Ethereum Improvement Proposals (EIPs & ERCs) describe standards for the Ethereum platform, such as core protocol changes and application-level standards. Zola 2026-02-11T14:49:28+00:00 https://wg-eips.ritovision.com/status/stagnant/atom.xml 2025-05-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Wei Tanghttps://github.com/sorpaas https://wg-eips.ritovision.com/7958/

Little endian opcodes `BYTE64`, `MLOAD64`, `MSTORE64`, and `PUSH*64` for EVM64

<h2 id="abstract">Abstract</h2> <p>This EIP defines additional little endian opcodes that can be deployed alongside <a href="https://wg-eips.ritovision.com/7937/">EIP-7937</a>.</p> <h2 id="motivation">Motivation</h2> <p>The core EIP that defines EVM64 (EIP-7937) is endianness-independent. This EIP defines those additional opcodes that must expose endianness. They are the bitwise opcode <code>BYTE64</code>, memory opcodes <code>MLOAD64</code> and <code>MSTORE64</code>, and stack opcodes <code>PUSH*64</code>.</p> <h2 id="specification">Specification</h2> <p>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>We define the following gas cost constant:</p> <ul> <li><code>G_VERYLOW64</code>: 2</li> </ul> <h3 id="byte64"><code>BYTE64</code></h3> <p><code>BYTE64</code> (0xc01a) is defined as <code>(x &gt;&gt; i * 8) &amp; 0xFF</code>. Note that the definition is changed from big endian to little endian.</p> <p>The gas cost is <code>G_VERYLOW64</code>.</p> <h3 id="mload64-and-mstore64"><code>MLOAD64</code> and <code>MSTORE64</code></h3> <p><code>MLOAD64</code> (0xc051) will load a 64-bit integer in little endian onto the stack. <code>MSTORE64</code> (0xc052) will read an 64-bit integer from the stack, and store it to memory in little endian.</p> <p>The gas cost for both opcodes is <code>G_VERYLOW64</code>. The memory resizing costs count as 8 bytes.</p> <p>As an example, <code>[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]</code> is an array of 8 bytes (64 bits). Calling <code>MLOAD64</code> to load this 8-byte value to stack will read it in little endian, resulting in 64-bit integer <code>0x0807060504030201</code>. 64-bit mode always operate on only the least significant 64 bits. When another 256-bit opcodes encounter this value on stack, it will be <code>0x00..00 0807060504030201</code>. Calling <code>MSTORE64</code> to store this value to memory will result in the array <code>[0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]</code>.</p> <h3 id="push-64"><code>PUSH*64</code></h3> <p><code>PUSH2_64</code> (0xc061) to <code>PUSH8_64</code> (0xc067) follows 2-byte to 8-byte literal. The literal is read little endian and pushed onto the stack.</p> <p>The gas cost for them is <code>G_VERYLOW64</code>.</p> <p>As an example, <code>0xc0 0x67 0x01 0x02 0x03 0x04 0x05 0x06 0x07 0x08</code> will result in a stack with single value <code>0x00..00 0807060504030201</code>.</p> <h2 id="rationale">Rationale</h2> <p>For detailed rationale discussion, please see the core EVM64 definition <a href="https://wg-eips.ritovision.com/7937/">EIP-7937</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>To be added.</p> <!-- TODO --> <h2 id="reference-implementation">Reference Implementation</h2> <p>To be added.</p> <!-- TODO --> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-04-27T00:00:00+00:00 2026-02-11T14:49:28+00:00 Dankrad Feisthttps://github.com/dankrad https://wg-eips.ritovision.com/7938/

Exponentially increase gas limit 100x over 4 years by setting a default for the client vote

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a deterministic gas limit growth schedule via client-side defaults. Ethereum clients will vote to increase the gas limit according to an exponential schedule unless explicitly configured otherwise by the user. The gas limit increase occurs every beacon chain epoch, aligned to a factor-of-10 increase every approximately 164,250 epochs (2 years). It will stop after 4 years when an updated gas increase schedule should be decided and committed to.</p> <h2 id="motivation">Motivation</h2> <p>The current gas limit mechanism relies on miner/operator voting, which lacks coordination and predictability. While flexible, this approach can lead to stagnation or overly cautious increases. By introducing a predictable exponential growth pattern as a client default, this EIP encourages a sustainable and transparent gas limit trajectory, aligned with expected advancements in hardware and protocol efficiency.</p> <h2 id="specification">Specification</h2> <h3 id="schedule">Schedule</h3> <p>Let <code>G0 = 50,000,000</code> be the gas limit at the activation epoch. Let the activation epoch be Ethereum beacon chain <strong>epoch 369017</strong>, which corresponds to approximately June 1, 2025.</p> <p>Let <code>t</code> be the current beacon chain epoch and <code>t0 = 369017</code> be the activation epoch. Let <code>T = 164,250</code> be the number of epochs for a 10x increase.</p> <p>The gas limit at epoch <code>t</code> is calculated as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>G(t) = {</span></span> <span class="giallo-l"><span> current default limit, if t &lt; t0</span></span> <span class="giallo-l"><span> round(G0 * 10^((t-t0)/T)), if t0 ≤ t ≤ t0 + 2*T</span></span> <span class="giallo-l"><span> 100 * G0, if t &gt; t0 + 2*T</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>round</code> should round to the next integer.</p> <h3 id="client-behavior">Client Behavior</h3> <ul> <li>At the start of each new beacon chain epoch, the default gas limit vote is recalculated using the formula above.</li> <li>Clients automatically vote for the calculated gas limit using the existing gas voting mechanism.</li> <li>Users can override this default by setting a manual gas limit policy in client configuration.</li> </ul> <h3 id="activation">Activation</h3> <ul> <li>Activation is at Ethereum beacon chain epoch 369017.</li> </ul> <h2 id="rationale">Rationale</h2> <p>This EIP maintains Ethereum's current gas voting mechanism but enhances it with a predictable and community-coordinated trajectory. By distributing responsibility across clients rather than enforcing protocol changes via consensus rules, this proposal offers flexibility while encouraging scalability.</p> <p>The exponential growth model ensures gradual but significant increases, allowing the network to adapt while targeting ambitious throughput goals.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The change is non-consensus and backward compatible. Clients not implementing the EIP will continue to behave as before. Only the default behavior changes; manual configuration remains supported.</p> <h2 id="security-considerations">Security Considerations</h2> <p>A rapid increase in the gas limit may stress less-optimized nodes and increase block propagation times. However, the exponential schedule with very gradual increments per epoch gives node operators and developers ample time to adapt and optimize.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-03-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Piper Merriamhttps://github.com/pipermerriam https://wg-eips.ritovision.com/7927/

Meta EIP for History Expiry changes happening in conjunction with Pectra

<h2 id="abstract">Abstract</h2> <p>This Meta-EIP documents the activation process and plan for history expiry as well as providing links to other EIPs that are related.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/4444/">EIP-4444</a> documents the motivation for history expiry itself.</p> <p>This EIP exists to document the process through which history expiry will be activated on mainnet, the testnet activation on Sepolia, devnet testing and other information surrounding history expiry that doesn't fit cleanly in any of the supporting EIPs.</p> <h2 id="specification">Specification</h2> <p>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>Execution layer client MUST implement <a href="https://wg-eips.ritovision.com/7642/">EIP-7642</a> to support the <code>eth/69</code> over DevP2P.</p> <p>Execution layer clients MAY drop pre-merge history according to <a href="https://wg-eips.ritovision.com/7639/">EIP-7639</a>.</p> <p>Consensus layer clients SHOULD NOT depend on Execution Layer clients having the deposit logs from pre-merge blocks and SHOULD implement <a href="https://wg-eips.ritovision.com/6110/">EIP-6110</a>.</p> <h3 id="mainnet-activation">Mainnet Activation</h3> <p>Mainnet activation of history expiry will occur shortly (a few days or weeks) after the activation of the <a href="https://wg-eips.ritovision.com/7600/">Pectra</a> hard fork. The short delay is to ensure that all deposit logs from before the fork have been processed before clients begin dropping history.</p> <h3 id="testnet-activation">Testnet Activation</h3> <p>Testing of history expiry will occur on the Sepolia testnet. Execution clients may begin dropping pre-merge Sepolia history on 2025-05-01.</p> <h3 id="devnet-activation">Devnet Activation</h3> <p>Execution clients may test dropping of history on devnets.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-wait-for-pectra">Why wait for Pectra</h3> <p>Consensus Layer clients have a dependency on pre-merge deposit logs. <a href="https://wg-eips.ritovision.com/6110/">EIP-6110</a> will remove this dependency when the Pectra fork is activated.</p> <h3 id="why-drop-sepolia-history">Why drop Sepolia history</h3> <p>The Sepolia history drop is intended as a testing ground for the mainnet activation.</p> <h3 id="why-drop-devnet-history">Why drop Devnet history</h3> <p>The Devnet history drop is intended to test prior to Sepolia to avoid any breakage on the Sepolia network.</p> <h3 id="won-t-this-break-json-rpc">Won't this break JSON-RPC</h3> <p>History Expiry doesn't require clients to remove this data. It only allows them to. Clients that wish to preserve this history in their client for JSON-RPC use cases are free to do so.</p> <h3 id="where-will-pre-merge-history-be-stored">Where will Pre-Merge history be stored</h3> <p>Pre-merge data is available in the e2store archival format. A public list of these archives can be found in the <code>eth-clients</code> historical data endpoints list which can be found on the <code>eth-clients</code> website.</p> <p>The Portal network also implements a decentralized peer-to-peer solution for storage and retrieval of all of Ethereum's pre-merge block data.</p> <p>The <a href="https://wg-eips.ritovision.com/7801/">EIP-7801</a> DevP2P protocol also provides a peer-to-peer solution for retrieval of this data.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="devp2p-eth-protocol">DevP2P <code>eth</code> protocol</h3> <p>Clients of the DevP2P <code>eth</code> protocol will need to upgrade to the new <code>eth/69</code> version specified in <a href="https://wg-eips.ritovision.com/7642/">EIP-7642</a></p> <h3 id="pre-merge-deposit-logs">Pre-Merge Deposit Logs</h3> <p>Consensus Layer clients have had a historical dependency on the deposit logs from pre-merge blocks. Dropping history would make these logs inaccessible to the Consensus Layer client. This issue is mitigated by <a href="https://wg-eips.ritovision.com/6110/">EIP-6110</a></p> <h3 id="serving-pre-merge-json-rpc">Serving Pre-Merge JSON-RPC</h3> <p>Execution clients that choose to drop history will no longer be capable of serving JSON-RPC requests for pre-merge requests for the following endpoints without sourcing the data from an alternate data source.</p> <ul> <li><code>eth_getBlockTransactionCountByHash</code></li> <li><code>eth_getBlockTransactionCountByNumber</code></li> <li><code>eth_getUncleCountByBlockHash</code></li> <li><code>eth_getUncleCountByBlockNumber</code></li> <li><code>eth_getBlockByHash</code></li> <li><code>eth_getBlockByNumber</code></li> <li><code>eth_getTransactionByHash</code></li> <li><code>eth_getTransactionByBlockHashAndIndex</code></li> <li><code>eth_getTransactionByBlockNumberAndIndex</code></li> <li><code>eth_getTransactionReceipt</code></li> <li><code>eth_getUncleByBlockHashAndIndex</code></li> <li><code>eth_getUncleByBlockNumberAndIndex</code></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="full-history-sync">Full History Sync</h3> <p>Execution layer clients will no longer be able to implement a full historical sync of history from the DevP2P <code>eth</code> protocol. Clients that wish to retain this functionality will need to source the pre-merge blocks from an alternate source. Clients SHOULD ensure that they continue to correctly validate block data sourced from alternate locations.</p> <h3 id="partial-history-sync">Partial History Sync</h3> <p>Execution layer clients that do a partial sync will need to adjust their syncing algorithms to only go back to the merge block as opposed to the previous behavior of tracing all the way back to genesis. Clients SHOULD ensure that their sync algorithms and other functionality are able to handle this data no longer being locally available.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-03-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/7921/

All `JUMPDEST` bytes become valid `JUMPDEST`

<h2 id="abstract">Abstract</h2> <p>Allow <code>JUMP</code> and <code>JUMPI</code> to arrive at any byte matching <code>JUMPDEST</code> (<code>0x5b</code>), even if that byte is an immediate argument.</p> <h2 id="motivation">Motivation</h2> <p>Immediate arguments are opcode parameters supplied within the code rather than the stack. Currently determining the validity of a <code>JUMPDEST</code> requires determining which bytes are immediate arguments to other opcodes, such as <code>PUSH1</code>. This presents several problems:</p> <ol> <li>Codesize is a linear DoS vector because code must be preprocessed to determine <code>JUMPDEST</code> validity.</li> <li>New opcodes with immediate arguments cannot be safely adopted.</li> <li><code>CODECOPY</code> data spans can invalidate subsequent <code>JUMPDEST</code>.</li> </ol> <p>The rationale for this <code>JUMPDEST</code> validity check is to prevent unintended code execution. However, almost all <code>JUMP</code> and <code>JUMPI</code> target constant destinations. Removing this check allows larger programs and better opcodes. Therefore, the cost of this safety check outweighs the benefit.</p> <h2 id="specification">Specification</h2> <p>When activated, all <code>0x5b</code> bytes are valid <code>JUMPDEST</code> for <code>JUMPI</code> and <code>JUMP</code> opcodes.</p> <h2 id="rationale">Rationale</h2> <p>Removing the check solves several problems while reducing EVM complexity.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Code previously only had one interpretation for disassembly. With this change, a <code>JUMPDEST</code> located inside an immediate argument can cause multiple disassembly interpretations. Usually the interpretations will converge after a few bytes but the length of such a dispute can be unbounded. <code>CODECOPY</code> data has always been difficult to identify. It is recommended that disassemblers provide all possible interpretations in their output in order to reveal possible underhanded functionality.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Current contracts performing dynamic jumps may gain new unintended functionality if it is possible to jump to an immediate argument containing <code>JUMPDEST</code>. It is expected that very few contracts will become vulnerable in this way. Most smart contract programming languages do not even allow dynamic jumps, and of those that do, few will have <code>JUMPDEST</code> in an accessible immediate argument. Therefore it is expected that few contracts will become vulnerable, and for many of them the newly possible codepaths will contain invalid opcodes. A static analysis tool should be developed and made publicly available to test if a contract might become vulnerable, and the program should be run for all current contracts in order to notify projects about potential security issues. Affected programs will have ample time to migrate.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-03-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 lightclienthttps://github.com/lightclient https://wg-eips.ritovision.com/7912/

Add additional SWAP and DUP operations for deeper stack access

<h2 id="abstract">Abstract</h2> <p>Add <code>SWAP17</code>-<code>SWAP24</code>, <code>DUP17</code> - <code>DUP24</code>, <code>SWAPN</code>, <code>DUPN</code>, and <code>EXCHANGE</code> instructions. The arbitrary depth operations must be preceded by <code>PUSH1</code> instructions defining operands.</p> <h2 id="motivation">Motivation</h2> <p>Due to the nature of some compilers, deeper stack access is a desirable VM feature. Previous attempts either required code versioning, like the EVM Object Format (EOF), or caused the behavior of some deployed contracts to change, due to the interpretation of new immediates.</p> <p>This is a pragmatic approach to introducing the desired functionality. It reuses instruction semantics that have been historically agreed on, instead of new, complex encodings and containers.</p> <h2 id="specification">Specification</h2> <p>Let <code>top - N</code> be the <code>N</code>th most recently pushed value on the stack, and <code>top - 0</code> be the most recent.</p> <p>If any of the following instructions reference a stack element beyond the current length of the stack, causing a stack underflow, abort with an exceptional halt.</p> <h3 id="constant-swapxx-and-dupxx">Constant <code>SWAPXX</code> and <code>DUPXX</code></h3> <p>Add the following new instructions:</p> <ul> <li><code>SWAP17</code>, <code>SWAP18</code>, ..., <code>SWAP24</code>: <code>0xb0</code>, <code>0xb1</code>, ..., <code>0xb7</code>.</li> <li><code>DUP17</code>, <code>DUP18</code>, ..., <code>DUP24</code>: <code>0xb8</code>, <code>0xba</code>, ..., <code>0xbf</code>.</li> </ul> <p>Let <code>SWAPXX</code> and <code>DUPXX</code> refer to the static instructions defined above. <code>XX</code> is defined as the stack element they are referencing.</p> <p>The operation <code>SWAPXX</code> swaps the top element with the <code>top-XX</code> element. The operation <code>DUPXX</code> duplicates the <code>top-XX</code> element and pushes the copy to the top of the stack.</p> <h3 id="swapn-and-dupn"><code>SWAPN</code> and <code>DUPN</code></h3> <p>Add the following new instructions:</p> <ul> <li><code>SWAPN</code>: <code>0xc0</code>.</li> <li><code>DUPN</code>: <code>0xc1</code>.</li> </ul> <p>Both operations take a single argument from the stack, <code>N</code>. This argument must be provided by a <code>PUSH1</code> operation immediately preceding the <code>SWAPN</code> and <code>DUPN</code> instructions. Failure to follow this calling convention will result in an out-of-gas error. If <code>N</code> is zero, fail with out-of-gas error.</p> <p><code>SWAPN</code> pops <code>N</code> from the stack and swaps the new top stack element with the <code>top-N</code> stack element.</p> <p><code>DUPN</code> pops <code>N</code> from the stack and push on a copy of the <code>top-N-1</code> stack element.</p> <h3 id="exchange"><code>EXCHANGE</code></h3> <p>Add the following new instruction:</p> <ul> <li><code>EXCHANGE</code>: <code>0xc2</code>.</li> </ul> <p>The <code>EXCHANGE</code> instruction takes a single argument from the stack <code>X</code> and deconstructs it into two operands, <code>N</code> and <code>M</code>. <code>N</code> is <code>X &gt;&gt; 4</code> and <code>M</code> is <code>X &amp; 0x0F</code>. The argument <code>X</code> must be provided by a <code>PUSH2</code> operation immediately preceding the <code>EXCHANGE</code> instruction. Failure to follow this calling convention will result in an out-of-gas error. If either <code>N</code> or <code>M</code> are zero, fail with out-of-gas error.</p> <p><code>EXCHANGE</code> pops <code>X</code> from the stack and will swap the stack element at index <code>N-1</code> with the stack element at <code>M-1</code>.</p> <h3 id="gas-costs">Gas costs</h3> <p>All operations cost <code>3</code> gas. Preceding push operations are charged separately according to the gas schedule.</p> <h2 id="rationale">Rationale</h2> <h3 id="constant-and-dynamic-swaps-and-dups">Constant and Dynamic <code>SWAP</code>s and <code>DUP</code>s</h3> <p>The main trade off between using the constant <code>SWAPXX</code> or <code>DUPXX</code> instructions versus the dynamic <code>SWAPN</code> or <code>DUPN</code> instructions is that the dynamic instructions require an additional two bytes in the form of a preceding <code>PUSH1</code> operation, whereas the constant versions require no additional bytes.</p> <h3 id="one-indexed-exchange">One indexed <code>EXCHANGE</code></h3> <p>Since <code>SWAP1</code> and <code>DUP1</code> operate on the top of the stack, it seems fitting that <code>EXCHANGE(1, 2)</code> operate on the <code>top</code> and <code>top-1</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO</p> <h2 id="security-considerations">Security Considerations</h2> <p>When verifying the preceding <code>PUSH</code> operations, client implementers must ensure that the preceding bytes are not part of a longer segment of push data (e.g. <code>0x6301026001b0</code> should error). This can be done efficiently by checking if <code>pc-2</code> is a valid jump destination. If it is, then the <code>PUSH</code> instruction will have been executed as expected.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-03-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mikhail Kalininhttps://github.com/mkalinin Mike Neuderhttps://github.com/michaelneuder Mallesh Paihttps://github.com/Mmp610 https://wg-eips.ritovision.com/7922/

Update the validator exit process by dynamically adjusting the churn limit based on historical validator exits.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes updating Ethereum's validator exit churn calculation by dynamically adjusting the churn limit at the start of each 256-epoch period ("generation") based on historical validator exits. Specifically, the maximum churn allowed in each generation will adjust according to the unused churn from the past 16 generations. This approach reduces validator wait times during periods of high exit demand <em>without sacrificing network safety</em>.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum currently implements a fixed, rate-limited queue for validator exits to ensure the security and stability of the network. The exit queue ensures the economic security of transactions finalized by the validator set. Suppose a malicious validator could immediately exit the set without any delay. In that case, they may attempt to execute a double spend attack by publishing a block while withholding a conflicting block, which they release after their stake has exited the protocol. The slashing mechanism can no longer hold the malicious validator accountable, and two conflicting finalized transactions may exist (if the attacker has 1/3 of the total stake and successfully splits the 2/3 honest majority in half).</p> <p>The <code>CHURN_LIMIT_QUOTIENT=2^16</code> was selected according to the rough heuristic that it should take approximately one month for 10% of the stake to exit. With 1,053,742 validators, we have a churn limit of 16 exits per epoch. 225 epochs per day $\implies$ 3600 exits per day $\implies$ 108,000 exits per 30 days. Then 108,000/1,053,742 $\approx$ 0.10. We can interpret this as "<em>the economic security of a finalized transaction decreases by no more than 10% within one month</em>."</p> <p>Another way of understanding the 16 exits per epoch security model is that it encodes the following constraints around validator exits:</p> <ol> <li>at most 16 validators exit in the next one epoch, and</li> <li>at most 32 validators exit in the next two epochs, and</li> <li>at most 48 validators exit in the next three epochs, and ...</li> <li>at most 16 $\cdot$ n validators exit in the next n epochs.</li> </ol> <p>While these constraints are simple to understand, the fixed per-epoch churn limit can result in unnecessarily long validator withdrawal delays during periods of higher-than-average exit demand, such as during institutional liquidations or market events. We argue that we should choose a <em>single</em> constraint from the above set and implement that flexibly.</p> <p>We illustrate this with an example. With one million validators, the current protocol specifies that 16 validators may exit per epoch. Over two weeks, this corresponds to 50,400 exits. This translates directly to "no more than 5.04% of the validators (equiv. stake) can exit within two weeks." Now imagine that in the past 13 days, no validators have exited the protocol, and thus, none of the two-week churn limit has been used. If a large staking operator with 3% of the validator set (30,000 validators) seeks to withdraw immediately, they should be able to -- this doesn't violate the two-week limit of 5.04%. However, since only 16 exits can be processed per epoch moving forward, they are forced to wait 1875 epochs (equiv. 8.33 days).</p> <blockquote> <p><strong>Key observation:</strong> If we enable the protocol to <em>look backward</em> at the exit history, we no longer need the per-epoch limit <em>looking forward</em>.</p> </blockquote> <p>For example, say we chose the following constraint explicitly:</p> <blockquote> <p><strong>Proposed weak subjectivity constraint:</strong> <em>No more than 50,400 exits in two weeks.</em></p> </blockquote> <p>Then, we only need to ensure that the constraint is honored over every rolling two-week window without setting a hard cap on exits during every epoch. A dynamically adjusted churn limit based on historical validator exit data allows Ethereum to flexibly accommodate spikes in exit demand while <em>preserving the same security over every two-week window</em>. By tracking the unused churn capacity of recent generations (periods), we can safely increase the churn limit when the network consistently operates below capacity, significantly improving the validator exit experience.</p> <h2 id="specification">Specification</h2> <p>Since the validator exit process is complex, we start with the stack trace and a verbal description of the end-to-end process in Electra.</p> <ol> <li><code>initiate_validator_exit</code> – a validator signals their intent to exit, which is actuated by setting <code>validator.exit_epoch</code> and <code>validator.withdrawable_epoch</code> based on the output of <code>compute_exit_epoch_and_update_churn</code>.</li> <li><code>compute_exit_epoch_and_update_churn</code> – is used to determine the exit epoch of a validator. This function implements the exit queue in the following way: <ul> <li><code>get_balance_churn_limit</code> - returns the amount of withdrawable ETH per epoch by dividing the total active balance by 2**16.</li> <li>set <code>exit_balance_to_consume</code> to the churn available in the current furthest epoch where some exits will be processed.</li> <li>if <code>exit_balance &gt; exit_balance_to_consume</code>, then we calculate the number of extra epochs the exit consumes to set the final <code>exit_epoch</code>.</li> </ul> </li> </ol> <p>This EIP changes how the churn limit and exit epochs are calculated by examining the number of exits in the previous 14 generations.</p> <ol> <li><code>get_exit_churn_limit</code> – implements the new churn limit calculation by summing over historical generations. <ul> <li><code>per_epoch_exit_churn</code> is set using <code>get_activation_exit_churn_limit</code> as today by dividing the total stake by 2**16 and capping the result at 256 ETH. With today's numbers, this returns 256 ETH that can churn per epoch.</li> <li><code>per_generation_exit_churn</code> is set by multiplying the per epoch exit churn by 256 (the number of epochs in a generation). With today's numbers, this is 256 $\cdot$ 256 = 65536 ETH that can churn per generation.</li> <li><code>total_unused_exit_churn</code> is calculated by looping through the past generations and summing the amount of unused capacity, <code>per_generation_exit_churn - churn_usage</code>.</li> <li>The final returned value is capped at <code>per_epoch_exit_churn * 8</code>. With today's numbers, this max is 256 $\cdot$ 8 = 2048 ETH per epoch.</li> </ul> </li> <li><code>compute_exit_epoch_and_update_churn</code> – is modified to use <code>get_exit_churn_limit</code> and account for any churn consumed in the generation where the exit will be processed.</li> </ol> <h3 id="definitions">Definitions</h3> <ul> <li><strong>Generation</strong>: A period consisting of 256 epochs.</li> <li><strong>Historical Churn Vector</strong>: A fixed-size array (<code>exit_churn_vector</code>) that records the total amount of churned ETH in the previous 16 generations.</li> <li><strong>Unused Churn</strong>: The difference between the maximum possible churn and the actual churn that occurred within a generation.</li> </ul> <h3 id="preset">Preset</h3> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>EPOCHS_PER_CHURN_GENERATION</code></td><td><code>uint64(2**8)</code> (= 256)</td><td>~27 hours</td></tr> <tr><td><code>GENERATIONS_PER_EXIT_CHURN_VECTOR</code></td><td><code>uint64(2**4)</code> (= 16)</td><td>~18 days</td></tr> <tr><td><code>GENERATIONS_PER_EXIT_CHURN_LOOKAHEAD</code></td><td><code>uint(2**1)</code> (= 2)</td><td></td></tr> <tr><td><code>EXIT_CHURN_SLACK_MULTIPLIER</code></td><td><code>uint(2**3)</code> (= 8)</td><td></td></tr> </tbody></table> <h3 id="new-state-variables">New State Variables</h3> <p>Add the following to the state:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>exit_churn_vector</span><span>:</span><span> Vector</span><span>[</span><span>uint64</span><span>,</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_VECTOR</span><span>]</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> total exited balance per generation for GENERATIONS_PER_EXIT_CHURN_VECTOR generations</span></span></code></pre><h3 id="initialization">Initialization</h3> <p>Upon activation of this EIP, initialize new variables:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Mark the churn of each generation as fully consumed</span></span> <span class="giallo-l"><span>state</span><span>.</span><span>exit_churn_vector</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">UINT64_MAX</span><span>]</span><span class="z-keyword"> *</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_VECTOR</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Update lookahead generations</span></span> <span class="giallo-l"><span>earliest_exit_epoch_generation</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>earliest_exit_epoch</span><span class="z-keyword"> //</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"><span>current_epoch_generation</span><span class="z-keyword"> =</span><span> get_current_epoch</span><span>(</span><span>state</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"><span>lookahead_generation</span><span class="z-keyword"> =</span><span> current_epoch_generation</span><span class="z-keyword"> +</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_LOOKAHEAD</span></span> <span class="giallo-l"><span class="z-keyword">for</span><span> generation</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>current_epoch_generation</span><span>,</span><span> lookahead_generation</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> earliest_exit_epoch_generation</span><span class="z-keyword"> &lt;</span><span> generation</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>exit_churn_vector</span><span>[</span><span>generation</span><span class="z-keyword"> %</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_VECTOR</span><span>]</span><span class="z-keyword"> =</span><span> uint64</span><span>(</span><span class="z-constant">0</span><span>)</span></span></code></pre> <p><em>Design note:</em> Max out churn usage for the past generations as it is unknown; update the current and lookahead generations according to the <code>state.earliest_exit_epoch</code> generation.</p> <h3 id="new-functions">New Functions</h3> <h4 id="epoch-processing">Epoch Processing</h4> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> process_historical_exit_churn_vector</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> BeaconState</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> current_epoch</span><span class="z-keyword"> =</span><span> get_current_epoch</span><span>(</span><span>state</span><span>)</span></span> <span class="giallo-l"><span> next_epoch</span><span class="z-keyword"> =</span><span> current_epoch</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> current_epoch_generation</span><span class="z-keyword"> =</span><span> current_epoch</span><span class="z-keyword"> //</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"><span> earliest_exit_epoch_generation</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>earliest_exit_epoch</span><span class="z-keyword"> //</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> next_epoch_generation</span><span class="z-keyword"> =</span><span> next_epoch</span><span class="z-keyword"> //</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Update the vector if switching over to the next generation.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> next_epoch_generation</span><span class="z-keyword"> &gt;</span><span> current_epoch_generation</span><span>:</span></span> <span class="giallo-l"><span> lookahead_generation</span><span class="z-keyword"> =</span><span> next_epoch_generation</span><span class="z-keyword"> +</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_LOOKAHEAD</span></span> <span class="giallo-l"><span> lookahead_generation_index</span><span class="z-keyword"> =</span><span> lookahead_generation</span><span class="z-keyword"> %</span><span class="z-constant"> GENERATIONS_PER_HISTORICAL_CHURN_VECTOR</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> earliest_exit_epoch_generation</span><span class="z-keyword"> &lt;</span><span> lookahead_generation</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If earliest_exit_epoch is earlier than the lookahead generation,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> reset its churn usage to 0,</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>exit_churn_vector</span><span>[</span><span>lookahead_generation_index</span><span>]</span><span class="z-keyword"> =</span><span> uint64</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> otherwise, mark the lookahead generation churn as fully consumed.</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>historical_exit_churn_vector</span><span>[</span><span>lookahead_generation_index</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> UINT64_MAX</span></span></code></pre> <p><em>Design note</em>: This function resets the lookahead generation churn upon switching to the next generation. If <code>state.earliest_exit_epoch</code> falls into the generation earlier than the lookahead, the lookahead generation churn usage is reset. Otherwise, it is marked as fully used.</p> <h4 id="get-exit-churn-limit"><code>get_exit_churn_limit</code></h4> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> get_exit_churn_limit</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> BeaconState</span><span>)</span><span> -&gt;</span><span> Gwei</span><span>:</span></span> <span class="giallo-l"><span> current_epoch</span><span class="z-keyword"> =</span><span> get_current_epoch</span><span>(</span><span>state</span><span>)</span></span> <span class="giallo-l"><span> earliest_exit_epoch</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>state</span><span>.</span><span>earliest_exit_epoch</span><span>,</span><span> compute_activation_exit_epoch</span><span>(</span><span>get_current_epoch</span><span>(</span><span>state</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> per_epoch_exit_churn</span><span class="z-keyword"> =</span><span> get_activation_exit_churn_limit</span><span>(</span><span>state</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If the earliest_exit_epoch generation is beyond the lookahead,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> don&#39;t use the slack.</span></span> <span class="giallo-l"><span> current_generation</span><span class="z-keyword"> =</span><span> current_epoch</span><span class="z-keyword"> //</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"><span> lookahead_generation</span><span class="z-keyword"> =</span><span> current_generation</span><span class="z-keyword"> +</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_LOOKAHEAD</span></span> <span class="giallo-l"><span> earliest_exit_epoch_generation</span><span class="z-keyword"> =</span><span> earliest_exit_epoch</span><span class="z-keyword"> //</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> earliest_exit_epoch_generation</span><span class="z-keyword"> &gt;</span><span> lookahead_generation</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> per_epoch_exit_churn</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Compute churn leftover from past generations.</span></span> <span class="giallo-l"><span> past_generations</span><span class="z-keyword"> =</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_VECTOR</span><span class="z-keyword"> -</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_LOOKAHEAD</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> current_generation</span><span class="z-keyword"> &gt;</span><span> past_generations</span><span>:</span></span> <span class="giallo-l"><span> oldest_generation</span><span class="z-keyword"> =</span><span> current_generation</span><span class="z-keyword"> -</span><span> past_generations</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> oldest_generation</span><span class="z-keyword"> =</span><span> uint64</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> per_generation_exit_churn</span><span class="z-keyword"> =</span><span> per_epoch_exit_churn</span><span class="z-keyword"> *</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"><span> total_unused_exit_churn</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> generation</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>oldest_generation</span><span>,</span><span> current_generation</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> generation_index</span><span class="z-keyword"> =</span><span> generation</span><span class="z-keyword"> %</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_VECTOR</span></span> <span class="giallo-l"><span> churn_usage</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>exit_churn_vector</span><span>[</span><span>generation_index</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> churn_usage</span><span class="z-keyword"> &lt;</span><span> per_generation_exit_churn</span><span>:</span></span> <span class="giallo-l"><span> total_unused_exit_churn</span><span class="z-keyword"> +=</span><span> per_generation_exit_churn</span><span class="z-keyword"> -</span><span> churn_usage</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Limit churn slack per epoch.</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> max</span><span>(</span><span>total_unused_exit_churn</span><span class="z-keyword"> +</span><span> per_epoch_exit_churn</span><span>,</span></span> <span class="giallo-l"><span> per_epoch_exit_churn</span><span class="z-keyword"> *</span><span class="z-constant"> EXIT_CHURN_SLACK_MULTIPLIER</span><span>)</span></span></code></pre> <p><em>Design note:</em> Given churn usage for past generations and current epoch churn size estimates the churn leftover from past generations. Caps the returned churn at <code>per_epoch_exit_churn * EXIT_CHURN_SLACK_MULTIPLIER</code>.</p> <h3 id="modified-functions">Modified Functions</h3> <p>Replace the existing <code>compute_exit_epoch_and_update_churn</code> function with this simplified MINSLACK-inspired version:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> compute_exit_epoch_and_update_churn</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> BeaconState</span><span>,</span><span class="z-variable z-parameter z-function"> exit_balance</span><span>:</span><span> Gwei</span><span>)</span><span> -&gt;</span><span> Epoch</span><span>:</span></span> <span class="giallo-l"><span> earliest_exit_epoch</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>state</span><span>.</span><span>earliest_exit_epoch</span><span>,</span><span> compute_activation_exit_epoch</span><span>(</span><span>get_current_epoch</span><span>(</span><span>state</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Modified in [EIP-XXXX]</span></span> <span class="giallo-l"><span> per_epoch_churn</span><span class="z-keyword"> =</span><span> get_exit_churn_limit</span><span>(</span><span>state</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> New epoch for exits.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> state</span><span>.</span><span>earliest_exit_epoch</span><span class="z-keyword"> &lt;</span><span> earliest_exit_epoch</span><span>:</span></span> <span class="giallo-l"><span> exit_balance_to_consume</span><span class="z-keyword"> =</span><span> per_epoch_churn</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> exit_balance_to_consume</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>exit_balance_to_consume</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Exit doesn&#39;t fit in the current earliest epoch.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> exit_balance</span><span class="z-keyword"> &gt;</span><span> exit_balance_to_consume</span><span>:</span></span> <span class="giallo-l"><span> balance_to_process</span><span class="z-keyword"> =</span><span> exit_balance</span><span class="z-keyword"> -</span><span> exit_balance_to_consume</span></span> <span class="giallo-l"><span> additional_epochs</span><span class="z-keyword"> =</span><span> (</span><span>balance_to_process</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> //</span><span> per_epoch_churn</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> earliest_exit_epoch</span><span class="z-keyword"> +=</span><span> additional_epochs</span></span> <span class="giallo-l"><span> exit_balance_to_consume</span><span class="z-keyword"> +=</span><span> additional_epochs</span><span class="z-keyword"> *</span><span> per_epoch_churn</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Consume the balance and update state variables.</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>exit_balance_to_consume</span><span class="z-keyword"> =</span><span> exit_balance_to_consume</span><span class="z-keyword"> -</span><span> exit_balance</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>earliest_exit_epoch</span><span class="z-keyword"> =</span><span> earliest_exit_epoch</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> New in [EIP-XXXX]</span></span> <span class="giallo-l"><span> current_epoch_generation</span><span class="z-keyword"> =</span><span> current_epoch</span><span class="z-keyword"> //</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"><span> exit_epoch_generation</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>earliest_exit_epoch</span><span class="z-keyword"> //</span><span class="z-constant"> EPOCHS_PER_CHURN_GENERATION</span></span> <span class="giallo-l"><span> current_generation_index</span><span class="z-keyword"> =</span><span> current_epoch_generation</span><span class="z-keyword"> %</span><span class="z-constant"> GENERATIONS_PER_HISTORICAL_CHURN_VECTOR</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Record churn usage only if exit falls into the lookahead period</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> and the exit epoch generation churn isn&#39;t fully used.</span></span> <span class="giallo-l"><span> lookahead_generation</span><span class="z-keyword"> =</span><span> current_epoch_generation</span><span class="z-keyword"> +</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_LOOKAHEAD</span></span> <span class="giallo-l"><span> exit_epoch_generation_index</span><span class="z-keyword"> =</span><span> exit_epoch_generation</span><span class="z-keyword"> %</span><span class="z-constant"> GENERATIONS_PER_EXIT_CHURN_VECTOR</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>exit_epoch_generation</span><span class="z-keyword"> &lt;=</span><span> lookahead_generation</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> state</span><span>.</span><span>historical_exit_churn_vector</span><span>[</span><span>exit_epoch_generation_index</span><span>]</span><span class="z-keyword"> &lt;</span><span class="z-constant"> UINT64_MAX</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>exit_churn_vector</span><span>[</span><span>exit_epoch_generation_index</span><span>]</span><span class="z-keyword"> +=</span><span> exit_balance</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> state</span><span>.</span><span>earliest_exit_epoch</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>As we described earlier, by computing unused churn from the previous 14 generations, the churn limit dynamically responds to actual validator behavior. This mechanism:</p> <ul> <li>Reduces validator waiting times during periods of congestion.</li> <li>Ensures security by restricting maximum churn limit increases.</li> <li>Simplifies implementation compared to more complex dynamic mechanisms.</li> </ul> <p>A generation length of 256 epochs (~27 hours) and a history of 14 generations (~16 days) balances responsiveness and stability, enabling Ethereum to adapt smoothly to sustained changes in validator exit behavior.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Validator exit constraints remain crucial for Ethereum's accountable safety. This proposal maintains the core safety guarantee by strictly limiting the increase of the churn limit.</li> <li>The maximum churn limit is capped at eight times the current fixed churn, ensuring safety assumptions hold even in worst-case scenarios.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> 2025-03-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Anders Elowssonhttps://github.com/anderselowsson https://wg-eips.ritovision.com/7915/

Fee schedule accounting for the long-run average to quickly restore equilibrium under inelastic demand

<h2 id="abstract">Abstract</h2> <p>Reworks the excess blob gas update in <code>calc_excess_blob_gas()</code> so that the blob base fee rises relatively more during high gas usage than it falls during low usage whenever the current fee is below the long-run average. This establishes a smoothly adapting, neutral lower bound for the base fee. The exponential moving average (EMA) is computed in the linear domain and stored as a header variable.</p> <h2 id="motivation">Motivation</h2> <p>Demand for blobspace is fee-inelastic, leading to a blob base fee that may fluctuate excessively with minor shifts in aggregate demand. The lower end of the fee range of 1 wei is under current circumstances economically inconsequential, but can be reached after a period of blocks consuming fewer blobs than the target. During increases in demand, the existing fee mechanism requires sustained periods of near-full blocks to re-establish equilibrium. This exacerbates spikiness in resource consumption, which can hamper efficient scaling of throughput. Furthermore, users may intermittently need to compete in a first-price auction for inclusion, degrading UX. The appropriate fee range will inadvertently vary going forward due to changes in the ETH token price and circulating supply, as well as the protocol's ability to scale throughput. To remain neutral and future-proof, the operational range should be established relative to the long-run average fee, smoothly affecting the equilibrium quantity of blobs consumed. Thus, this EIP introduces a new fee update mechanism that accounts for the long-run average fee when responding to shifts in demand. This allows the protocol to quickly converge to desirable equilibria while also remaining neutral and future-proof.</p> <p><img src="https://wg-eips.ritovision.com/7915/./assets/1.png" alt="Figure 1" /></p> <p><strong>Figure 1.</strong> Response to various blob quantities for the proposed fee mechanism (green), the current mechanism (black), and the threshold mechanism of <a href="https://wg-eips.ritovision.com/7762/">EIP-7762</a> (red). The proposed mechanism smoothly converges to appropriate equilibria when demand shifts, establishing the fee relative to the long-run average base fee $\bar{f}_g$ (at 4 gwei in this example). The fee adapts faster when converging toward $\bar{f}_g$ from below than when diverging from it.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th><th>Short description</th></tr></thead><tbody> <tr><td><code>EMA_DECAY</code></td><td><code>2**18</code></td><td>Reciprocal of the EMA decay rate (per slot)</td></tr> <tr><td><code>MEAN_REVERSION_DEADBAND</code></td><td><code>64</code></td><td>Fee ratio at which mean reversion effect accelerates</td></tr> <tr><td><code>MEAN_REVERSION_FULLBAND</code></td><td><code>10**6</code></td><td>Fee ratio at which mean reversion effect stops increasing</td></tr> </tbody></table> <h3 id="functions">Functions</h3> <p>The function <code>calc_excess_blob_gas()</code> from <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> is updated. A mean reversion weight <code>w</code> is computed based on the ratio between the long-run base fee and the current base fee. The weight influences the excess gas update by smoothly increasing the gas used and decreasing the gas target as the current base fee falls below the long-run base fee (see Figure 2 below). The variable <code>Up</code> upsamples <code>w</code> to retain precision. Note that the function applies <code>integer_squareroot()</code>, which must be implemented at the execution layer; it is currently implemented at the consensus layer. Thresholding at <code>MEAN_REVERSION_FULLBAND</code> and strategic deployment of <code>Up</code> allows the mechanism to rely on the <code>uint64</code> type internally.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> calc_excess_blob_gas</span><span>(</span><span class="z-variable z-parameter z-function">parent</span><span>:</span><span> Header</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> parent</span><span>.</span><span>excess_blob_gas</span><span class="z-keyword"> +</span><span> parent</span><span>.</span><span>blob_gas_used</span><span class="z-keyword"> &lt;</span><span class="z-constant"> TARGET_BLOB_GAS_PER_BLOCK</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Compute upsampled mean reversion weight w based on the EMA fee ratio</span></span> <span class="giallo-l"><span> Up</span><span class="z-keyword"> =</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">16</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> get_base_fee_per_blob_gas</span><span>(</span><span>parent</span><span>)</span><span class="z-keyword"> &gt;</span><span> parent</span><span>.</span><span>base_fee_per_blob_gas_ema</span><span>:</span></span> <span class="giallo-l"><span> w</span><span class="z-keyword"> =</span><span> Up</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> parent</span><span>.</span><span>base_fee_per_blob_gas_ema</span><span class="z-keyword"> //</span><span> get_base_fee_per_blob_gas</span><span>(</span><span>parent</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> MEAN_REVERSION_FULLBAND</span><span>:</span></span> <span class="giallo-l"><span> ratio</span><span class="z-keyword"> =</span><span> Up</span><span class="z-keyword"> *</span><span class="z-constant"> MEAN_REVERSION_FULLBAND</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> ratio</span><span class="z-keyword"> =</span><span> Up</span><span class="z-keyword"> *</span><span> parent</span><span>.</span><span>base_fee_per_blob_gas_ema</span><span class="z-keyword"> //</span><span> get_base_fee_per_blob_gas</span><span>(</span><span>parent</span><span>)</span></span> <span class="giallo-l"><span> w</span><span class="z-keyword"> =</span><span> (</span><span>ratio</span><span class="z-keyword"> +</span><span> Up</span><span class="z-keyword"> *</span><span class="z-constant"> MEAN_REVERSION_DEADBAND</span><span>)</span><span class="z-keyword"> //</span><span> (</span><span class="z-constant">MEAN_REVERSION_DEADBAND</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> _</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span class="z-constant">3</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> w</span><span class="z-keyword"> =</span><span> integer_squareroot</span><span>(</span><span>w</span><span class="z-keyword"> *</span><span> Up</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Return excess blob gas based on adjusted gas usage and target under mean reversion</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> parent</span><span>.</span><span>excess_blob_gas</span><span class="z-keyword"> +</span><span> parent</span><span>.</span><span>blob_gas_used</span><span class="z-keyword"> *</span><span> w</span><span class="z-keyword"> //</span><span> Up</span><span class="z-keyword"> -</span><span class="z-constant"> TARGET_BLOB_GAS_PER_BLOCK</span><span class="z-keyword"> *</span><span> Up</span><span class="z-keyword"> //</span><span> w</span></span></code></pre> <p>The exponential moving average (EMA) of the base fee is updated based on the previous block's <code>base_fee_per_blob_gas</code> and <code>base_fee_per_blob_gas_ema</code> in a new function:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> calc_base_fee_per_blob_gas_ema</span><span>(</span><span class="z-variable z-parameter z-function">parent</span><span>:</span><span> Header</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> parent</span><span>.</span><span>base_fee_per_blob_gas_ema</span><span class="z-keyword"> +</span></span> <span class="giallo-l"><span> get_base_fee_per_blob_gas</span><span>(</span><span>parent</span><span>)</span><span class="z-keyword"> //</span><span class="z-constant"> EMA_DECAY</span><span class="z-keyword"> -</span></span> <span class="giallo-l"><span> parent</span><span>.</span><span>base_fee_per_blob_gas_ema</span><span class="z-keyword"> //</span><span class="z-constant"> EMA_DECAY</span></span></code></pre><h3 id="header-extension">Header extension</h3> <p>The current header encoding is extended with the <code>uint</code> field <code>base_fee_per_blob_gas_ema</code>. For the first post-fork block, <code>parent.base_fee_per_blob_gas_ema</code> is evaluated as <code>4*10**9</code> (4 gwei).</p> <h3 id="execution-layer-validation">Execution layer validation</h3> <p>The block validity conditions on the execution layer are extended to assert that <code>base_fee_per_blob_gas_ema</code> was correctly updated:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check that the base fee per blob gas EMA was updated correctly</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> block</span><span>.</span><span>header</span><span>.</span><span>base_fee_per_blob_gas_ema</span><span class="z-keyword"> ==</span><span> calc_base_fee_per_blob_gas_ema</span><span>(</span><span>block</span><span>.</span><span>parent</span><span>.</span><span>header</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="supply-and-demand">Supply and demand</h3> <p>Since the introduction of blobs, the reservation fee of the marginal consumer of blobs has periodically been very low. Whenever demand picks up, a sustained succession of near-full blocks is required to restore equilibrium, with the mechanism intermittently resorting to a first-price auction, considered a worse UX by blob consumers. The resulting spikiness in resource consumption is suboptimal for scaling blobspace. At a fundamental level, the issue is that Ethereum faces a fee-inelastic demand curve while operating a perfectly inelastic supply curve—with supply fixed at <code>TARGET_BLOB_GAS_PER_BLOCK</code>. When an equilibrium forms between fee-inelastic supply and demand curves, even a small shift in aggregate demand can lead to huge shifts in the equilibrium fee. This proposal smoothly increases the elasticity of the supply curve as it diverges from the long-run average, restricting the equilibrium fee from forming much below the average. Combined with the faster fee adjustments in the direction of the average, a desirable equilibrium can then quickly be established during temporary shifts in demand.</p> <p>Supply and demand are not fixed, and the appropriate equilibrium will inadvertently shift in the future due to changes in the ETH token price and circulating supply, as well as the protocol's ability to scale throughput. To remain neutral and future-proof, the pricing mechanism should therefore operate on a relative basis, ideally then anchored to the computed long-run average.</p> <p>When demand fails to meet supply, a producer can reduce the unit price or decrease the quantity supplied to re-establish equilibrium. If it sells unique goods but seeks to avoid inefficiencies from either idle capacity or excessive resource use, it can gradually reduce both, smoothly moving along its expansion path to attain the optimal equilibrium under the given demand curve. Ethereum can respond to <em>temporary downturns</em> in demand by gradually reducing both price <em>and</em> equilibrium throughput, smoothly reducing the number of consumed blobs at which the price remains fixed. This is achieved by adjusting the fee update to smoothly become less responsive to low gas usage, implicitly controlling output. Ethereum cannot respond to <em>sustained downturns</em> in demand by reducing throughput, because such a downturn could imply that circumstances have changed, and that the price is now <em>too high</em> (assuming the protocol remains neutral). To be clear, Ethereum reduces throughput already today during downturns in demand by thresholding at 1 wei. Any fixed threshold that prevents the price from falling further once reached reduces throughput by not allowing blocks with below-threshold gas usage to influence the future fee. However, an instant shift from a fixed response schedule to complete unresponsiveness under a below-target demand presumably does not reflect the protocol's blobspace production expansion path (see also Figure 1).</p> <h3 id="proposed-base-fee-update-schedule">Proposed base fee update schedule</h3> <p>The update schedule adheres to the following design principles:</p> <ul> <li>Remain neutral and future-proof concerning changes in supply and demand.</li> <li>Rely on the normal fee update schedule when the base fee is above or just slightly below the long-run average.</li> <li>Smoothly adjust the fee update to become less responsive to low gas usage and more responsive to high gas usage as the ratio $\bar{f}_g/f_g$ grows.</li> <li>When the price is relatively low ($f_g&lt;\bar{f}_g$), raise the fee quickly during a rise in demand and reduce it slowly during a fall in demand. In other words, add a mean reversion effect (this is closely related to the previous point).</li> <li>The fee update must vary smoothly with blob quantity at all applicable $\bar{f}_g/f_g$ ratios so that users or validators will not strategically include specific quantities of blobs in each block.</li> <li>Avoid extreme responses even if the ratio $\bar{f}_g/f_g$ diverges substantially.</li> </ul> <p>A mean reversion weight is first computed</p> <p>$$ w = \sqrt[8]{\frac{\bar{f}_g/f_g + D}{D+1}}, $$</p> <p>where $D$ is the constant <code>MEAN_REVERSION_DEADBAND</code>, set to 64. The eighth root can be computed by applying the existing (at the consensus layer) function <code>integer_squareroot()</code> three times. The update to the excess gas field $e_g$ for slot $n$ is then changed from</p> <p>$$ e_{g(n)} = e_{g(n-1)} + c_g - t_g $$</p> <p>to</p> <p>$$ e_{g(n)} = e_{g(n-1)} + c_gw - t_g/w. $$</p> <p>Figure 2 illustrates the resulting fee update schedule when applying the blob targets from Pectra. The further the fee falls below the average, the fewer blobs must be consumed for the fee to remain fixed. This eventually leads to equilibrium being established, even under low demand. The transition is gradual, allowing for a smooth response to shifts in demand. Note that the vertical blob spacing is kept smooth at all ratios, discouraging users or validators to strategically adapt intra-block consumption of blobs.</p> <p><img src="https://wg-eips.ritovision.com/7915/./assets/2.png" alt="Figure 2" /></p> <p><strong>Figure 2.</strong> Proposed blob fee update schedule across the $f_g/\bar{f}_g$ ratio under Pectra blob constants. When the ratio is around or above 1, the baseline fee update schedule is applied. When the fee falls below the average, fewer blobs must be consumed for the fee to remain fixed.</p> <p>The fee schedule is computed across the range <code>MEAN_REVERSION_FULLBAND = 10**6</code>. Thus, if the ratio in Figure 2 falls below $10^{-6}$, the schedule at $10^{-6}$ applies. This approach protects against exploding fee schedules, allows the fee to gradually fall further if no blobs at all are consumed, and protects against overflow due to high ratios (thus allowing for the smaller <code>uint64</code> in the <code>calc_excess_blob_gas()</code> function). Optionally, the operational region can also be bounded by adding a constant $c$ (set in the region of 1-2 blobs worth of gas) to the fee update schedule:</p> <p>$$ e_{g(n)} = e_{g(n-1)} + c_gw - t_g/w + c(w-1). $$</p> <p>The mechanism only applies mean reversion when $f_g &lt; \bar{f}_ g.$ While there can be benefits from mean reversion in both directions, the case when $f_g&lt;\bar{f}_ g$ is far more important to address. Furthermore, the update schedule from <a href="https://wg-eips.ritovision.com/7691/">EIP-7691</a>, applied when $f_g \geq \bar{f}_g$, already decreases more with 0 blobs than it increases with the maximum.</p> <p>A symmetrical update schedule at ratios around 1 was initially considered since the target from Pectra is not centered at <code>MAX_BLOB_GAS_PER_BLOCK/2</code>. However, a well-formed symmetrical fee update schedule will likely not achieve a <code>TARGET_BLOB_GAS_PER_BLOCK</code> throughput, even though it responds to a target gas consumption by keeping the fee fixed. The reason is that the fee update for blocks $x$ blobs above the target and $x$ blobs below the target will not be reciprocal. Equilibrium would therefore settle at slightly lower throughput than <code>TARGET_BLOB_GAS_PER_BLOCK</code>, at a slightly higher price than when relying on the assymetrical update schedule with an identical target. The proposed fee update schedule instead intermediately transitions to a symmetrical schedule as the fee ratio falls (see Figure 2).</p> <h3 id="computing-the-long-run-average-base-fee">Computing the long-run average base fee</h3> <p>An average of the base fee $\bar{f}_g$ is maintained in the header variable <code>base_fee_per_blob_gas_ema</code>, computed as an exponential moving average. Each slot, $\bar{f}_g$ is updated by taking</p> <p>$$ \bar{f}_ {g(n)} = \bar{f}_ {g(n-1)} + \frac{f_{g(n-1)} - \bar{f}_{g(n-1)}}{m}, $$</p> <p>where $m$ is a constant <code>EMA_DECAY=2**18</code>. This setting gives a half-life of around one month. If the <code>EMA_DECAY</code> is set slightly higher, the mechanism is guaranteed to influence blob pricing over the next few years. For example, initializing $\bar{f}_ g=4\times10^9$ (as proposed) and setting a half-life of four months (<code>EMA_DECAY=2**20</code>) ensures that $\bar{f}_ g&gt;5\times10^8$ one year after activation. If the proposed mechanism is included in a hard fork that also boosts throughput, this could be seen as a bonus, given the smooth floor operating a few orders of magnitude below $\bar{f}_ g$.</p> <p>Figure 3 shows how $\bar{f}_{g}$ would have evolved between November 2024 and March 2025, using $4\times10^9$ as a starting value. Note that the EMA fee could be allowed to fall below <code>EMA_DECAY</code> by subtracting at least 1 in each update step (this is however not part of the functionality in the specification).</p> <p>The EMA is computed in the linear domain to preserve additivity and maintain interpretability. Averaging in the log-domain across excess gas (akin to a geometric mean in the linear domain) would give undue influence to fine-grained fluctuations at lower fees. This would make changes at lower gas thresholds very influential, creating feedback loops that are hard to explain and reason about; especially since the threshold at 1 wei always will be fixed and gradually could come into play over the long run due to shifts in supply or demand. However, note that while it is strictly preferred to compute the EMA in the linear domain, it would be possible to convert back to the log-domain to store and apply an excess blob gas EMA. This option is described in the next subsection.</p> <p><img src="https://wg-eips.ritovision.com/7915/./assets/3.png" alt="Figure 3" /></p> <p><strong>Figure 3.</strong> Exponential moving average with the proposed settings applied to a few months of historical blob base fee data.</p> <h3 id="alternative-approach">Alternative approach</h3> <p>One alternative way to structure the adaptive mean reversion was referenced in the previous subsection and will be described here. It differs in that that the protocol would rely on and store a log-domain representation of <code>base_fee_per_blob_gas_ema</code>: <code>excess_blob_gas_ema</code>. The EMA computation would still be performed in the linear domain, but <code>get_base_fee_per_blob_gas()</code> and its inverse—relying on a new <code>fake_log()</code> function—would be applied during computations to first go to the linear domain and then return to the log-domain</p> <p>$$ \bar{e}_ {g(n)} = \log\Biggl[\exp\bigl(\bar{e}_ {g(n-1)}\bigr) + \frac{\exp\bigl(e_ {g(n-1)}\bigr) - \exp\bigl(\bar{e}_ {g(n-1)}\bigr)}{m}\Biggr]. $$</p> <p>The weight calculation in <code>calc_excess_blob_gas()</code> could then be performed in the log-domain, in principle:</p> <p>$$ w = \frac{\bar{e}_g-e_g + D}{D+1}, $$</p> <p>but where, e.g., $D$ would be adjusted according to relevant excess gas scaling for the applicable hard fork. The fee update schedule would become very similar with both approaches, and the choice thus mostly comes down to architectural preferences.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The blob base fee doubles during full blocks if the current fee is several orders of magnitude below the average. As a result, a single-block delay in inclusion results in users paying twice as much, potentially influencing inclusion and fee-market strategies. However, practical implications should be limited, given that this aggressive fee schedule only operates at fees well below the average.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-03-05T00:00:00+00:00 2026-02-11T14:49:28+00:00 Charles Cooperhttps://github.com/charles-cooper https://wg-eips.ritovision.com/7903/

Removes the initcode size limit introduced in EIP-3860

<h2 id="abstract">Abstract</h2> <p>This EIP proposes the removal of the <code>initcode</code> size limit of 49152 bytes introduced in <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a>. The restriction complicates deploying multiple contracts addressing the <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> limit (24576 bytes) within a single transaction, while the existing gas metering for <code>initcode</code>, already ensures fair <code>initcode</code> costing, including for <code>JUMPDEST</code> analysis.</p> <h2 id="motivation">Motivation</h2> <p>The EIP-3860 <code>initcode</code> size limit imposes an unnecessary constraint on deployment patterns, particularly for creation transactions creating large <em>logical</em> contracts composed of multiple <em>physical sub-contracts</em> in a single transaction. A key argument for retaining EIP-170's 24KB runtime code limit is that high-level languages (HLLs) should abstract it away. However, the EIP-3860 limit prevents HLLs from cleanly abstracting this, as deploying large logical contracts exceeding 49152 bytes of <code>initcode</code> requires splitting into multiple transactions, undermining the abstraction.</p> <p>Removing the cap simplifies smart contract deployment and enables HLLs to cleanly abstract large contracts, without compromising network security or cost attribution.</p> <h2 id="specification">Specification</h2> <p>Revert the <code>initcode</code> size limit introduced in EIP-3860. Specifically:</p> <ul> <li>Remove the 49152-byte cap on <code>initcode</code> size during contract creation.</li> <li>Retain existing gas costs for <code>initcode</code> execution, including the 2 gas per byte for <code>JUMPDEST</code> analysis, as defined in EIP-3860.</li> </ul> <p>No changes to deployed contract size limits (EIP-170) or gas schedules beyond removing the size restriction are proposed.</p> <h2 id="rationale">Rationale</h2> <p>This proposal is driven by the need to restore flexibility in contract deployment patterns, such as factory contracts creating multiple sub-contracts in one transaction. The design decision to remove the 49152-byte cap leverages the pre-existing gas metering system, which scales linearly with <code>initcode</code> size (i.e., 2 gas per byte), ensuring fair cost attribution without artificial limits.</p> <p>A key justification for EIP-170's 24576-byte limit is that high-level languages (HLLs) should abstract it away. However, EIP-3860's <code>initcode</code> cap undermines this by forcing multi-transaction deployments for large contracts, breaking the abstraction HLLs aim to provide. Removing the cap aligns with this philosophy by enabling single-transaction deployments.</p> <p>Alternative designs, such as increasing the cap (e.g., to 98304 bytes), were considered but rejected as arbitrary; gas metering already mitigates resource concerns. The per-block gas limit already naturally restricts <code>initcode</code> (at the current gas limit of 35 million, <code>initcode</code> is restricted to ~16mb). Furthermore, initcode has additional implied costs - it must have already been paid for via calldata or memory expansion, limiting it even more.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is fully backwards compatible. Existing contracts and transactions remain unaffected, as the proposal only lifts a restriction without altering execution semantics or gas costs.</p> <h2 id="test-cases">Test Cases</h2> <h2 id="security-considerations">Security Considerations</h2> <p>No new security risks are introduced. The current gas schedule already mitigates denial-of-service concerns by charging per-byte for <code>initcode</code>. Benchmarks were performed, and ns/byte remained consistent across a range of different bytecodes, ranging from 128 bytes to 15MB.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> 2025-02-27T00:00:00+00:00 2026-02-11T14:49:27+00:00 Francisco Giordanohttps://github.com/frangio https://wg-eips.ritovision.com/7896/

A capability to enable calldata decoding in wallets.

<h2 id="abstract">Abstract</h2> <p>This EIP extends <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> with a new <code>interfaces</code> capability, whereby an application can attach the contract interface specifications (aka. ABIs) that the wallet needs to reliably decode the calldata in the request.</p> <h2 id="motivation">Motivation</h2> <p>The security model of Ethereum accounts relies on a separation of concerns between applications and wallets, the latter being responsible for securing private key material and providing restricted access to it. When an application requests a transaction or a signature, the wallet prompts the user to accept it or reject it. The user is expected to make an assessment about the desirability of the operation, given that it can potentially operate on all account assets, in the extreme case "draining" them all for the benefit of an attacker. The wallet is tasked with providing information about the request to lead to an accurate assessment, in particular to help detect unintended effects and attacks.</p> <p>This idealized vision is far from realized. "Blind signing", the practice of accepting a request without full visibility of its contents or understanding of its implications, is a pervasive problem across Ethereum. This is a puzzling situation given what's at stake. A likely explanation is that it is simply very difficult for wallets to extract and provide good information about requests.</p> <p>Before accepting a transaction request, a user would ideally like to know exactly what effects the transaction will have when included on chain. Transaction simulations have become widespread throughout wallets in recent years, where the wallet (or a service provider) runs the transaction and summarizes the observed effects in a friendly description such as "-1 ETH, +2400 USDC". However, exactly predicting these effects is impossible due to mutable shared state, and describing the range of possible effects is intractable due to the turing completeness of the EVM, so we should be cautious and not overly rely on this kind of approach.</p> <p>Whereas transaction simulations try to provide insight into the dynamic behavior of a transaction, wallets should also surface all of the statically available information, such as transaction parameters and application metadata.</p> <p>Some parameters have clear semantics, for example, the <code>value</code> in a transaction expresses how much of the native token is transferred. The <code>data</code> in a transaction, however, presents a challenge, as it is provided to the wallet as a bytestring and cannot be reliably decoded into more meaningfully structured information without knowledge of the target contract ABI. The wallet can try to use a database of function selectors to try to guess an ABI, but this will fail for new and unknown contracts, and known selectors can be ambiguous due to collisions, including those deliberately introduced by attackers. Alternatively, the wallet can obtain an ABI from a repository of verified source code, with the downside that the main such repository is managed by a centralized party.</p> <p>Since applications that request transactions are necessarily aware of the relevant ABIs, this EIP proposes a mechanism where they can attach ABIs in transaction requests, so that wallets can show decoded call data to users and help make a more informed assessment.</p> <h2 id="specification">Specification</h2> <p>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>A new capability called <code>interfaces</code> is added to EIP-5792 requests.</p> <h3 id="wallet-sendcalls"><code>wallet_sendCalls</code></h3> <p>When this capability is supported, <code>wallet_sendCalls</code> requests MAY include a global <code>interfaces</code> field.</p> <p>The <code>interfaces</code> field provided by an application MUST map contract addresses to interface specs. These contract addresses SHOULD correspond to those of the <code>to</code> fields in the <code>calls</code> array of the request, and SHOULD be compared with them case-sensitively. There MAY be addresses in <code>calls</code> without a matching interface spec, and there MAY be addresses in <code>interfaces</code> without a matching call.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> SendCallsParams</span><span class="z-keyword"> =</span><span> {</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> default fields omitted</span></span> <span class="giallo-l"><span class="z-variable"> capabilities</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span> {</span><span class="z-variable"> interfaces</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> InterfacesCapability</span><span> }</span><span class="z-keyword"> &amp;</span><span class="z-entity z-name"> Record</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-entity z-name"> Capability</span><span>&gt;</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">type</span><span class="z-entity z-name"> InterfacesCapability</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> [</span><span class="z-variable">contract</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string"> `</span><span class="z-string">0x</span><span class="z-string">${</span><span class="z-support">string</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>]</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> version</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> spec</span><span class="z-keyword">:</span><span class="z-support"> unknown</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> version-dependent</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> optional</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> boolean</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>An interface spec MUST describe how a contract will decode calldata into a series of function arguments. The interpretation of a spec as a decoding procedure depends on a version string.</p> <p>The two initially defined versions are <code>abi-v1</code> and <code>abi-v2</code>, corresponding to the Contract Application Binary Interface as defined by Solidity and adopted by other languages. In these cases, the spec MUST be provided as an array as described in Solidity's documentation, page "Contract ABI Specification", section "JSON". The array MAY contain event and error descriptions in addition to function descriptions, though applications SHOULD exclude irrelevant items. The v1-v2 distinction corresponds to Solidity's <code>pragma abicoder v1</code> and <code>pragma abicoder v2</code> (or <code>pragma experimental ABIEncoderV2</code>). Vyper implements <code>abi-v2</code>.</p> <p>Applications SHOULD mark the <code>interfaces</code> field as <code>optional</code>, so that the user is able to proceed if their wallet does not support the capability or a provided spec version. If the field is marked <code>optional</code>, the wallet MAY ignore interfaces with unsupported spec versions.</p> <p>Wallets SHOULD use the provided interface specs to decode the <code>data</code> of each call in the <code>calls</code> array in order to present the user with the decoded function arguments. Wallets MAY validate the provided specs against a database of verified or trusted specs.</p> <h4 id="example-request">Example Request</h4> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">version</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">from</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa22cc169386b820ab57c006a5b4980add068a7eb</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x01</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">calls</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">to</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdac17f958d2ee523a2206206994597c13d831ec7</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">data</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa9059cbb000000000000000000000000f0c87f351435211efa00938a33771bf38302d1f10000000000000000000000000000000000000000000000056bc75e2d63100000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">capabilities</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interfaces</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">optional</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">0xdac17f958d2ee523a2206206994597c13d831ec7</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">version</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">abi-v1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">spec</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">function</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">transfer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">stateMutability</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nonpayable</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">to</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">value</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">outputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h3 id="wallet-getcapabilities"><code>wallet_getCapabilities</code></h3> <p>Under the <code>interfaces</code> capability, wallets MUST include a <code>versions</code> array field listing the supported interface spec versions.</p> <h4 id="example-response">Example Response</h4> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">0x0</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interfaces</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">supported</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">versions</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">abi-v1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">abi-v2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <!-- TODO --> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <!-- TODO --> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-02-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Shoham Chakrabortyhttps://github.com/shohamc1 Alex Forshtathttps://github.com/forshtat https://wg-eips.ritovision.com/7889/

Top level reverts emit a log with revert message

<h2 id="abstract">Abstract</h2> <p>All calls to the REVERT opcode with non-zero size must emit a log with revert data, making it accessible via standard RPC without the need for tracing.</p> <h2 id="motivation">Motivation</h2> <p>Revert messages are currently inaccessible to users as they are not available via standard RPC. Instead, users have to request a node to trace the transaction and check the stack and memory at the moment when the REVERT opcode was executed.</p> <p>This introduces overhead for users and nodes - users must make an additional request to find out why their transaction failed, and the node has to replay the full transaction (which may be slow and computationally expensive) to get back a relatively small piece of data.</p> <p>Currently it is up to smart wallet developers to emit logs before a revert, however this is not a standard feature and thus cannot be relied upon by tools such as client libraries and block explorers. Making this log part of the protocol allows these tools to rely on logs for revert reasons.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <!-- TODO --> <ul> <li><code>REVERTTOPIC</code>: <code>TBD</code></li> <li><code>DATA_LIMIT</code>: <code>TBD</code></li> </ul> <h3 id="functionality">Functionality</h3> <p>Whenever <code>REVERT</code> is called with non-zero size, emit a log identical to a LOG1 with the topic <code>REVERTTOPIC</code>. The log data is the raw bytes of the revert message. The data is truncated to <code>DATA_LIMIT</code>.</p> <h2 id="rationale">Rationale</h2> <p>This is the simplest possible implementation that allows revert messages to be accessible via RPC methods. It does not require any changes to client libraries, or other RPC consumers as it is backward compatible. It does not introduce new RPC methods or new opcodes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Reverted transactions may now contain up to one log.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Reverted transactions must cost at least intrinsic gas (21000 gas), which is much more expensive than the LOG1 opcode (750 gas). Hence, this EIP does not introduce any new avenues to inflate Ethereum storage requirements. However, it is expected to increase the average number of logs.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-02-18T00:00:00+00:00 2026-02-11T14:49:28+00:00 Francesco D'Amatohttps://github.com/fradamt Toni Wahrstätterhttps://github.com/nerolation https://wg-eips.ritovision.com/7886/

Separate block validation from execution

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a mechanism to make execution blocks statically verifiable through minimal checks that only require the previous state, without requiring execution of the block's transactions. This enables validators to attest to a block's validity without completing its execution.</p> <h2 id="motivation">Motivation</h2> <p>The primary advantage of this proposal is <strong>asynchronous block validation</strong>. In the current Ethereum protocol, blocks must be fully executed before validators can attest to them. This requirement creates a bottleneck in the consensus process, as attestors must wait for execution results before committing their votes, limiting the network's throughput potential.</p> <p>By introducing a mechanism where execution payloads can be reverted rather than invalidating the entire block, execution is no longer an immediate requirement for validation. Instead, a block's validity can be determined based on its structural correctness and the upfront payment of transaction fees by senders. This allows attestation to happen earlier in the slot, independent of execution, potentially enabling higher block gas limits and significant throughput improvements across the network.</p> <h2 id="specification">Specification</h2> <h3 id="header-changes">Header Changes</h3> <p>The block header structure is extended to support delayed execution:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-entity z-name">@</span><span class="z-entity z-name">dataclass</span></span> <span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> Header</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Existing fields</span></span> <span class="giallo-l"><span> parent_hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span> ommers_hash</span><span>:</span><span> Hash32</span></span> <span class="giallo-l"><span> coinbase</span><span>:</span><span> Address</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Pre-execution state root - this is the state root before executing transactions</span></span> <span class="giallo-l"><span> pre_state_root</span><span>:</span><span> Root</span><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Deferred execution outputs from parent block</span></span> <span class="giallo-l"><span> parent_transactions_root</span><span>:</span><span> Root</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Transaction root from parent block</span></span> <span class="giallo-l"><span> parent_receipt_root</span><span>:</span><span> Root</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Receipt root from parent block</span></span> <span class="giallo-l"><span> parent_bloom</span><span>:</span><span> Bloom</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Logs bloom from parent block</span></span> <span class="giallo-l"><span> parent_requests_hash</span><span>:</span><span> Hash32</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Hash of requests from the parent block</span></span> <span class="giallo-l"><span> parent_execution_reverted</span><span>:</span><span class="z-support"> bool</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Indicates if parent block&#39;s execution was reverted</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Other existing fields</span></span> <span class="giallo-l"><span> difficulty</span><span>:</span><span> Uint</span></span> <span class="giallo-l"><span> number</span><span>:</span><span> Uint</span></span> <span class="giallo-l"><span> gas_limit</span><span>:</span><span> Uint</span></span> <span class="giallo-l"><span> gas_used</span><span>:</span><span> Uint</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Declared gas used by txs, validated post-execution</span></span> <span class="giallo-l"><span> timestamp</span><span>:</span><span> U256</span></span> <span class="giallo-l"><span> extra_data</span><span>:</span><span> Bytes</span></span> <span class="giallo-l"><span> prev_randao</span><span>:</span><span> Bytes32</span></span> <span class="giallo-l"><span> nonce</span><span>:</span><span> Bytes8</span></span> <span class="giallo-l"><span> base_fee_per_gas</span><span>:</span><span> Uint</span></span> <span class="giallo-l"><span> withdrawals_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> blob_gas_used</span><span>:</span><span> U64</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Total blob gas used by transactions</span></span> <span class="giallo-l"><span> excess_blob_gas</span><span>:</span><span> U64</span></span> <span class="giallo-l"><span> parent_beacon_block_root</span><span>:</span><span> Root</span></span></code></pre> <p>The key changes are:</p> <ol> <li><code>pre_state_root</code>: Represents the state root before execution (checked against the post-execution state of the parent block)</li> <li><code>parent_receipt_root</code>: Receipt root from the parent block (deferred execution output)</li> <li><code>parent_bloom</code>: Logs bloom from the parent block (deferred execution output)</li> <li><code>parent_requests_hash</code>: Hash of requests from the parent block (deferred execution output)</li> <li><code>parent_execution_reverted</code>: Indicates whether the parent block's execution was reverted</li> </ol> <p>A block header MUST include all these fields to be considered valid under this EIP. The <code>pre_state_root</code> MUST match the state root after applying the parent block's execution. The parent execution outputs MUST accurately reflect the previous block's execution results to maintain chain integrity.</p> <h3 id="chain-state-tracking">Chain State Tracking</h3> <p>The blockchain object is extended to track execution outputs for verification in subsequent blocks:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-entity z-name">@</span><span class="z-entity z-name">dataclass</span></span> <span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> BlockChain</span><span>:</span></span> <span class="giallo-l"><span> blocks</span><span>:</span><span> List</span><span>[</span><span>Block</span><span>]</span></span> <span class="giallo-l"><span> state</span><span>:</span><span> State</span></span> <span class="giallo-l"><span> chain_id</span><span>:</span><span> U64</span></span> <span class="giallo-l"><span> last_transactions_root</span><span>:</span><span> Root</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Transaction root from the last executed block</span></span> <span class="giallo-l"><span> last_receipt_root</span><span>:</span><span> Root</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Receipt root from last executed block</span></span> <span class="giallo-l"><span> last_block_logs_bloom</span><span>:</span><span> Bloom</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Logs bloom from last executed block</span></span> <span class="giallo-l"><span> last_requests_hash</span><span>:</span><span> Bytes</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Requests hash from last executed block</span></span> <span class="giallo-l"><span> last_execution_reverted</span><span>:</span><span class="z-support"> bool</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Indicates if the last block&#39;s execution was reverted</span></span></code></pre> <p>These additional fields are used to verify the deferred execution outputs claimed in subsequent blocks. The <code>last_transactions_root</code>, <code>last_receipt_root</code>, <code>last_block_logs_bloom</code>, <code>last_requests_hash</code>, and <code>last_execution_reverted</code> act as critical chain state references that MUST be updated after each block execution to ensure proper state progression. When a block's execution is reverted due to a gas mismatch, the <code>last_execution_reverted</code> field is set to <code>True</code>, which affects the base fee calculation of subsequent blocks.</p> <h3 id="block-validation">Block Validation</h3> <p>Static validation is performed separately from execution. In this phase, all checks that can be done without executing transactions are performed:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> validate_block</span><span>(</span><span class="z-variable z-parameter z-function">chain</span><span>:</span><span> BlockChain</span><span>,</span><span class="z-variable z-parameter z-function"> block</span><span>:</span><span> Block</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate header against parent</span></span> <span class="giallo-l"><span> validate_header</span><span>(</span><span>chain</span><span>,</span><span> block</span><span>.</span><span>header</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate deferred execution outputs from the parent</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block</span><span>.</span><span>header</span><span>.</span><span>parent_transactions_root</span><span class="z-keyword"> !=</span><span> chain</span><span>.</span><span>last_transactions_root</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block</span><span>.</span><span>header</span><span>.</span><span>parent_receipt_root</span><span class="z-keyword"> !=</span><span> chain</span><span>.</span><span>last_receipt_root</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block</span><span>.</span><span>header</span><span>.</span><span>parent_bloom</span><span class="z-keyword"> !=</span><span> chain</span><span>.</span><span>last_block_logs_bloom</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block</span><span>.</span><span>header</span><span>.</span><span>parent_requests_hash</span><span class="z-keyword"> !=</span><span> chain</span><span>.</span><span>last_requests_hash</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block</span><span>.</span><span>header</span><span>.</span><span>pre_state_root</span><span class="z-keyword"> !=</span><span> state_root</span><span>(</span><span>chain</span><span>.</span><span>state</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block</span><span>.</span><span>header</span><span>.</span><span>parent_execution_reverted</span><span class="z-keyword"> !=</span><span> chain</span><span>.</span><span>last_execution_reverted</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Process all transactions trie and validate transactions</span></span> <span class="giallo-l"><span> total_inclusion_gas</span><span class="z-keyword"> =</span><span> Uint</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span> total_blob_gas_used</span><span class="z-keyword"> =</span><span> Uint</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span> withdrawals_trie</span><span class="z-keyword"> =</span><span> Trie</span><span>(</span><span class="z-variable">secured</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>,</span><span class="z-variable"> default</span><span class="z-keyword">=</span><span class="z-constant">None</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Track sender balances and nonces by address</span></span> <span class="giallo-l"><span> sender_balances</span><span class="z-keyword"> =</span><span> {</span><span>}</span></span> <span class="giallo-l"><span> sender_nonces</span><span class="z-keyword"> =</span><span> {</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Calculate blob gas price based on excess blob gas</span></span> <span class="giallo-l"><span> blob_gas_price</span><span class="z-keyword"> =</span><span> calculate_blob_gas_price</span><span>(</span><span>block</span><span>.</span><span>header</span><span>.</span><span>excess_blob_gas</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate each transaction</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span>,</span><span> tx</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span class="z-support">map</span><span>(</span><span>decode_transaction</span><span>,</span><span> block</span><span>.</span><span>transactions</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate transaction parameters (signature, fees, etc.)</span></span> <span class="giallo-l"><span> validate_transaction</span><span>(</span><span>tx</span><span>,</span><span> block</span><span>.</span><span>header</span><span>.</span><span>base_fee_per_gas</span><span>,</span><span> block</span><span>.</span><span>header</span><span>.</span><span>excess_blob_gas</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Recover sender</span></span> <span class="giallo-l"><span> sender_address</span><span class="z-keyword"> =</span><span> recover_sender</span><span>(</span><span>chain</span><span>.</span><span>chain_id</span><span>,</span><span> tx</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Calculate gas costs (both EIP-7623 intrinsic cost and floor cost)</span></span> <span class="giallo-l"><span> intrinsic_gas</span><span>,</span><span> calldata_floor_gas_cost</span><span class="z-keyword"> =</span><span> calculate_intrinsic_cost</span><span>(</span><span>tx</span><span>)</span></span> <span class="giallo-l"><span> blob_gas_used</span><span class="z-keyword"> =</span><span> calculate_total_blob_gas</span><span>(</span><span>tx</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Track total gas usage (using the maximum of intrinsic gas and floor cost)</span></span> <span class="giallo-l"><span> total_inclusion_gas</span><span class="z-keyword"> +=</span><span class="z-support"> max</span><span>(</span><span>intrinsic_gas</span><span>,</span><span> calldata_floor_gas_cost</span><span>)</span></span> <span class="giallo-l"><span> total_blob_gas_used</span><span class="z-keyword"> +=</span><span> blob_gas_used</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Calculate maximum gas fee (including blob fees)</span></span> <span class="giallo-l"><span> effective_gas_price</span><span class="z-keyword"> =</span><span> calculate_effective_gas_price</span><span>(</span><span>tx</span><span>,</span><span> block</span><span>.</span><span>header</span><span>.</span><span>base_fee_per_gas</span><span>)</span></span> <span class="giallo-l"><span> max_gas_fee</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>gas</span><span class="z-keyword"> *</span><span> effective_gas_price</span><span class="z-keyword"> +</span><span> blob_gas_used</span><span class="z-keyword"> *</span><span> blob_gas_price</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify sender is an EOA or has delegation support</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> sender_address</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> sender_balances</span><span>:</span></span> <span class="giallo-l"><span> account</span><span class="z-keyword"> =</span><span> get_account</span><span>(</span><span>chain</span><span>.</span><span>state</span><span>,</span><span> sender_address</span><span>)</span></span> <span class="giallo-l"><span> is_sender_eoa</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> account</span><span>.</span><span>code</span><span class="z-keyword"> ==</span><span class="z-support"> bytearray</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> or</span><span> is_valid_delegation</span><span>(</span><span>account</span><span>.</span><span>code</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_sender_eoa</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"><span> sender_balances</span><span>[</span><span>sender_address</span><span>]</span><span class="z-keyword"> =</span><span> account</span><span>.</span><span>balance</span></span> <span class="giallo-l"><span> sender_nonces</span><span>[</span><span>sender_address</span><span>]</span><span class="z-keyword"> =</span><span> account</span><span>.</span><span>nonce</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify sender has sufficient balance</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> sender_balances</span><span>[</span><span>sender_address</span><span>]</span><span class="z-keyword"> &lt;</span><span> max_gas_fee</span><span class="z-keyword"> +</span><span> Uint</span><span>(</span><span>tx</span><span>.</span><span>value</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify correct nonce</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> sender_nonces</span><span>[</span><span>sender_address</span><span>]</span><span class="z-keyword"> !=</span><span> tx</span><span>.</span><span>nonce</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Track balance and nonce changes</span></span> <span class="giallo-l"><span> sender_balances</span><span>[</span><span>sender_address</span><span>]</span><span class="z-keyword"> -=</span><span> max_gas_fee</span><span class="z-keyword"> +</span><span> Uint</span><span>(</span><span>tx</span><span>.</span><span>value</span><span>)</span></span> <span class="giallo-l"><span> sender_nonces</span><span>[</span><span>sender_address</span><span>]</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate gas constraints</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> total_inclusion_gas</span><span class="z-keyword"> &gt;</span><span> block</span><span>.</span><span>header</span><span>.</span><span>gas_used</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> total_blob_gas_used</span><span class="z-keyword"> !=</span><span> block</span><span>.</span><span>header</span><span>.</span><span>blob_gas_used</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate withdrawals trie</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span>,</span><span> wd</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>block</span><span>.</span><span>withdrawals</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> trie_set</span><span>(</span><span>withdrawals_trie</span><span>,</span><span> rlp</span><span>.</span><span>encode</span><span>(</span><span>Uint</span><span>(</span><span>i</span><span>)</span><span>)</span><span>,</span><span> rlp</span><span>.</span><span>encode</span><span>(</span><span>wd</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block</span><span>.</span><span>header</span><span>.</span><span>withdrawals_root</span><span class="z-keyword"> !=</span><span> root</span><span>(</span><span>withdrawals_trie</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> InvalidBlock</span></span></code></pre> <p>This validation function enforces several requirements:</p> <ol> <li>Clients MUST validate that the block's parent execution outputs match the chain's tracked last execution outputs.</li> <li>The <code>pre_state_root</code> MUST match the current state root to ensure proper state transition.</li> <li>All transactions MUST be statically validated for signature correctness and transaction type-specific requirements (<a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>, <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>, etc.).</li> <li>Sender accounts MUST be externally owned accounts (EOAs) or have valid delegation support (<a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>).</li> <li>Senders MUST have sufficient balance to cover maximum possible gas fees plus transaction value.</li> <li>Transaction nonces MUST be correct and sequential per sender.</li> <li>Total inclusion gas (using the maximum of intrinsic gas and <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> floor cost) MUST not exceed the block's declared gas_used.</li> <li>Total blob gas MUST match the declared blob_gas_used.</li> <li>Withdrawal trie root MUST match its respective header field.</li> </ol> <p>When calculating inclusion gas, the implementation uses the maximum of the regular intrinsic gas cost and the <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> calldata floor cost, which ensures proper accounting for calldata gas regardless of execution outcome.</p> <h3 id="block-execution-with-state-snapshots">Block Execution with State Snapshots</h3> <p>After a block passes static validation, execution proceeds with the pre-charged transaction senders:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> apply_body</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> block_env</span><span>:</span><span> vm</span><span>.</span><span>BlockEnvironment</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> transactions</span><span>:</span><span> Tuple</span><span>[</span><span>Union</span><span>[</span><span>LegacyTransaction</span><span>,</span><span> Bytes</span><span>]</span><span>,</span><span class="z-constant"> ...</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> withdrawals</span><span>:</span><span> Tuple</span><span>[</span><span>Withdrawal</span><span>,</span><span class="z-constant"> ...</span><span>]</span><span>,</span></span> <span class="giallo-l"><span>)</span><span> -&gt;</span><span> vm</span><span>.</span><span>BlockOutput</span><span>:</span></span> <span class="giallo-l"><span> block_output</span><span class="z-keyword"> =</span><span> vm</span><span>.</span><span>BlockOutput</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Process system transactions first (beacon roots, history storage)</span></span> <span class="giallo-l"><span> process_system_transaction</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> block_env</span><span class="z-keyword">=</span><span>block_env</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> target_address</span><span class="z-keyword">=</span><span class="z-constant">BEACON_ROOTS_ADDRESS</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">=</span><span>block_env</span><span>.</span><span>parent_beacon_block_root</span><span>,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> process_system_transaction</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> block_env</span><span class="z-keyword">=</span><span>block_env</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> target_address</span><span class="z-keyword">=</span><span class="z-constant">HISTORY_STORAGE_ADDRESS</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> data</span><span class="z-keyword">=</span><span>block_env</span><span>.</span><span>block_hashes</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The parent hash</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Process user transactions</span></span> <span class="giallo-l"><span> process_transactions</span><span>(</span><span>block_env</span><span>,</span><span> block_output</span><span>,</span><span> transactions</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Process withdrawals</span></span> <span class="giallo-l"><span> process_withdrawals</span><span>(</span><span>block_env</span><span>,</span><span> block_output</span><span>,</span><span> withdrawals</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Process requests (deposits, withdrawals, consolidations)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> not generated if execution_reverted in header is True</span></span> <span class="giallo-l"><span> process_general_purpose_requests</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> block_env</span><span class="z-keyword">=</span><span>block_env</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> block_output</span><span class="z-keyword">=</span><span>block_output</span><span>,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> block_output</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> process_transactions</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> block_env</span><span>:</span><span> vm</span><span>.</span><span>BlockEnvironment</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> block_output</span><span>:</span><span> vm</span><span>.</span><span>BlockOutput</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> transactions</span><span>:</span><span> Tuple</span><span>[</span><span>Union</span><span>[</span><span>LegacyTransaction</span><span>,</span><span> Bytes</span><span>]</span><span>,</span><span class="z-constant"> ...</span><span>]</span><span>,</span></span> <span class="giallo-l"><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Take a block-level snapshot of the state before transaction execution</span></span> <span class="giallo-l"><span> begin_transaction</span><span>(</span><span>block_env</span><span>.</span><span>state</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Decode transactions</span></span> <span class="giallo-l"><span> decoded_transactions</span><span class="z-keyword"> =</span><span> [</span><span>decode_transaction</span><span>(</span><span>tx</span><span>)</span><span class="z-keyword"> for</span><span> tx</span><span class="z-keyword"> in</span><span> transactions</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Pre-charge senders for maximum possible gas fees upfront</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> tx</span><span class="z-keyword"> in</span><span> decoded_transactions</span><span>:</span></span> <span class="giallo-l"><span> deduct_max_tx_fee_from_sender_balance</span><span>(</span><span>block_env</span><span>,</span><span> tx</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Execute each transaction</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span>,</span><span> tx</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>decoded_transactions</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> process_transaction</span><span>(</span><span>block_env</span><span>,</span><span> block_output</span><span>,</span><span> tx</span><span>,</span><span> Uint</span><span>(</span><span>i</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Stop processing if execution is already reverted</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block_output</span><span>.</span><span>execution_reverted</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> break</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate declared gas used against actual gas used</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>execution_reverted</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>execution_reverted</span></span> <span class="giallo-l"><span class="z-keyword"> or</span><span> block_output</span><span>.</span><span>block_gas_used</span><span class="z-keyword"> !=</span><span> block_env</span><span>.</span><span>block_gas_used</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If execution is reverted, reset all outputs and rollback the state</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block_output</span><span>.</span><span>execution_reverted</span><span>:</span></span> <span class="giallo-l"><span> rollback_transaction</span><span>(</span><span>block_env</span><span>.</span><span>state</span><span>)</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>block_gas_used</span><span class="z-keyword"> =</span><span> Uint</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>transactions_trie</span><span class="z-keyword"> =</span><span> Trie</span><span>(</span><span class="z-variable">secured</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>,</span><span class="z-variable"> default</span><span class="z-keyword">=</span><span class="z-constant">None</span><span>)</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>receipts_trie</span><span class="z-keyword"> =</span><span> Trie</span><span>(</span><span class="z-variable">secured</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>,</span><span class="z-variable"> default</span><span class="z-keyword">=</span><span class="z-constant">None</span><span>)</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>receipt_keys</span><span class="z-keyword"> =</span><span> (</span><span>)</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>block_logs</span><span class="z-keyword"> =</span><span> (</span><span>)</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>requests</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>execution_reverted</span><span class="z-keyword"> =</span><span class="z-constant"> True</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Commit the state if execution is valid</span></span> <span class="giallo-l"><span> commit_transaction</span><span>(</span><span>block_env</span><span>.</span><span>state</span><span>)</span></span></code></pre> <p>During block execution:</p> <ol> <li> <p>Clients MUST create a block-level snapshot before any transaction execution occurs. This happens after handling the system contracts from <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a> and <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a>.</p> </li> <li> <p>Maximum fees MUST be deducted from sender balances upfront by:</p> </li> </ol> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> deduct_max_tx_fee_from_sender_balance</span><span>(</span><span class="z-variable z-parameter z-function">block_env</span><span>,</span><span class="z-variable z-parameter z-function"> tx</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> effective_gas_price</span><span class="z-keyword"> =</span><span> calculate_effective_gas_price</span><span>(</span><span>tx</span><span>,</span><span> block_env</span><span>.</span><span>base_fee_per_gas</span><span>)</span></span> <span class="giallo-l"><span> blob_gas_price</span><span class="z-keyword"> =</span><span> calculate_blob_gas_price</span><span>(</span><span>block_env</span><span>.</span><span>excess_blob_gas</span><span>)</span></span> <span class="giallo-l"><span> blob_gas_used</span><span class="z-keyword"> =</span><span> calculate_total_blob_gas</span><span>(</span><span>tx</span><span>)</span></span> <span class="giallo-l"><span> max_gas_fee</span><span class="z-keyword"> =</span><span> tx</span><span>.</span><span>gas</span><span class="z-keyword"> *</span><span> effective_gas_price</span><span class="z-keyword"> +</span><span> blob_gas_used</span><span class="z-keyword"> *</span><span> blob_gas_price</span></span> <span class="giallo-l"><span> sender</span><span class="z-keyword"> =</span><span> recover_sender</span><span>(</span><span>block_env</span><span>.</span><span>chain_id</span><span>,</span><span> tx</span><span>)</span></span> <span class="giallo-l"><span> sender_account</span><span class="z-keyword"> =</span><span> get_account</span><span>(</span><span>block_env</span><span>.</span><span>state</span><span>,</span><span> sender</span><span>)</span></span> <span class="giallo-l"><span> set_account_balance</span><span>(</span><span>block_env</span><span>.</span><span>state</span><span>,</span><span> sender</span><span>,</span><span> sender_account</span><span>.</span><span>balance</span><span class="z-keyword"> -</span><span> U256</span><span>(</span><span>max_gas_fee</span><span>)</span><span>)</span></span></code></pre> <ol start="3"> <li> <p>Transactions are executed sequentially until executing a transaction would cause the block to exceed the gas limit.</p> </li> <li> <p>After execution, clients MUST verify that the total gas used matches the declared <code>gas_used</code> in the block header.</p> </li> <li> <p>If the actual gas used doesn't match the declared value, clients MUST:</p> <ul> <li>Set <code>execution_reverted</code> to <code>True</code></li> <li>Roll back to the snapshot taken before execution</li> <li>Reset all execution outputs (receipts, logs, etc.)</li> <li>Return zero gas used</li> </ul> </li> <li> <p>The block itself remains valid, but execution outputs are not applied to the state.</p> </li> <li> <p>General purpose requests as defined in <a href="https://wg-eips.ritovision.com/7685/">EIP-7685</a> are skipped when execution is reverted.</p> </li> <li> <p>The execution outputs (<code>last_transactions_root</code>, <code>last_receipt_root</code>, <code>last_block_logs_bloom</code>, <code>last_requests_hash</code>, <code>last_execution_reverted</code>) are updated in the chain state based on the execution results, and will be verified in subsequent blocks.</p> </li> </ol> <p>Execution SHALL be stopped and the payload reverted after exceeding the block gas limit:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> process_transaction</span><span>(</span><span>...</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block_output</span><span>.</span><span>block_gas_used</span><span class="z-keyword"> +</span><span> tx</span><span>.</span><span>gas</span><span class="z-keyword"> &gt;</span><span> block_env</span><span>.</span><span>block_gas_limit</span><span>:</span></span> <span class="giallo-l"><span> block_output</span><span>.</span><span>execution_reverted</span><span class="z-keyword"> =</span><span class="z-constant"> True</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="deferred-execution-outputs">Deferred Execution Outputs</h3> <p>The core innovation of deferring execution outputs to the next block enables static and stateful validation without requiring immediate execution. The <code>pre_state_root</code> provides a cryptographically verifiable starting point for validation, while parent execution outputs create a chain of deferred execution results that maintains the integrity of the blockchain state.</p> <p>This approach eliminates the execution bottleneck in the validation pipeline by allowing validators to attest to a block's validity based on its structure and the pre-charged transaction fees, without waiting for execution results.</p> <h3 id="pre-charging-mechanism">Pre-Charging Mechanism</h3> <p>Pre-charging senders with the maximum possible fees before execution provides a crucial guarantee that transactions have sufficient balance to be included in the block. This mechanism is compatible with existing fee models, including <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> dynamic fee transactions and <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> blob transactions.</p> <p>By tracking sender balances and nonces during validation, the protocol can enforce transaction validity without execution, enabling earlier block attestation.</p> <h3 id="state-snapshot-architecture">State Snapshot Architecture</h3> <p>The block-level snapshot mechanism provides a way to revert execution when necessary. This approach allows clients to roll back the entire block's execution if the actual gas used does not match the declared gas in the header, without invalidating the block structure itself.</p> <p>This provides two key benefits:</p> <ol> <li>It allows validators to attest to blocks before execution is complete</li> <li>It ensures execution is eventually performed correctly, with economic penalties for incorrect gas declarations</li> </ol> <h3 id="execution-reversion-handling">Execution Reversion Handling</h3> <p>When a block's execution is reverted due to gas mismatch:</p> <ol> <li>The block itself remains valid and part of the canonical chain</li> <li>The <code>last_execution_reverted</code> flag is set to <code>True</code> in chain state</li> <li>The next block must include this flag as <code>parent_execution_reverted</code></li> <li>Base fee calculations for subsequent blocks use 0 as parent gas used when parent execution was reverted</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork, as it alters the block validation and execution process.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="execution-correctness-guarantees">Execution Correctness Guarantees</h3> <p>The protocol ensures execution correctness through these primary mechanisms:</p> <ol> <li>Deferred execution outputs MUST match in subsequent blocks, creating a chain of verifiable execution results.</li> <li>State rollback MUST occur if the actual gas used doesn't match the declared value, providing an economic incentive for correct gas declaration.</li> <li>The <code>parent_execution_reverted</code> flag ensures that blocks acknowledge when parent execution has been reverted, maintaining chain integrity.</li> <li>Static and stateful validation guarantees that all transactions are properly authorized and senders have sufficient funds for maximum fees.</li> </ol> <h3 id="base-fee-dynamics-with-reverted-execution">Base Fee Dynamics with Reverted Execution</h3> <p>When a block's execution is reverted, the next block's base fee calculation treats the parent's gas used as zero, regardless of what was declared in the header. This ensures that base fee adjustments remain responsive to actual chain usage, and prevents manipulation of the fee market through incorrect gas declarations.</p> <h3 id="data-availability-and-economic-incentives">Data Availability and Economic Incentives</h3> <p>Block proposers MUST declare correct gas usage or lose transaction fees when execution is reverted. This aligns incentives for correct gas declaration and ensures execution integrity.</p> <p>Even when a block's execution is reverted due to incorrect gas declaration, the transaction data (calldata, <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> access lists, and blob data) MUST still be stored by all nodes for syncing and block validation purposes. This requirement creates a potential attack vector where malicious actors could attempt to place large amounts of data on-chain at a reduced cost by intentionally invalidating blocks through incorrect gas declarations.</p> <p>However, this attack is not economically sustainable for several reasons:</p> <ol> <li>Block proposers who invalidate blocks through incorrect gas declarations lose all execution layer rewards associated with the block.</li> <li>The attack requires control of block production, which is a scarce resource in the consensus layer.</li> </ol> <p>The economic costs of forgoing block rewards significantly outweigh any potential benefits, making such attacks financially impractical under normal network conditions.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-01-31T00:00:00+00:00 2026-02-11T14:49:28+00:00 Piotr Dobaczewskihttps://github.com/pdobacz Andrei Maiborodahttps://github.com/gumb0 Paweł Bylicahttps://github.com/chfast Alex Beregszaszihttps://github.com/axic Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/7873/

Adds a `TXCREATE` instruction to EOF and an accompanying transaction type allowing to create EOF contracts from transaction data

<h2 id="abstract">Abstract</h2> <p>EVM Object Format (EOF) removes the possibility to create contracts using creation transactions (with an empty <code>to</code> field), <code>CREATE</code> or <code>CREATE2</code> instructions. We introduce a new instruction: <code>TXCREATE</code>, as well as a new transaction type (<code>InitcodeTransaction</code>), to provide a way to create contracts using EOF containers in transaction data.</p> <h2 id="motivation">Motivation</h2> <p>This EIP uses terminology from the <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> which introduces the EOF format.</p> <p>Creation transaction and creation instructions <code>CREATE</code> and <code>CREATE2</code> are means provided by legacy EVM to deploy new code, but per requirement of removing code observability, they are not allowed to deploy EOF code. To allow Externally Owned Accounts (EOAs) to deploy EOF contracts, there must be a way to create EOF contracts using bytecode delivered in transaction data.</p> <p>Additionally, the new instruction and transaction type introduced in this EIP enable contracts to create other contracts using initcode from the transaction data, which in legacy EVM is achieved via a combination of <code>CREATE</code> or <code>CREATE2</code> and loading the initcode from calldata.</p> <p>This mechanism complements <code>EOFCREATE</code> and <code>RETURNCODE</code> instructions from <a href="https://wg-eips.ritovision.com/7620/">EIP-7620</a>, and thus all use cases of contract creation that are available in legacy EVM are enabled for EOF.</p> <p>Since <code>TXCREATE</code> is not restricted to EOF containers, it also serves the purpose of bootstrapping EOF contracts into the state.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>INITCODE_TX_TYPE</code></td><td><code>Bytes1(0x06)</code></td></tr> <tr><td><code>MAX_INITCODE_COUNT</code></td><td><code>256</code></td></tr> <tr><td><code>TX_CREATE_COST</code></td><td>Defined as <code>32000</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/0f9e4345b60d36c23fffaa69f70cf9cdb975f4ba/src/ethereum/shanghai/fork_types.py#L42">Ethereum Execution Layer Specs</a></td></tr> <tr><td><code>STACK_DEPTH_LIMIT</code></td><td>Defined as <code>1024</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/0f9e4345b60d36c23fffaa69f70cf9cdb975f4ba/src/ethereum/shanghai/vm/interpreter.py#L60">Ethereum Execution Layer Specs</a></td></tr> <tr><td><code>GAS_CODE_DEPOSIT</code></td><td>Defined as <code>200</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/0f9e4345b60d36c23fffaa69f70cf9cdb975f4ba/src/ethereum/shanghai/vm/gas.py#L44">Ethereum Execution Layer Specs</a></td></tr> <tr><td><code>TX_DATA_COST_PER_ZERO</code></td><td>Defined as <code>4</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/0f9e4345b60d36c23fffaa69f70cf9cdb975f4ba/src/ethereum/shanghai/fork_types.py#L41">Ethereum Execution Layer Specs</a></td></tr> <tr><td><code>TX_DATA_COST_PER_NON_ZERO</code></td><td>Defined as <code>16</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/0f9e4345b60d36c23fffaa69f70cf9cdb975f4ba/src/ethereum/shanghai/fork_types.py#L40">Ethereum Execution Layer Specs</a></td></tr> <tr><td><code>MAX_CODE_SIZE</code></td><td>Defined as <code>24576</code> in <a href="https://wg-eips.ritovision.com/170/">EIP-170</a></td></tr> <tr><td><code>MAX_INITCODE_SIZE</code></td><td>Defined as <code>2 * MAX_CODE_SIZE</code> in <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a></td></tr> </tbody></table> <h3 id="transaction-types">Transaction Types</h3> <p>Introduce new transaction <code>InitcodeTransaction</code> (type <code>INITCODE_TX_TYPE</code>) which extends <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> (type 2) transaction by adding a new field <code>initcodes: List[ByteList[MAX_INITCODE_SIZE], MAX_INITCODE_COUNT]</code>.</p> <p>The <code>initcodes</code> can only be accessed via the <code>TXCREATE</code> instruction (see below), therefore <code>InitcodeTransactions</code> are intended to be sent to contracts including <code>TXCREATE</code> in their execution.</p> <h4 id="gas-schedule">Gas schedule</h4> <p><code>initcodes</code> items data costs the same as calldata: transaction gas of an <code>InitcodeTransaction</code> is extended to include tokens in <code>initcodes</code> alongside tokens in <code>calldata</code>. Using the conventions from <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a>, the transaction gas is calculated as:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">STANDARD_TOKEN_COST</span><span class="z-keyword"> =</span><span class="z-constant"> 4</span></span> <span class="giallo-l"><span class="z-constant">TOTAL_COST_FLOOR_PER_TOKEN</span><span class="z-keyword"> =</span><span class="z-constant"> 10</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>tokens_in_calldata</span><span class="z-keyword"> =</span><span> zero_bytes_in_calldata</span><span class="z-keyword"> +</span><span> nonzero_bytes_in_calldata</span><span class="z-keyword"> *</span><span class="z-constant"> 4</span></span> <span class="giallo-l"><span>tokens_in_initcodes</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword">for</span><span> initcode</span><span class="z-keyword"> in</span><span> initcodes</span><span>:</span></span> <span class="giallo-l"><span> tokens_in_initcodes</span><span class="z-keyword"> +=</span><span> zero_bytes_in_initcode</span><span class="z-keyword"> +</span><span> nonzero_bytes_in_initcode</span><span class="z-keyword"> *</span><span class="z-constant"> 4</span></span> <span class="giallo-l"><span>tx</span><span>.</span><span>gasUsed</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span class="z-constant"> 21000</span></span> <span class="giallo-l"><span class="z-keyword"> +</span></span> <span class="giallo-l"><span class="z-support"> max</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> STANDARD_TOKEN_COST</span><span class="z-keyword"> *</span><span> (</span><span>tokens_in_calldata</span><span class="z-keyword"> +</span><span> tokens_in_initcodes</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> execution_gas_used</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> TOTAL_COST_FLOOR_PER_TOKEN</span><span class="z-keyword"> *</span><span> (</span><span>tokens_in_calldata</span><span class="z-keyword"> +</span><span> tokens_in_initcodes</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre><h4 id="transaction-validation">Transaction validation</h4> <ul> <li><code>InitcodeTransaction</code> is invalid if there are zero entries in <code>initcodes</code>, or if there are more than <code>MAX_INITCODE_COUNT</code> entries.</li> <li><code>InitcodeTransaction</code> is invalid if any entry in <code>initcodes</code> is zero length, or if any entry exceeds <code>MAX_INITCODE_SIZE</code>.</li> <li><code>InitcodeTransaction</code> is invalid if the <code>to</code> is <code>nil</code>.</li> </ul> <p>Under transaction validation rules <code>initcodes</code> are not validated for conforming to the EOF specification. They are only validated when accessed via <code>TXCREATE</code>. This avoids potential DoS attacks of the mempool. If during the execution of an <code>InitcodeTransaction</code> no <code>TXCREATE</code> instruction is called, such transaction is still valid.</p> <p>Other creation transactions that support contract creation (specifically type 0 "Frontier," type 1 "AccessList," type 2 "FeeMarket" transactions with an empty <code>to</code> field) will not attempt to parse EOF containers in their <code>input</code> field and will execute the code as non-EOF code. This will result in immediately executing the undefined <code>0xEF</code> instruction and halting.</p> <h4 id="rlp-and-signature">RLP and signature</h4> <p>Given the definitions from <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> the <code>TransactionPayload</code> for an <code>InitcodeTransaction</code> is the RLP serialization of:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, value, data, access_list, initcodes, y_parity, r, s]</span></span></code></pre> <p><code>TransactionType</code> is <code>INITCODE_TX_TYPE</code> and the signature values <code>y_parity</code>, <code>r</code>, and <code>s</code> are calculated by constructing a secp256k1 signature over the following digest:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>keccak256(INITCODE_TX_TYPE || rlp([chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, value, data, access_list, initcodes]))</span></span></code></pre> <p>The <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>ReceiptPayload</code> for this transaction is <code>rlp([status, cumulative_transaction_gas_used, logs_bloom, logs])</code>.</p> <h3 id="execution-semantics">Execution Semantics</h3> <p>Wherever not explicitly listed, the rules of EOF contract creation, as well as the <code>TXCREATE</code> instruction, should be identical or analogous to those of <code>CREATE2</code> instruction. This includes but is not limited to:</p> <ul> <li>behavior on <code>accessed_addresses</code> and address collision (<a href="https://wg-eips.ritovision.com/684/">EIP-684</a> and <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>)</li> <li>EVM execution frame created for the <code>TXCREATE</code> initcode - memory, account context etc.</li> <li>nonce bumping of the account of newly created contract <a href="https://wg-eips.ritovision.com/161/">EIP-161</a></li> <li>balance checking and transfer for the creation endowment (<code>value</code> argument)</li> </ul> <p>Introduce a new instruction on the same block number <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> is activated on: <code>TXCREATE</code> (<code>0xed</code>).</p> <h4 id="txcreate"><code>TXCREATE</code></h4> <ul> <li>deduct <code>TX_CREATE_COST</code> gas</li> <li>halt with exceptional failure if the current frame is in <code>static-mode</code>.</li> <li>pop <code>tx_initcode_hash</code>, <code>salt</code>, <code>input_offset</code>, <code>input_size</code>, <code>value</code> from the operand stack</li> <li>perform (and charge for) memory expansion using <code>[input_offset, input_size]</code></li> <li>load initcode EOF container from the transaction <code>initcodes</code> array which hashes to <code>tx_initcode_hash</code> <ul> <li>fails (returns 0 on the stack) if such initcode does not exist in the transaction, or if called from a transaction of <code>TransactionType</code> other than <code>INITCODE_TX_TYPE</code> <ul> <li>caller's nonce is not updated and gas for initcode execution is not consumed.</li> </ul> </li> <li>let <code>initcontainer</code> be that EOF container, and <code>initcontainer_size</code> its length in bytes</li> </ul> </li> <li>check that current call depth is below <code>STACK_DEPTH_LIMIT</code> and that caller balance is enough to transfer <code>value</code> <ul> <li>in case of failure return 0 on the stack, caller's nonce is not updated and gas for initcode execution is not consumed.</li> </ul> </li> <li><strong>validate the initcode container and all its subcontainers recursively</strong> <ul> <li>unlike in general validation, <code>initcontainer</code> is additionally required to have <code>data_size</code> declared in the header equal to actual <code>data_section</code> size.</li> <li>validation includes checking that the <code>initcontainer</code> does not contain <code>RETURN</code> or <code>STOP</code></li> </ul> </li> <li>fails (returns 0 on the stack) if container was invalid <ul> <li>caller’s nonce is not updated and gas for initcode execution is not consumed.</li> </ul> </li> <li>caller's memory slice <code>[input_offset:input_size]</code> is used as calldata</li> <li>execute the container and deduct gas for execution. The 63/64th rule from <a href="https://wg-eips.ritovision.com/150/">EIP-150</a> applies.</li> <li>increment <code>sender</code> account's nonce</li> <li>calculate <code>new_address</code> as <code>keccak256(0xff || sender32 || salt)[12:]</code>, where <code>sender32</code> is the sender address left-padded to 32 bytes with zeros</li> <li>an unsuccessful execution of initcode results in pushing <code>0</code> onto the stack <ul> <li>can populate returndata if execution <code>REVERT</code>ed</li> <li><code>sender</code>'s nonce stays updated</li> </ul> </li> <li>a successful execution ends with initcode executing <code>RETURNCODE{deploy_container_index}(aux_data_offset, aux_data_size)</code> instruction (see <a href="https://wg-eips.ritovision.com/7620/">EIP-7620</a>). After that: <ul> <li>load deploy EOF subcontainer at <code>deploy_container_index</code> in the container from which <code>RETURNCODE</code> is executed</li> <li>concatenate data section with <code>(aux_data_offset, aux_data_offset + aux_data_size)</code> memory segment and update data size in the header</li> <li>if updated deploy container size exceeds <code>MAX_CODE_SIZE</code>, instruction exceptionally aborts</li> <li>set <code>state[new_address].code</code> to the updated deploy container</li> <li>push <code>new_address</code> onto the stack</li> </ul> </li> <li>deduct <code>GAS_CODE_DEPOSIT * deployed_code_size</code> gas</li> </ul> <p>Note that the implementations are expected to cache the result of container validation for the time of current transaction execution, and therefore the cost of each container's validation is sufficiently covered by <code>InitcodeTransaction</code> intrinsic cost (initcodes charge).</p> <h2 id="rationale">Rationale</h2> <h3 id="txcreate-failure-modes"><code>TXCREATE</code> failure modes</h3> <p><code>TXCREATE</code> has two "light" failure modes in case the initcontainer is not present and in case the EOF validation is unsuccessful. An alternative design where both cases led to a "hard" failure (consuming the entire gas available) was considered. We decided to have the more granular and forgiving failure modes in order to align the gas costs incurred to the actual work the EVM performs.</p> <h3 id="allowing-txcreate-in-legacy-evm">Allowing <code>TXCREATE</code> in legacy EVM</h3> <p>EOF contract creation requires an exceptional possibility of calling an EOF opcode in legacy code - <code>TXCREATE</code>, because otherwise neither legacy contracts nor create transactions can deploy EOF code to bootstrap. The alternative approach was to continue using legacy creation mechanisms, by either still relying on fetching the <em>initcode</em> from memory and not satisfy the overarching requirement of code non-observability, or to abuse the legacy creation transactions mechanism, or to introduce a predeployed Creator Contract into the state.</p> <p>This also makes <a href="https://wg-eips.ritovision.com/7698/">EIP-7698</a> (EOF - Creation transaction) no longer an essential requirement for deploying EOF contracts onto the chain. The EIP could be removed from EOFv1 and withdrawn.</p> <h3 id="new-address-hashing-scheme">New address hashing scheme</h3> <p><code>TXCREATE</code> uses the scheme <code>new_address = keccak256(0xff || sender32 || salt)[12:]</code>, same as <code>EOFCREATE</code> instruction. The decision whether to include initcontainer hash into salt is left to the <code>TXCREATE</code> caller. See <a href="https://wg-eips.ritovision.com/7620/">EIP-7620</a> for detailed rationale.</p> <h3 id="eof-creation-transactions-vs-deployment-patterns">EOF creation transactions vs deployment patterns</h3> <p>Relying on the EOF creation transactions as the alternative solution makes it impossible for smart contract wallets to deploy arbitrary EOF contracts (only EOAs can). At the same time, it is a use case current legacy creation rules allow, thanks to <code>CREATE</code> and <code>CREATE2</code> instructions. A workaround where those arbitrary EOF contracts are first "uploaded" to a factory contract, and then deployed using an <code>EXTDELEGATECALL</code>-<code>EOFCREATE</code> sequence, is very expensive, as it requires the deployed contract to be put on-chain twice. Because of this, the approach proposed in this EIP is more compatible with the Account Abstraction (AA) roadmap, where smart contract wallets should have feature parity with EOAs.</p> <p>On top of this, relying on nonce-based hashing scheme to obtain addresses of newly created contracts, like in the case of the EOF creation transactions, would prevent EOF contracts from being deployed counterfactually to deterministic, cross-chain addresses. Introduction of the <code>TXCREATE</code> instruction, supports this out of the box. ERCs can be written to provide toehold contracts which will cater for the deployment patterns, such as salt-less deployment and hashing in the sender's address as part of the salt.</p> <h3 id="handling-of-0xef00-prefixed-code-in-existing-transaction-types">Handling of <code>0xEF00</code> prefixed code in existing transaction types.</h3> <p>Three existing transaction types (type 0 "Frontier," type 1 "AccessList," type 2 "FeeMarket") accept code as part of their input data in certain configurations. This code can start with <code>EF</code> as it is initcode and not a deployed contract.</p> <p>One possible way of handling potential EOF containers in these transactions is to make them invalid if they are attempting to execute an EOF container as initcode. Specifically the transactions is invalid if the input data begins with <code>0xef00</code> and if the <code>to</code> field is set to nil, signaling a contract creation transaction. This would make blocks containing these transactions invalid, whereas before the fork including this EIP they would have been valid.</p> <p>One impact that would be seen by this would be block builders, as they would need to ensure that the transactions that are invalid are not included in a block. There is precedent for this, as <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> established a new floor for the gas limit in transactions, prior to its adoption the limit was lower. However, block builders have an existing check on gas limits and transactions and that change was adjusting the formula and constants.</p> <p>We should also consider the treatment <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegation designations receive if they show up as code in a contract creation transaction. The transaction is valid, is executed as plain bytecode, ad the first operation executed is <code>0xEF</code>, which is an invalid opcode and would cause the whole transaction to abort.</p> <p>Letting the inputdata of a type 0, 1, and 2 contract creation transaction execute as plain EVM code irrespective of the magic <code>0xEF00</code> bytes keeps a consistent behavior in client code and keeps block builders from having to update their logic in older transaction types.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change poses no risk to backwards compatibility, as it is introduced at the same time EIP-3540 is. Despite the new instruction being introduced for legacy bytecode (code which is not EOF formatted), there is little chance that a meaningful contract would unintentionally execute <code>0xed</code> instruction with formally valid operands and inadvertently cause it to run EOF initcode (which would also require an <code>InitcodeTransaction</code> to be used, otherwise the initcode lookup will fail).</p> <p><code>TXCREATE</code> instruction introduction into legacy EVM does not affect <code>JUMPDEST</code> analysis, because instruction has no immediate arguments.</p> <p>The transactions of the new type are invalid until this change activates.</p> <p>Contract creation options do not change for legacy bytecode, including how existing transactions with <code>to: nil</code> behave when encountering code in their calldata that may look like an EOF container.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-01-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Josh Weintraubhttps://github.com/jhweintraub https://wg-eips.ritovision.com/7877/

Deprecate RETURN opcode in favor of new opcodes that allow returning data from various locations without first having to write to memory.

<h2 id="abstract">Abstract</h2> <p>This EIP specifies a series of new <code>RETURN</code> opcodes which allow the user to specify which data location to return from instead of defaulting to returning from memory.</p> <h2 id="motivation">Motivation</h2> <p>With the introduction of transient storage, many smart contracts have begun to store data using the new transient opcodes to optimize for gas usage, whereby a callback involves returning the data previously stored transiently. However, the current <code>RETURN</code> opcode only allows for returning sequential bytes in memory. This requires developers to incur additional gas overhead by manually writing data from transient storage to memory before returning, incuring both an additional memory expansion and opcode cost from complicated for-loops. Similar inefficiencies already occur when attempting to return data already placed in storage. This EIP attempts to rectify this by allowing developers to optimize their code by deciding where to return data from directly, instead of requiring the intermediate step of first copying the data to memory.</p> <h2 id="specification">Specification</h2> <p>This EIP introduces 3 new opcodes as well as renaming/aliasing an existing one.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>SRETURN (0xf6)</span></span> <span class="giallo-l"><span>TRETURN (0xf7)</span></span> <span class="giallo-l"><span>RRETURN (0xf8)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>RETURN -&gt; MRETURN (0xf3)</span></span></code></pre> <p>The <code>MRETURN</code> opcode is a rename of <code>RETURN</code>, whereby sequential bytes in memory are returned. It will operate exactly as it currenty does as of the Cancun hard-fork, and its gas cost will remain the same.</p> <p><code>RRETURN</code> operates similar to <code>MRETURN</code>. It pops two items off the stack, an offset to begin reading bytes from in the existing <code>RETURNDATA</code> buffer, and a number of bytes to return. Those bytes are used to overwrite the existing <code>RETURNDATA</code> buffer and then a return to the previous function is performed.</p> <p><code>SRETURN</code> and <code>TRETURN</code> operate similarly, except on storage and transient respectively. It pops two items off the stack, a slot number to begin reading from, and a number of sequential slots to return from. Ex: <code>SRETURN(0x0, 0x40)</code> returns the 64 bytes of data in slots [0, 1], and <code>TRETURN(0x0, 0x40)</code> returns the data in transient storage slots [0, 1]. Since the existing <code>S/TLOAD</code> opcodes already return 32-bytes, having the opcode return data in chunks of 32-bytes should make implementation by assembly/compiler much simpler. If the length parameter is a zero, then only the initial slot value should be returned, so <code>SRETURN(0x00, 0x00)</code> returns the value at storage slot 0.</p> <p>The cost for these opcodes should be similar to the cost of accessing data now.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>SRETURN = (number_of_cold_slots) * 2100 + (numer_of_warm_slots * 100)</span></span> <span class="giallo-l"><span>TRETURN = number_of_slots * 100</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>RRETURN = cost of RETURNDATACOPY without memory_expansion cost</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>minimum_word_size = (size + 31) / 32</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>static_gas = 3</span></span> <span class="giallo-l"><span>dynamic_gas = 3 * minimum_word_size</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>overall = static_gas + dynamic_gas</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Allowing for more targeted return opcodes allows for saving gas at all levels of smart contract optimization by eliminating the intermediate steps of first writing any data to memory before returning. In events where this data may be large, this can result in significant gas savings. These opcodes can be built into the Solidity compiler directly so that all contracts can take advantage of them. Similarly, by making return more explicit it allows for better static analysis by avoiding messy memory allocations.</p> <p>There is precedent for these changes.</p> <p>EIP-3855: Introducing <code>PUSH0</code> opcode to optimize away alternative methods of pushing 0 onto the stack.</p> <p>EIP-6: Renaming <code>SUICIDE</code> to <code>SELFDESTRUCT</code> without changing functionality.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backwards compatibility concerns, as <code>MRETURN</code> will utilize the same gas cost and opcode as <code>RETURN</code> does now. Due to EOF, it is suggested that these changes be activated in future EVM version once EOF has been fully implemented.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no security considerations as it is fully backwards compatible, and reduces potential attack space through simplified bytecode.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2025-01-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Sam Wilsonhttps://github.com/SamWilsnsam@binarycake.ca https://wg-eips.ritovision.com/7867/

An EIP-5792 capability providing atomicity and flow control configuration.

<h2 id="abstract">Abstract</h2> <p>This proposal extends <a href="https://wg-eips.ritovision.com/5792/">EIP-5792</a> to allow dapps to downgrade their required atomicity guarantees and control the behaviour after a failed/reverted call. It introduces the batch-scope concept of <code>strict</code> vs. <code>loose</code> atomicity, where a <code>strict</code> batch remains atomic in the face of chain reorgs and a <code>loose</code> batch does not; and the per-call ability to continue after a failed/reverted call (<code>continue</code>) or stop processing (<code>halt</code>).</p> <h2 id="motivation">Motivation</h2> <p>While the base EIP-5792 specification works extremely well for smart contract wallets, it does not allow the expression of the full range of flow control options that wallets can implement. For example, a dapp may only be submitting a batch for gas savings and not care about whether all calls are reverted on failure. A wallet may only be able to offer a limited form of atomicity through block builder backchannels, but that may be sufficient for a trading platform.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="rpc-interface">RPC Interface</h3> <p>The following subsections are modifications to the API endpoints from EIP-5792.</p> <p>If a request does not match the schema defined below, the wallet MUST reject the request with an error code of <code>INVALID_SCHEMA</code>.</p> <h4 id="wallet-sendcalls"><code>wallet_sendCalls</code></h4> <p>The following JSON Schema SHALL be inserted, in the request object, as values of either the batch-scope or call-scope <code>capabilities</code> objects (as appropriate) with a key of <code>flowControl</code>.</p> <h5 id="batch-scope">Batch-scope</h5> <h6 id="schema">Schema</h6> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$schema</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://json-schema.org/draft/2020-12/schema</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">optional</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">boolean</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">atomicity</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">enum</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">strict</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">loose</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">none</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h6 id="example-request">Example Request</h6> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">from</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chainId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x01</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">calls</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">capabilities</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">flowControl</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">atomicity</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">loose</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>]</span></span> <span class="giallo-l"></span></code></pre><h5 id="call-scope">Call-scope</h5> <h6 id="schema-1">Schema</h6> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$schema</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://json-schema.org/draft/2020-12/schema</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">optional</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">boolean</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">onFailure</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">enum</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">rollback</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">halt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">continue</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h6 id="example-request-1">Example Request</h6> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">from</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chainId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x01</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">calls</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">to</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd46e8dd67c5d32be8058bb8eb970870f07244567</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">value</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x182183</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">data</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xfbadbaf01</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">capabilities</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">flowControl</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">onFailure</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">continue</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h4 id="wallet-getcapabilities"><code>wallet_getCapabilities</code></h4> <p>The following JSON Schema is inserted into the per-chain object returned from <code>wallet_getCapabilities</code> with a key of <code>flowControl</code>.</p> <h5 id="schema-2">Schema</h5> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$schema</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://json-schema.org/draft/2020-12/schema</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">none</span><span class="z-support">&quot;</span><span>:</span><span> {</span><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/onFailure</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">loose</span><span class="z-support">&quot;</span><span>:</span><span> {</span><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/onFailure</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">strict</span><span class="z-support">&quot;</span><span>:</span><span> {</span><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/onFailure</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$defs</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">onFailure</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">array</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">uniqueItems</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minItems</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">items</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">enum</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">rollback</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">halt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">continue</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="example-response">Example Response</h5> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">flowControl</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">loose</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">halt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">continue</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">strict</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">continue</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="concepts">Concepts</h3> <h4 id="call-failure">Call Failure</h4> <!-- TODO: is a "call failure" the same as a "revert"? --> <h4 id="rollback">Rollback</h4> <p>A rollback is informally defined as "causing no meaningful changes on chain." A rolled back batch only makes gas accounting and bookkeeping (eg. nonce) changes. In other words, a rollback is the default behaviour of EIP-5792 when a call fails.</p> <h4 id="critical-calls">Critical Calls</h4> <p>A critical call is a call that causes the entire batch to rollback on failure, and correspondingly a non-critical call does not. Specifically, a critical call has a call-scope <code>onFailure</code> of <code>rollback</code> (or no <code>onFailure</code> present), while non-critical calls have either <code>halt</code> or <code>continue</code>.</p> <h4 id="atomicity-levels">Atomicity Levels</h4> <p>This proposal introduces three atomicity levels: strict, loose, and none; enabled by setting batch-scope <code>atomicity</code> to <code>strict</code>, <code>loose</code>, or <code>none</code> respectively. Strict may also be enabled by omitting <code>atomicity</code> entirely.</p> <p>Strict atomicity is simply naming the default behaviour of EIP-5792: calls within a single batch MUST be contiguous and applied atomically (or the batch rolled back.)</p> <p>Loose atomicity, on the other hand, is a weaker guarantee. In the event of a block reorg, any number of calls from the batch MAY appear on chain (possibly interspersed with other transactions). If there are no block reorgs, loose atomicity MUST provide the same guarantees as strict.</p> <p>The none level of atomicity only provides the guarantee that the calls appear on chain in the order they are in the batch. Any number of calls from the batch MAY appear on chain (possibly interspersed with other transactions).</p> <h3 id="behaviour">Behaviour</h3> <h4 id="wallet-sendcalls-1"><code>wallet_sendCalls</code></h4> <p>The wallet MUST reject <code>wallet_sendCalls</code> requests with error code <code>MISSING_CAP</code> where both:</p> <ul> <li>the batch-scope <code>flowControl</code> capability <strong>is not</strong> present; and</li> <li>a call-scope <code>flowControl</code> capability <strong>is</strong> present.</li> </ul> <p>Note that the above requirement still applies if the call-scope <code>flowControl</code> capability is marked as optional.</p> <p>When <code>flowControl</code> is present in the batch-scope <code>capabilities</code>, the following changes override the behaviour specified in EIP-5792.</p> <h5 id="removed-requirements">Removed Requirements</h5> <p>These requirements defined in EIP-5792 are removed:</p> <blockquote> <p>The wallet:</p> <ul> <li>MUST NOT await for any calls to be finalized to complete the batch</li> <li>MUST submit multiple calls as an atomic unit in a single transaction</li> <li>MAY revert all calls if any call fails</li> <li>MUST not execute any further calls after a failed call</li> <li>MAY reject the request if one or more calls in the batch is expected to fail, when simulated sequentially</li> </ul> </blockquote> <h5 id="added-requirements">Added Requirements</h5> <p>The wallet:</p> <h6 id="batch-atomicity">Batch Atomicity</h6> <ul> <li>MAY break the batch over multiple transactions.</li> <li>MUST treat a missing batch-scope <code>atomicity</code> level as equivalent to <code>strict</code>.</li> <li>MUST provide strict guarantees (as defined above) when the batch-scope <code>atomicity</code> is <code>strict</code>.</li> <li>MUST provide <em>at least</em> loose guarantees (as defined above) when the batch-scope <code>atomicity</code> is <code>loose</code>.</li> <li>MUST provide <em>at least</em> the in-order call inclusion guarantee (as defined above) when the batch-scope <code>atomicity</code> is <code>none</code>.</li> <li>MAY provide loose guarantees (as defined above) when the batch-scope <code>atomicity</code> is <code>none</code>.</li> <li>MAY provide strict guarantees (as defined above) when the batch-scope <code>atomicity</code> is <code>loose</code> or <code>none</code>.</li> <li>MUST rollback the batch if one or more critical calls (as defined above) fail.</li> <li>MUST NOT rollback the batch if zero critical calls (as defined above) fail. <ul> <li>In other words, if the only failures are non-critical, the successful calls have to appear on chain.</li> </ul> </li> <li>MUST NOT execute a call (or ever allow a call to be executed) more than once.</li> </ul> <h6 id="flow-control">Flow Control</h6> <ul> <li>MUST treat a missing call-scope <code>flowControl</code> capability as equivalent to setting <code>onFailure</code> to <code>rollback</code>.</li> <li>MUST treat a missing call-scope <code>onFailure</code> mode as equivalent to <code>rollback</code>.</li> <li>MUST NOT execute any calls following a failed call with <code>onFailure</code> set to <code>halt</code>.</li> <li>MUST continue to execute calls as normal following a failed call with <code>onFailure</code> set to <code>continue</code>.</li> </ul> <h6 id="errors">Errors</h6> <ul> <li>MUST reject (with error code <code>REJECTED_LEVEL</code>) batches containing at least one critical call if the batch requests an atomicity level that the wallet can provide but the user rejected (such as might happen with an <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> set code transaction.) <ul> <li>Note that this only applies to user rejections specifically because of atomicity. It does not change the behaviour for batches rejected for other reasons. This error code MUST NOT be used for other rejection reasons.</li> </ul> </li> <li>MUST reject (with error code <code>UNSUPPORTED_LEVEL</code>) batches containing at least one critical call if the batch requests an atomicity level the wallet cannot provide for any reason other than user rejection. <ul> <li>Wallets supporting <code>strict</code> but not <code>loose</code> SHOULD NOT reject <code>loose</code> batches and SHOULD instead upgrade the request to strict atomicity.</li> <li>Note that a batch with exactly one call <em>always</em> satisfies the requirements of strict atomicity.</li> </ul> </li> <li>MUST reject (with error code <code>UNSUPPORTED_ON_FAIL</code>) batches containing unsupported <code>onFailure</code> modes.</li> <li>MUST reject (with error code <code>UNSUPPORTED_FLOW</code>) batches containing unsupported combinations/orderings of call-scope <code>onFailure</code> modes. <ul> <li>Wallets MUST reject <code>rollback</code> when used in a <code>none</code> batch, even if the batch is upgraded to <code>loose</code> or <code>strict</code> atomicity. This also applies to calls that do not specify an explicit <code>onFailure</code> mode.</li> </ul> </li> <li>MAY reject (with error code <code>ROLLBACK_EXPECTED</code>) the request if the batch is expected to be rolled back.</li> <li>SHOULD inform the user before executing any calls if any call in the batch is expected to fail.</li> </ul> <h4 id="wallet-getcallsstatus"><code>wallet_getCallsStatus</code></h4> <p>When <code>wallet_getCallsStatus</code> is called with a batch identifier corresponding to a batch submitted with the batch-scope <code>flowControl</code> capability enabled, the following changes override the behaviour defined in EIP-5792. Note that:</p> <ul> <li>There are no changes when called with a batch without this capability enabled; and</li> <li>Even if the behaviour of the batch is not changed from the default (eg. setting <code>atomicity</code> to <code>strict</code> and omitting the <code>flowControl</code> capability for all calls), the following changes still apply.</li> </ul> <h5 id="removed-requirements-1">Removed Requirements</h5> <p>These requirements defined in EIP-5792 are removed:</p> <blockquote> <ul> <li>If a wallet executes multiple calls <strong>atomically</strong> in a single transaction, <code>wallet_getCallsStatus</code> MUST return an object with a <code>receipts</code> field that contains a single transaction receipt, corresponding to the transaction in which the calls were included.</li> <li>If a wallet executes multiple calls <strong>non-atomically</strong> through some <code>capability</code> defined elsewhere, <code>wallet_getCallsStatus</code> MUST return an object with a <code>receipts</code> field that contains <strong>an array of receipts</strong> for all transactions containing batch calls that were included onchain. This includes the batch calls that were included on-chain but eventually reverted.</li> </ul> </blockquote> <h5 id="added-requirements-1">Added Requirements</h5> <h6 id="capabilities">Capabilities</h6> <p>The returned capabilities object:</p> <ul> <li>MUST contain a <code>flowControl</code> key set to exactly the boolean <code>true</code>. <ul> <li>It may be tempting to include additional detail about the status of individual calls here, but don't. Instead use a multi-status capability defined elsewhere.</li> </ul> </li> </ul> <h6 id="receipts">Receipts</h6> <p>The returned <code>receipts</code> array:</p> <ul> <li>MUST NOT contain more than one receipt for the same transaction.</li> <li>SHOULD NOT contain receipts for transactions without a call from the requested batch.</li> <li>MUST contain exactly one receipt capturing each successful call. <ul> <li>Multiple calls MAY be captured in one receipt, but the successful execution of one call MUST NOT be captured by multiple receipts.</li> <li>Given two calls (<em>A</em> and <em>B</em>) in a batch, the following are non-exhaustive example combinations of calls-per-receipt. Each <code>(...)</code> is a receipt from a single transaction. <ul> <li>Valid Examples: <ul> <li><code>[(successful A, successful B)]</code></li> <li><code>[(successful A), (successful B)]</code></li> <li><code>[(successful A, unsuccessful B), (successful B)]</code></li> <li><code>[(unsuccessful A), (successful A), (successful B)]</code></li> </ul> </li> <li>Invalid Examples: <ul> <li><code>[(successful A, unsuccessful B), (successful A, successful B)]</code></li> <li><code>[(successful A, successful A), (successful B)]</code></li> </ul> </li> </ul> </li> </ul> </li> <li>MAY contain one or more receipts capturing each failed call. <ul> <li>For example, the wallet may retry a transaction with a higher gas limit. Both the failed and successful transaction receipts can be included, though only the successful receipt must be.</li> </ul> </li> <li>SHOULD be stable over multiple <code>wallet_getCallsStatus</code> requests, with only new receipts being appended. <ul> <li>For example: <ul> <li><code>[(unsuccessful A)]</code> followed by <code>[(unsuccessful A), (successful A)]</code> is valid; but</li> <li><code>[(unsuccessful A)]</code> followed by <code>[(successful A)]</code> should be avoided.</li> </ul> </li> </ul> </li> </ul> <h5 id="status-codes">Status Codes</h5> <p>This proposal modifies some of the status codes for use with EIP-5792's <code>GetCallsResult.status</code> field, and introduces the following new codes:</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>102</code></td><td>Partially Executed</td></tr> <tr><td><code>207</code></td><td>Partial Success</td></tr> </tbody></table> <p>An "included" call, in this section, is defined as having either been successfully or unsuccessfully executed. A call that has been recorded on chain, but has not yet been executed, does not qualify as included. Executed calls contained in batches that may still be rolled back also do not qualify as included.</p> <p>A batch is "complete" when all of the calls in the batch (up to and including a failed call with an <code>onFailure</code> mode of <code>halt</code> should one be present) have been included and the wallet will not resubmit failed calls.</p> <h6 id="100-pending"><code>100</code> Pending</h6> <p>Status <code>100</code> MUST NOT be returned if any calls in the batch have been included on chain.</p> <h6 id="102-partially-executed"><code>102</code> Partially Executed</h6> <p>Status <code>102</code> SHALL be returned only when all of the following are true:</p> <ul> <li>At least one call in the batch has been included on chain; and</li> <li>The batch is not complete.</li> </ul> <p>Responses with status <code>102</code> MUST contain at least one receipt, and SHOULD contain receipts for all transactions with calls that have been included.</p> <p>Note that a receipt capturing a failed call does not mean the call will ultimately fail. Wallets can resubmit calls (eg. with a higher gas limit), and the call may be executed successfully eventually.</p> <h6 id="200-confirmed"><code>200</code> Confirmed</h6> <p>Status <code>200</code> MUST NOT be returned if any calls in the batch failed (including batch rollback, and the <code>onFailure</code> modes <code>halt</code>/<code>continue</code>).</p> <h6 id="207-partial-success"><code>207</code> Partial Success</h6> <p>Status <code>207</code> SHALL be returned only when all of the following are true:</p> <ul> <li>At least one call in the batch has been included and succeeded;</li> <li>At least one call in the batch with an <code>onFailure</code> mode of <code>continue</code> has been included and failed;</li> <li>No calls with an <code>onFailure</code> mode of <code>rollback</code> have been included and failed;</li> <li>No calls with an <code>onFailure</code> mode of <code>halt</code> have been included and failed; and</li> <li>The batch is complete.</li> </ul> <h6 id="500-chain-rules-failure"><code>500</code> Chain Rules Failure</h6> <p>To clarify, status <code>500</code> is the correct code when the batch has rolled back <em>or</em> when all calls are non-critical and have all failed.</p> <p>If any calls are included and succeeded, one of <code>200</code>, <code>207</code>, or <code>600</code> should be returned instead.</p> <h6 id="600-partial-chain-rules-failure"><code>600</code> Partial Chain Rules Failure</h6> <p>Status <code>600</code> SHALL be returned only when all of the following are true:</p> <ul> <li>At least one call in the batch has been included and succeeded;</li> <li>At least one call in the batch with an <code>onFailure</code> mode of <code>halt</code> has been included and failed;</li> <li>No calls with an <code>onFailure</code> mode of <code>rollback</code> have been included and failed; and</li> <li>The batch is complete.</li> </ul> <h4 id="wallet-getcapabilities-1"><code>wallet_getCapabilities</code></h4> <p>The response to <code>wallet_getCapabilities</code> indicates what call-scope <code>onFailure</code> modes are supported for each supported batch-scope <code>atomicity</code> level for batches with two or more calls. Support, here, means "natively supports." A wallet that offers <code>strict</code> atomicity but not <code>loose</code> MUST NOT advertise support for <code>loose</code> (even if the wallet will upgrade <code>loose</code> to <code>strict</code> without an error.)</p> <p>The wallet:</p> <ul> <li>MAY respond with one, two, or three <code>atomicity</code> levels.</li> <li>MAY respond with one, two, or three <code>onFailure</code> modes in each <code>atomicity</code> level. The levels do not need to support the same modes.</li> <li>MUST include the particular atomicity / onFailure combination if it is supported <em>at all</em>. For example, if particular orderings are impossible—say <code>rollback</code> before <code>halt</code> is fine, but <code>halt</code> before <code>rollback</code> is not—then both <code>rollback</code> and <code>halt</code> have to be included in the array.</li> </ul> <h5 id="examples">Examples</h5> <h6 id="plain-externally-owned-account-eoa">Plain Externally Owned Account (EOA)</h6> <p>A plain EOA might offer <code>halt</code> functionality by submitting one transaction per block, and <code>continue</code> by submitting all calls at once.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">flowControl</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">none</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">halt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">continue</span><span class="z-punctuation z-definition z-string">&quot;</span><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h6 id="shielded-mempool-externally-owned-account-eoa">Shielded Mempool Externally Owned Account (EOA)</h6> <p>Unlike a plain EOA, a shielded mempool can provide additional guarantees about transaction atomicity. In this example, the wallet only offers the <code>onFailure</code> mode of <code>continue</code> when using <code>none</code> atomicity, but offers all three levels when using <code>loose</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">flowControl</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">none</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">continue</span><span class="z-punctuation z-definition z-string">&quot;</span><span> ]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">loose</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">rollback</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">halt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">continue</span><span class="z-punctuation z-definition z-string">&quot;</span><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h6 id="smart-contract-wallet">Smart Contract Wallet</h6> <p>In this example, the wallet will service batches specifying <code>none</code> and <code>loose</code> as if they requested <code>strict</code>. Even though the batches will work, the <code>wallet_getCapabilities</code> response does not list <code>none</code> or <code>loose</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">flowControl</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">strict</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">rollback</span><span class="z-punctuation z-definition z-string">&quot;</span><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="error-codes">Error Codes</h3> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>INVALID_SCHEMA</code></td><td><!-- TODO --></td></tr> <tr><td><code>MISSING_CAP</code></td><td><!-- TODO --></td></tr> <tr><td><code>REJECTED_LEVEL</code></td><td><!-- TODO --></td></tr> <tr><td><code>UNSUPPORTED_LEVEL</code></td><td><!-- TODO --></td></tr> <tr><td><code>UNSUPPORTED_ON_FAIL</code></td><td><!-- TODO --></td></tr> <tr><td><code>UNSUPPORTED_FLOW</code></td><td><!-- TODO --></td></tr> <tr><td><code>ROLLBACK_EXPECTED</code></td><td><!-- TODO --></td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <!-- The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The current placeholder is acceptable for a draft. TODO: Remove this comment before submitting --> <p>TBD</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <!-- This section is optional. All EIPs that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The EIP must explain how the author proposes to deal with these incompatibilities. EIP submissions without a sufficient backwards compatibility treatise may be rejected outright. The current placeholder is acceptable for a draft. TODO: Remove this comment before submitting --> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>App developers cannot treat each call in a batch as an independent transaction unless the atomicity level is strict. In other words, there may be additional untrusted transactions between any of the calls in a batch. Calls that failed may eventually flip to succeeding, and vice versa. Even strictly atomic batches can flip between succeeding/failing in the face of a block reorg. The calls in loosely atomic batches can be included in separate, non-contiguous blocks. There is no constraint over how long it will take all the calls in a batch to be included. Apps should encode deadlines and timeout behaviors in the smart contract calls, just as they do today for transactions, including ones otherwise bundled.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-12-27T00:00:00+00:00 2026-02-11T14:49:28+00:00 Liyi Guohttps://github.com/colinlyguo https://wg-eips.ritovision.com/7851/

Introduce a new precompiled contract for EOAs with delegated code to deactivate or reactivate private keys.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a precompiled contract that enables Externally Owned Accounts (EOAs) with delegated control to smart contracts via <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> to deactivate or reactivate their private keys. This design does not require additional storage fields or account state changes. By leveraging delegated code, reactivation can be performed securely through mechanisms such as social recovery.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> enables EOAs to gain smart contract capabilities, but the private key of the EOA still retains full control over the account.</p> <p>With this EIP, EOAs can fully migrate to smart contract wallets, while retaining private key recovery options with reactivation. The flexible deactivate and reactivate design also paves the way for native account abstraction. e.g., <a href="https://wg-eips.ritovision.com/7701/">EIP-7701</a>.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>PRECOMPILE_ADDRESS</code></td><td><code>0xTBD</code></td></tr> <tr><td><code>PRECOMPILE_GAS_COST</code></td><td><code>13000</code></td></tr> </tbody></table> <h3 id="definitions">Definitions</h3> <ul> <li><code>||</code> is the byte/byte-array concatenation operator.</li> </ul> <h3 id="delegated-code-encoding">Delegated Code Encoding</h3> <p>The deactivation status is encoded by appending or removing the <code>0x00</code> byte at the end of the delegated code. The transitions between two states are as follows:</p> <ul> <li>Active state: <code>0xef0100 || address</code>. The private key is active and can sign transactions.</li> <li>Deactivated state: <code>0xef0100 || address || 0x00</code>. The private key is deactivated and cannot sign transactions or <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegation authorizations.</li> </ul> <h3 id="precompiled-contract">Precompiled Contract</h3> <p>A new precompiled contract is introduced at address <code>PRECOMPILE_ADDRESS</code>. It costs <code>PRECOMPILE_GAS_COST</code> and executes the following logic:</p> <ul> <li>Returns a precompile contract error, consumes all gas, and no state changes are made if: <ul> <li>Gas is insufficient.</li> <li>Called via <code>STATICCALL</code> (i.e., in a read-only context).</li> <li>Caller is not an EOA with delegated code (prefix <code>0xef0100</code> as per <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>).</li> </ul> </li> <li>Updates caller's delegated code based on length: <ul> <li><code>23</code> bytes (<code>0xef0100 || address</code>): Appends <code>0x00</code> to deactivate private key authorization.</li> <li><code>24</code> bytes (<code>0xef0100 || address || 0x00</code>): Removes last byte <code>0x00</code> to activate private key authorization.</li> </ul> </li> <li>Saves updated code as caller's new account code.</li> </ul> <h3 id="transaction-validation">Transaction Validation</h3> <p>Validation to check whether a private key is deactivated (identified by a code prefix <code>0xef0100</code> and a code length of <code>24</code>) MUST be performed in the following scenarios:</p> <ul> <li>During transaction validity checks before execution, nodes MUST reject transactions signed with deactivated private keys to ensure such transactions cannot be included in blocks.</li> <li>The same validation MUST be applied to the transaction pool when receiving new transactions to prevent invalid transactions from propagating through the network.</li> <li>Any <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> authorization issued by an authority with a deactivated private key MUST be treated as invalid and skipped.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="cost-of-precompiled-contract">Cost of Precompiled Contract</h3> <p>The <code>PRECOMPILE_GAS_COST</code> represents the gas required to validate and potentially update an account's code. A fair cost for calling this precompiled contract can be determined by analyzing its impact on the node:</p> <ul> <li>Reading the code of the address: <code>2600</code>.</li> <li>Changing the code hash (from non-zero to non-zero): <code>5000</code>.</li> <li>Deploying at most <code>24</code> bytes of code: <code>200 * 24 = 4800</code>.</li> </ul> <p>The primary operation consumes a total of <code>12400</code> gas. To account for additional overhead, such as context switching during state transitions, as well as code prefix and length validations, the cost is rounded up to <code>13000</code>.</p> <h3 id="additional-transaction-validation-overhead">Additional Transaction Validation Overhead</h3> <p>Due to <a href="https://wg-eips.ritovision.com/3607/">EIP-3607</a> and <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>, nodes already load the account code during transaction validation to verify whether the sender is an EOA (empty code or code with prefix <code>0xef0100</code>). This EIP introduces only a code length check after loading the code, resulting in minimal additional overhead. Similarly, <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>’s authorization validation already involves retrieving the account code, with this EIP adding only a code length check, which is negligible compared to code reading.</p> <p>Transaction pools already perform state-based checks, such as those for nonce and balance. This EIP adds an account code read and a length check, which together are comparable to nonce and balance validations. DoS prevention mechanisms, expected in transaction pools, also support these additional checks.</p> <h3 id="an-alternative-eoa-deprecation-approach">An Alternative EOA Deprecation Approach</h3> <p>An alternative deprecation approach involves using a hard fork to edit all existing and new EOAs to pre-written upgradeable smart contracts, which utilize the original EOA private key for authorization. Users can add and replace keys, or upgrade the smart contracts to other implementations. However, this approach is incompatible with EOAs already delegated to smart contracts, as it will overwrite the existing smart contract implementations. This EIP aims to fill this migration gap.</p> <h3 id="using-a-precompiled-contract">Using a Precompiled Contract</h3> <p>Alternative methods for deactivating and reactivating EOA private keys include:</p> <ul> <li>Adding a new transaction type: Introducing a new transaction type could provide a mechanism to deactivate and reactivate EOA private keys. However, reactivating the private key would rely on a delegated contract as the authorizer, which complicates defining the rules for the new transaction type.</li> <li>Deploying a smart contract: Compared to reusing the code field, using a smart contract has higher costs: (i) it requires new contract storage slots to track the deactivation status of each address (ii) executing bytecode increases the overhead of the node compared to precompiled contracts, (iii) during transaction validation, reusing the code field allows deactivation status check to be combined with existing code loading in some scenarios, thereby reducing the need for additional storage reads, as discussed in <a href="https://wg-eips.ritovision.com/7851/#additional-transaction-validation-overhead">Additional Transaction Validation Overhead</a> section.</li> </ul> <h3 id="in-protocol-reactivation">In-Protocol Reactivation</h3> <p>This approach ensures maximum compatibility with future migrations. EOAs can reactivate their private keys, delegate their accounts to an <a href="https://wg-eips.ritovision.com/7701/">EIP-7701</a> contract, and then deactivate their private keys again. This avoids the limitations of contract upgrades. e.g., to remove legacy proxy contracts (reducing gas overhead) when upgrading to EOF contracts, one can reactivate the EOA and redelegate it to an EOF proxy contract.</p> <p>Reactivation can only be performed by the delegated contract. Since reactivating the private key grants full control over the wallet, wallets must implement this interface with strict security measures. These measures should treat reactivation as the highest level of authority, equivalent to full wallet ownership. Users should delegate their EOAs only to wallets that have been thoroughly audited and follow best practices for security.</p> <h3 id="avoiding-delegated-code-prefix-modification">Avoiding Delegated Code Prefix Modification</h3> <p>This EIP appends a byte (<code>0x00</code>) to the delegated code instead of modifying the prefix (<code>0xef0100</code>) of <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> to ensure forward compatibility. If new prefixes such as <code>0xef0101</code> are introduced in the future, changing the prefix to represent the deactivated status (e.g., <code>0xef01ff</code>) makes it unclear which prefix to restore (<code>0xef0100</code> or <code>0xef0101</code>) upon reactivation.</p> <h3 id="avoiding-account-state-changes">Avoiding Account State Changes</h3> <p>An alternative is to add a <code>deactivated</code> field in the account state to track the status. However, this approach will introduce backward compatibility logic and more test vectors related to this optional field when enabling this EIP, because the field is not present in existing accounts.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>When the private key is deactivated, this EIP introduces: (i) an extra byte (<code>0x00</code>) to be appended to the end of the delegated code, and (ii) the delegated code length becomes <code>24</code> bytes (e.g., <code>EXTCODESIZE</code> would return <code>24</code>).</p> <p>These changes are not breaking. However, they require protocol, application, and contract implementations to use strict offsets to parse the delegated address correctly. Implementations must also check the delegated code prefix <code>0xef0100</code> to determine whether it represents an EOA with delegated code, while avoiding over-restrictive checks, such as asserting the code length to be exactly <code>23</code>.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Initialize the state database and precompiled contract</span></span> <span class="giallo-l"><span>state_db</span><span class="z-keyword"> =</span><span> StateDB</span><span>(</span><span>)</span></span> <span class="giallo-l"><span>precompile</span><span class="z-keyword"> =</span><span> PrecompiledContract</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Test 1: Valid activation and deactivation</span></span> <span class="giallo-l"><span>caller</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0123</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>delegated_addr</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span>.</span><span>fromhex</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1122334455667788990011223344556677889900</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span>active_code</span><span class="z-keyword"> =</span><span> PrecompiledContract</span><span>.</span><span class="z-constant">DELEGATED_CODE_PREFIX</span><span class="z-keyword"> +</span><span> delegated_addr</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Active state</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>state_db</span><span>.</span><span>set_code</span><span>(</span><span>caller</span><span>,</span><span> active_code</span><span>)</span></span> <span class="giallo-l"><span>error</span><span>,</span><span> gas_left</span><span class="z-keyword"> =</span><span> precompile</span><span>.</span><span>execute</span><span>(</span><span>caller</span><span>,</span><span> state_db</span><span>,</span><span class="z-variable"> gas</span><span class="z-keyword">=</span><span class="z-constant">15000</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> error</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> state_db</span><span>.</span><span>get_code</span><span>(</span><span>caller</span><span>)</span><span class="z-keyword"> ==</span><span> active_code</span><span class="z-keyword"> +</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant">\x00</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Deactivated state</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> gas_left</span><span class="z-keyword"> ==</span><span class="z-constant"> 15000</span><span class="z-keyword"> -</span><span> PrecompiledContract</span><span>.</span><span class="z-constant">PRECOMPILE_GAS_COST</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>error</span><span>,</span><span> gas_left</span><span class="z-keyword"> =</span><span> precompile</span><span>.</span><span>execute</span><span>(</span><span>caller</span><span>,</span><span> state_db</span><span>,</span><span class="z-variable"> gas</span><span class="z-keyword">=</span><span class="z-constant">15000</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> error</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> state_db</span><span>.</span><span>get_code</span><span>(</span><span>caller</span><span>)</span><span class="z-keyword"> ==</span><span> active_code</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Turns to the active state again</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> gas_left</span><span class="z-keyword"> ==</span><span class="z-constant"> 15000</span><span class="z-keyword"> -</span><span> PrecompiledContract</span><span>.</span><span class="z-constant">PRECOMPILE_GAS_COST</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Test 2: Error cases</span></span> <span class="giallo-l"><span>error</span><span>,</span><span> gas_left</span><span class="z-keyword"> =</span><span> precompile</span><span>.</span><span>execute</span><span>(</span><span>caller</span><span>,</span><span> state_db</span><span>,</span><span class="z-variable"> gas</span><span class="z-keyword">=</span><span class="z-constant">15000</span><span>,</span><span class="z-variable"> read_only</span><span class="z-keyword">=</span><span class="z-constant">True</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> error</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">STATICCALL disallows state modification</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> gas_left</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>error</span><span>,</span><span> gas_left</span><span class="z-keyword"> =</span><span> precompile</span><span>.</span><span>execute</span><span>(</span><span>caller</span><span>,</span><span> state_db</span><span>,</span><span class="z-variable"> gas</span><span class="z-keyword">=</span><span>PrecompiledContract</span><span>.</span><span class="z-constant">PRECOMPILE_GAS_COST</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> error</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">insufficient gas</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> gas_left</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>caller</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4567</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> EOA that is not delegated to code</span></span> <span class="giallo-l"><span>error</span><span>,</span><span> gas_left</span><span class="z-keyword"> =</span><span> precompile</span><span>.</span><span>execute</span><span>(</span><span>caller</span><span>,</span><span> state_db</span><span>,</span><span class="z-variable"> gas</span><span class="z-keyword">=</span><span class="z-constant">15000</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> error</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">the address is not an EOA delegated to code</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> gas_left</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>caller</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x89ab</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This is a contract address.</span></span> <span class="giallo-l"><span>state_db</span><span>.</span><span>set_code</span><span>(</span><span>caller</span><span>,</span><span class="z-support"> bytes</span><span>.</span><span>fromhex</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">60006000f3</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span></span> <span class="giallo-l"><span>error</span><span>,</span><span> gas_left</span><span class="z-keyword"> =</span><span> precompile</span><span>.</span><span>execute</span><span>(</span><span>caller</span><span>,</span><span> state_db</span><span>,</span><span class="z-variable"> gas</span><span class="z-keyword">=</span><span class="z-constant">15000</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> error</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">the address is not an EOA delegated to code</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> gas_left</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> PrecompiledContract</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> DELEGATED_CODE_PREFIX</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span>.</span><span>fromhex</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ef0100</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"><span class="z-constant"> PRECOMPILE_GAS_COST</span><span class="z-keyword"> =</span><span class="z-constant"> 13000</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> execute</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> caller</span><span>,</span><span class="z-variable z-parameter z-function"> state_db</span><span>,</span><span class="z-variable z-parameter z-function"> gas</span><span>,</span><span class="z-variable z-parameter z-function"> read_only</span><span class="z-keyword">=</span><span class="z-constant">False</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Switch the private key state of delegated EOAs between active and deactivated.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> Parameters:</span></span> <span class="giallo-l"><span class="z-string"> - caller: The address calling the contract</span></span> <span class="giallo-l"><span class="z-string"> - state_db: The state database</span></span> <span class="giallo-l"><span class="z-string"> - gas: Gas provided for execution</span></span> <span class="giallo-l"><span class="z-string"> - read_only: Whether called in a read-only context</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-string"> Returns:</span></span> <span class="giallo-l"><span class="z-string"> - Tuple of (result, gas_left)</span></span> <span class="giallo-l"><span class="z-string"> result: error bytes on failure, empty bytes on success</span></span> <span class="giallo-l"><span class="z-string"> gas_left: remaining gas, 0 on error</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check gas</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> gas</span><span class="z-keyword"> &lt;</span><span class="z-variable z-language"> self</span><span>.</span><span class="z-constant">PRECOMPILE_GAS_COST</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">insufficient gas</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check STATICCALL</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> read_only</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">STATICCALL disallows state modification</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Get and validate caller&#39;s code</span></span> <span class="giallo-l"><span> code</span><span class="z-keyword"> =</span><span> state_db</span><span>.</span><span>get_code</span><span>(</span><span>caller</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> code</span><span>.</span><span>startswith</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span class="z-constant">DELEGATED_CODE_PREFIX</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">the address is not an EOA delegated to code</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Update delegated code based on length</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 23</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Active state</span></span> <span class="giallo-l"><span> state_db</span><span>.</span><span>set_code</span><span>(</span><span>caller</span><span>,</span><span> code</span><span class="z-keyword"> +</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant">\x00</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Deactivate</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 24</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Deactivated state</span></span> <span class="giallo-l"><span> state_db</span><span>.</span><span>set_code</span><span>(</span><span>caller</span><span>,</span><span> code</span><span>[</span><span>:</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Activate</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Although this is not possible, it&#39;s added for completeness</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">invalid delegated code length</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> gas</span><span class="z-keyword"> -</span><span class="z-variable z-language"> self</span><span>.</span><span class="z-constant">PRECOMPILE_GAS_COST</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> StateDB</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span><span class="z-string">Simplified state database, omitting other account fields</span><span class="z-punctuation z-definition z-string">&quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-support"> __init__</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>accounts</span><span class="z-keyword"> =</span><span> {</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> get_code</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> addr</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> self</span><span>.</span><span>accounts</span><span>.</span><span>get</span><span>(</span><span>addr</span><span>,</span><span> {</span><span>}</span><span>)</span><span>.</span><span>get</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">code</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> set_code</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> addr</span><span>,</span><span class="z-variable z-parameter z-function"> value</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> addr</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span class="z-variable z-language"> self</span><span>.</span><span>accounts</span><span>:</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>accounts</span><span>[</span><span>addr</span><span>]</span><span class="z-keyword"> =</span><span> {</span><span>}</span></span> <span class="giallo-l"><span class="z-variable z-language"> self</span><span>.</span><span>accounts</span><span>[</span><span>addr</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">code</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span class="z-keyword"> =</span><span> value</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="contracts-using-ecdsa-secp256k1-signatures">Contracts Using ECDSA <code>Secp256k1</code> Signatures</h3> <p>Contracts that have already been deployed and use ECDSA <code>secp256k1</code> signatures outside of transaction signatures (e.g., <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens that support <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>, the <code>permit</code> function) will not be able to verify the deactivated status of the EOA. This means that signatures signed by private keys will remain valid in these functions.</p> <p>To handle deactivated EOAs, new or upgradeable contracts can check the signing address's deactivation status, for example:</p> <ul> <li>Use <code>EXTCODESIZE</code> to get the account's code length.</li> <li>If the code length is <code>24</code> bytes, use <code>EXTCODECOPY</code> to verify the code starts with <code>0xef0100</code> (delegated code prefix).</li> <li>If both conditions are satisfied (i.e., the code size is <code>24</code> bytes and the code starts with <code>0xef0100</code>), the private key is confirmed to be deactivated, and the signature should be rejected.</li> </ul> <p>For non-upgradeable contracts, the above method cannot be applied directly. Another potential solution, at the protocol level, is to modify <code>ecRecover</code> precompiled contract: if the private key of the recovered address is deactivated, the <code>ecRecover</code> precompiled contract could return a precompile contract error (or, if not adding an error return path, return a zero address or a collision-resistant address, such as <code>0x1</code>). However, this approach also has limitations, as it cannot cover cases where contracts implement their own signature verification logic without relying on <code>ecRecover</code>.</p> <h3 id="irreversible-deactivation">Irreversible Deactivation</h3> <p>Delegating to a wallet that lacks reactivation support (e.g., by calling the precompiled contract through an appropriate interface) may result in irreversible deactivation. To mitigate this risk, users should delegate their EOAs only to thoroughly audited implementations that explicitly support this EIP.</p> <h3 id="deactivation-and-reactivation-replay">Deactivation and Reactivation Replay</h3> <p>Replay attacks can occur in two scenarios: (i) repeating the same authorization on a single chain, or (ii) using the authorization across different chains.</p> <p>For deactivation through EOA-signed transactions, the use of nonces in transactions ensures the same message cannot be replayed multiple times on the same chain. Additionally, the replay protection mechanism provided by <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>, if enabled, effectively prevents cross-chain message replay.</p> <p>For deactivation or reactivation via delegated contracts, the contract should implement robust replay protection mechanism(s) (e.g., adding a customized nonce and the chain ID to the signed message) to safeguard against replay attacks both within the same chain and across different chains. Especially when the EOA has been (or will be) delegated to the same implementation on multiple chains.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-12-06T00:00:00+00:00 2026-02-11T14:49:28+00:00 Keyvan Kambakhshhttps://github.com/keyvank Nobitex Labslabs@nobitex.ir https://wg-eips.ritovision.com/7833/

Giving life to smart contracts by enabling their functions to be automatically invoked by block producers.

<h2 id="abstract">Abstract</h2> <p>Ethereum's smart contracts enable users to delegate control of their funds to code, but these contracts require an external trigger to execute. Timing is often critical, and issues such as network delays or malicious behavior by block producers—like MEV attacks—can prevent timely execution. To address these challenges, this Ethereum Improvement Proposal (EIP) introduces a new opcode, OFFERCALL, which allows contracts to schedule function calls. When functions self-schedule, they exhibit bot-like behavior. These scheduled calls would offer ETH to block producers as an incentive to prioritize their execution over manually submitted transactions. If the offer is not fulfilled, the bot is deactivated until manually re-ignited by the owner. The EIP proposes enforcing the execution of scheduled calls as a requirement for block validity. This could help mitigate MEV attacks, as block producers would be compelled to execute bots that neutralize market manipulation within the blockchain.</p> <h2 id="specification">Specification</h2> <p>Adding bot-like behavior to an EVM function is achieved by recursively scheduling a call to the same function in the next block. We propose introducing a new EVM opcode, OFFERCALL, which, as the name implies, offers ETH to be burnt to the block producer of the next block in exchange for invoking a function. These offers are aggregated and ranked by the Ethereum node, with only the top N offers being retained; all others are discarded. Scheduled calls must be executed before any user transactions, with execution order determined by their rank in the sorted list. The offered ETH is burnt to prevent block producers from exploiting the system by scheduling calls that pay the offered amounts back to themselves.</p> <p>Here is a solidity example of how the usage of OFFERCALL would look like:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Bot</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> offerPerCall</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _offer</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> offerPerCall </span><span class="z-keyword">=</span><span> _offer</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Ignite the bot with an initial invocation offer</span></span> <span class="giallo-l"><span class="z-entity z-name"> offercall</span><span>(</span><span>update</span><span>,</span><span> offerPerCall</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setOffer</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _offer</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> offerPerCall </span><span class="z-keyword">=</span><span> _offer</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> update</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Do scheduled work</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The callee may reschedule itself in order to</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> introduce a bot-like behavior.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The callee has to be careful about its offer</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> otherwise it may die.</span></span> <span class="giallo-l"><span class="z-entity z-name"> offercall</span><span>(</span><span>update</span><span>,</span><span> offerPerCall</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Once an offercall fails, the contract owner</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> may have to set a new offer by calling `setOffer`</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> and then invoking the `update()` function again.</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>An OFFERCALL fails in two situations:</p> <ul> <li>The contract does not hold at least the offered amount of ETH.</li> <li>The offered amount is not large enough to rank within the top N offers.</li> </ul> <p>In the case of a self-scheduling function, once an OFFERCALL fails, the bot is deactivated. The only way to revive it is for the contract owner to manually call the function again, likely with a higher offer.</p> <h2 id="rationale">Rationale</h2> <p>The rationale behind this Ethereum Improvement Proposal (EIP) stems from the need to enhance the reliability and fairness of smart contract execution on the Ethereum network. While Ethereum’s smart contracts allow for a high degree of programmability and automation, the execution of these contracts often depends on external triggers, such as user transactions or network conditions. This dependency introduces significant challenges, particularly in situations where timing is critical or when malicious actors, like block producers, can exploit the system for profit.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The introduction of the new OFFERCALL opcode in this EIP requires a network upgrade, as it adds new functionality that is not currently supported by the Ethereum Virtual Machine (EVM). This change will affect how smart contracts can schedule and incentivize the execution of specific function calls, introducing a new mechanism that block producers must accommodate.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>N/A</p> <h2 id="security-considerations">Security Considerations</h2> <p>The main concern with this EIP is whether it could lead to centralization, as wealthier users might dominate execution priorities. Burning unfulfilled offers partly addresses this by preventing endless offers.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-11-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/7830/

Raise the limit for only EOF contracts to 64 KiB

<h2 id="abstract">Abstract</h2> <p>Revise the contract size limit for EOF contracts to be 64 KiB instead of the existing 24 KiB limit. Legacy contracts are unaffected.</p> <h2 id="motivation">Motivation</h2> <p>The contract size limit was introduced as a measure against DoS attacks. <code>JUMPDEST</code>-analysis is required for legacy contracts, and many of the algorithms performing it are not linear and/or have unknown unknowns. This is one of the reasons for the hesitance of a limit increase.</p> <p>For contract developers the limit poses annoying problems, given modern contracts with good error reporting would consume more space. They are forced to work with workarounds, like "libraries" (using <code>DELEGATECALL</code>), splitting an application across regular contracts (and <code>CALL</code>-ing across), or working with proxies (e.g. the "diamond pattern"). All these solutions have resulted in suboptimal patterns, bugs in deployed contracts, and loss of funds.</p> <p>With EOF the <code>JUMPDEST</code>-analysis is removed from runtime and a validation process is performed once during deployment. The initcode cost <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a> introduced accounts for this validation too. Therefore, with EOF there are no known problems for increasing the limit, because the overheads are already accounted for.</p> <p>Storage cost is already paid per contract byte.</p> <h2 id="specification">Specification</h2> <p><a href="https://wg-eips.ritovision.com/170/">EIP-170</a> specifies <code>MAX_CODE_SIZE</code> as 24576 bytes, and <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a> specifies <code>MAX_INITCODE_SIZE</code> as <code>2 * MAX_CODE_SIZE</code> (49152 bytes).</p> <p>Starting <code>FORK_BLOCK</code>, for EOF initcode/code (code starting with the <code>0xEF 0x00</code> bytes) the limit is changed:<code>MAX_CODE_SIZE</code> is set to 65536 bytes (64 KiB). This means <code>MAX_INITCODE_SIZE</code> becomes 131072 bytes (128 KiB).</p> <h2 id="rationale">Rationale</h2> <p>The 64 KiB limit is over 2x of existing limit, while it is not a significant increase, it is the realistic increase given the limitations of initcode. In EOF deployment the to-be-deployed code is stored as a section ("subcontainer"), which has a size limit of 64 KiB, therefore it is not possible to deploy larger contracts without introducing a large or variable-length-encoded size field.</p> <p>A further increase can be proposed with applying these changes to EOF.</p> <p>This increase still fits within the gas schedule, limiting the size to less than what gas limits allow. In <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> the gas limit was first set "by setting the cap at a value slightly higher than what is feasible with current gas limits." At that time the gas limit had not exceeded 5M gas.</p> <p>A simple analysis shows contract deployments for 64 KiB contracts to be between 14M and 16M gas, roughly close to the current 15M target.</p> <table><thead><tr><th></th><th style="text-align: right">Cancun</th><th style="text-align: right">This EIP</th><th style="text-align: right">36M Gas</th><th style="text-align: right">Max Initcode</th></tr></thead><tbody> <tr><td><strong>Initcode bytes</strong></td><td style="text-align: right">200</td><td style="text-align: right">200</td><td style="text-align: right">200</td><td style="text-align: right">65,536</td></tr> <tr><td><strong>Deployed Bytes</strong></td><td style="text-align: right">24,576</td><td style="text-align: right">65,536</td><td style="text-align: right">165,331</td><td style="text-align: right">65,536</td></tr> <tr><td><strong>Zero byte ratio</strong></td><td style="text-align: right">10%</td><td style="text-align: right">10%</td><td style="text-align: right">10%</td><td style="text-align: right">10%</td></tr> <tr><td><strong>Initcode Cost</strong></td><td style="text-align: right">4/16</td><td style="text-align: right">4/16</td><td style="text-align: right">4/16</td><td style="text-align: right">4/16</td></tr> <tr><td></td><td style="text-align: right"></td><td style="text-align: right"></td><td style="text-align: right"></td><td style="text-align: right"></td></tr> <tr><td><strong>Intrinsic Gas</strong></td><td style="text-align: right">53,000</td><td style="text-align: right">53,000</td><td style="text-align: right">53,000</td><td style="text-align: right">53,000</td></tr> <tr><td><strong>Calldata Gas</strong></td><td style="text-align: right">366,685</td><td style="text-align: right">972,893</td><td style="text-align: right">2,449,859</td><td style="text-align: right">1,939,866</td></tr> <tr><td><strong>EIP-3860 Gas</strong></td><td style="text-align: right">49,552</td><td style="text-align: right">131,472</td><td style="text-align: right">331,062</td><td style="text-align: right">262,144</td></tr> <tr><td><strong>EVM Execution</strong></td><td style="text-align: right">100,000</td><td style="text-align: right">100,000</td><td style="text-align: right">100,000</td><td style="text-align: right">100,000</td></tr> <tr><td><strong>Code Deposit</strong></td><td style="text-align: right">4,915,200</td><td style="text-align: right">13,107,200</td><td style="text-align: right">33,066,200</td><td style="text-align: right">13,107,200</td></tr> <tr><td></td><td style="text-align: right"></td><td style="text-align: right"></td><td style="text-align: right"></td><td style="text-align: right"></td></tr> <tr><td><strong>Total Cost</strong></td><td style="text-align: right">5,484,437</td><td style="text-align: right">14,364,565</td><td style="text-align: right">36,000,121</td><td style="text-align: right">15,462,210</td></tr> </tbody></table> <p>Note that the Max 30M gas contract size of 135 KiB is outside the limits of what is proposed in this EIP and is included to show what it would take to exceed current gas limits.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards compatible change. Existing contracts are unaffected, and only new deployments see the effect.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Given the analysis cost is paid as part of deployment, the size of contract should have no effect on the runtime.</p> <p>A more thorough analysis may be needed to determine whether the proposed limit poses any risk because of client storage architectures.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-11-04T00:00:00+00:00 2026-02-11T14:49:28+00:00 Carl Beekhuizenhttps://github.com/carlbeek Yoav Weisshttps://github.com/yoavw Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/7808/

Reserve transaction type range for use by the RIP process

<h2 id="abstract">Abstract</h2> <p>This EIP reserves a <a href="https://wg-eips.ritovision.com/2718/">transaction-type</a> range for use by the Rollup Improvement Proposal (RIP) process to ensure there are no conflicts.</p> <h2 id="motivation">Motivation</h2> <p>For L2s to use new transactrion types, it is necessary to reserve a transaction-type range for use by the RIP process so as to ensure there are no conflicts between transaction types used by RIPs and EIPs.</p> <h2 id="specification">Specification</h2> <p>The transaction-type (as specified in <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a>) range from <code>0x40</code> to <code>0x7f</code> (inclusive of both) is reserved for use by the RIP process.</p> <h2 id="rationale">Rationale</h2> <p>By reserving a transaction-type range for RIPs, it allows the RIP process to maintain its own registry of transaction types that are not (necessarily) in use on L1 mainnet, the EIP process is then freed from having to maintain a registry of RIP tx-types while still having 64 tx-types for its own use.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Nil.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-10-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status https://wg-eips.ritovision.com/7797/

Double the performance of hash_tree_root by customizing SHA-256

<h2 id="abstract">Abstract</h2> <p>This EIP explains how to customize <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/ssz/simple-serialize.md#merkleization"><code>hash_tree_root</code></a> to double its performance.</p> <h2 id="motivation">Motivation</h2> <p>Hashing is a dominant performance bottleneck for Consensus Layer implementations. To support large validator counts, it is critical to optimize hashing performance.</p> <p>Consensus Layer hashes are based on <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/ssz/simple-serialize.md#merkleization"><code>hash_tree_root</code></a>, a mechanism that splits up the data into chunks and then forms a tree by recursively combining two adjacent chunks and hashing them into a single parent chunk until only a single root chunk remains.</p> <p>For hashing, Secure Hash Algorithm 2 with a digest size of 256 bits is used (SHA-256). This algorithm produces <em>exactly</em> 256 bits of output for a variable-length input message. However, as <code>hash_tree_root</code> pads all input chunks to exactly 256 bits, the effective input message length is always <em>exactly</em> 512 bits.</p> <p>This EIP defines how the SHA-256 algorithm used by <code>hash_tree_root</code> can be customized to exploit knowledge of the exact input length to double its performance, while retaining its security properties.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="sha-256-preprocessing">SHA-256 preprocessing</h3> <p>Before SHA-256 hash computation begins, the input message is preprocessed. A single <code>1</code> bit is appended to the input message, followed by a varying number of <code>0</code> bits, and finally a big endian <code>uint64</code> indicating the input message bit length. The number of <code>0</code> bits is chosen so that the message size is the smallest possible multiple of 512 bits. In the context of <code>hash_tree_root</code> where the input message size is 512 bits, preprocessing results in the following padded message:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> 0 1 2 3 4 5 6 7 8 9 A B C D E F</span></span> <span class="giallo-l"><span> +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+</span></span> <span class="giallo-l"><span> 0x00 | |</span></span> <span class="giallo-l"><span> 0x10 | Input |</span></span> <span class="giallo-l"><span> 0x20 | message |</span></span> <span class="giallo-l"><span> 0x30 | |</span></span> <span class="giallo-l"><span> +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+</span></span> <span class="giallo-l"><span> 0x40 |80|00 00 00 00 00 00 00 00 00 00 00 00 00 00 00|</span></span> <span class="giallo-l"><span> 0x50 |00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00|</span></span> <span class="giallo-l"><span> 0x60 |00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00|</span></span> <span class="giallo-l"><span> 0x70 |00 00 00 00 00 00 00 00|00 00 00 00 00 00 02 00|</span></span> <span class="giallo-l"><span> +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+</span></span></code></pre><h3 id="sha-256-blocks">SHA-256 blocks</h3> <p>SHA-256 operates on message blocks of 512 bits. Therefore, in the context of <code>hash_tree_root</code> where the input message size is 512 bits, two message blocks are formed, the first containing the entire input message, and the second containing entirely static data resulting from the preprocessing step.</p> <p>Note that the second 512 bit message block does not provide any entropy, and is only useful to distinguish input messages that share a common prefix and only vary in the number of trailing <code>0</code> bits. As <code>hash_tree_root</code> uses a fixed message size, no distinguishing is necessary. Further, SHA-256 is also considered secure for padded messages that fit into a single message block.</p> <h3 id="sha-256-512">SHA-256-512</h3> <p>A new algorithm SHA-256-512 is defined as a modified SHA-256 algorithm that skips input message preprocessing and is restricted to inputs of exactly 512 bits. The input message SHALL be processed as is, as a single 512-bit SHA-256 message block.</p> <p>For every <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/ssz/simple-serialize.md#composite-types">composite SSZ type</a> in use, implementations SHALL support a new type that shares the same functionality, but hashes using SHA-256-512 instead of regular SHA-256.</p> <h3 id="consensus-types">Consensus types</h3> <p>Starting with the hard fork that introduces this EIP, the SHA-256-512 based composite SSZ types SHOULD be preferred over existing SHA-256 based types.</p> <p>Certain use cases covering historical objects MAY require conversion to the historical data type and re-hashing with the original SHA-256 type to recover their historical root. This includes <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/phase0/beacon-chain.md#compute_signing_root"><code>compute_signing_root</code></a> signing over historical data, and also individual fields such as <code>BeaconState.latest_block_header</code> which MAY refer to data from prior forks.</p> <p>Certain other objects such as <code>DepositData</code> or <code>VoluntaryExit</code> MAY continue to rely on existing SHA-256 logic.</p> <h2 id="rationale">Rationale</h2> <p>Doubling the throughput of the underlying hash algorithm allows scaling to more validators on the same hardware, or allows using the freed CPU time for other tasks. Even when caching rarely-changed intermediate hashes across computations such as the <code>validators</code> list of a <code>BeaconState</code>, and employing hardware-accelerated SHA-256 implementations that are further optimized for the tree structure using libraries such as <code>prysmaticlabs/hashtree</code>, the state root validation step of the Consensus Layer state transition function can still consume ~25% of CPU time (Holesky test network, ~1.7m validators), mostly dominated by frequently changing per-validator structures such as the <code>EpochParticipationFlags</code> lists.</p> <p>If the hash algorithm is changed to a more zero-knowledge friendly one in the future, similar efforts as described in this EIP would be needed to identify the locations where historical objects need to be hashed using historical hashes, and also to introduce new composite SSZ types. A switch from SHA-256 to SHA-256-512 would pull such work ahead, and any future hash algorithm changes would solely have to extend on these known locations. The total work necessary to switch hash algorithms multiple times is comparable to switching a single time.</p> <p>Existing hardware acceleration for SHA-256 continues to be viable, as only the message preprocessing step is dropped. Hardware acceleration typically only implements the SHA-256 message block function, which is unchanged by this EIP.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Smart contracts and client applications that verify Consensus Layer data require updates to remain compatible with data hashed using SHA-256-512. New logic may be required to correctly select the hash algorithm for historical structures such as <code>BeaconBlockHeader</code>.</p> <p>SSZ serialization, generalized indices, as well as semantics of individual object fields remain unchanged.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Certain SHA-256-512 hashes of 512 bit data may collide with regular SHA-256 hashes of shorter data. For example:</p> <ul> <li>Any common 440-bit prefix: <code>COMMON_PREFIX := 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f202122232425262728292a2b2c2d2e2f30313233343536</code></li> <li><code>SHA-256-512(COMMON_PREFIX ++ 0x80 ++ 0x00000000000001b8) == 463eb28e72f82e0a96c0a4cc53690c571281131f672aa229e0d45ae59b598b59</code></li> <li><code>SHA-256(COMMON_PREFIX) == 463eb28e72f82e0a96c0a4cc53690c571281131f672aa229e0d45ae59b598b59</code></li> </ul> <p>Because SSZ has never hashed data with sizes different from 512 bits, SSZ hashes based on SHA-256 do not collide with hashes based on SHA-256-512.</p> <p>SHA-256-512 SHOULD NOT be used for purposes other than SSZ Merkleization.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-10-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Giulio Rebuffohttps://github.com/Giulio2002 Ben Adamshttps://github.com/benaadams https://wg-eips.ritovision.com/7790/

Suggests specific parameters for the controlled gas limit increase strategy introduced.

<p>This proposal specifies specific parameters for the controlled gas limit increase strategy outlined in <a href="https://wg-eips.ritovision.com/7783/">EIP-7783</a>, including block number to start the increase, initial gas limit, rate of increase per block, and gas limit cap.</p> <h2 id="abstract"><strong>Abstract</strong></h2> <p>This proposal provides parameter recommendations for implementing the controlled gas limit increase strategy in <a href="https://wg-eips.ritovision.com/7783/">EIP-7783</a>.</p> <h2 id="motivation"><strong>Motivation</strong></h2> <p>The motivation for this proposal is to define practical and balanced parameters for Ethereum's gas limit increase strategy to achieve predictable and stable network scaling. While <a href="https://wg-eips.ritovision.com/7783/">EIP-7783</a> defines the mechanism, there is still a need to establish the values needed for its implementation based on real-world conditions.</p> <h2 id="specification"><strong>Specification</strong></h2> <h3 id="proposed-parameters"><strong>Proposed Parameters</strong></h3> <p>The parameters for the controlled gas limit increase strategy are:</p> <ul> <li> <p><strong>Block Number Start (<code>blockNumStart</code>)</strong>: <code>21792420</code><br /> The block number at which the gas limit increase begins. this is february 7, 2024.</p> </li> <li> <p><strong>Initial Gas Limit (<code>initialGasLimit</code>)</strong>: <code>30_000_000</code><br /> The initial gas limit at <code>blockNumStart</code> represents the current default gas limit of the Ethereum network, set to 30 million gas.</p> </li> <li> <p><strong>Rate of Increase (<code>r</code>)</strong>: <code>6</code><br /> The gas limit will increase by 6 gas per block. This results in a slow growth rate culminating to reaching the cap in approximately 694 days.</p> </li> <li> <p><strong>Gas Limit Cap (<code>gasLimitCap</code>)</strong>: <code>60_000_000</code><br /> The maximum gas limit is capped at 60 million gas, ensuring that the gas limit will not increase indefinitely and will prevent the network from being overwhelmed by excessively large blocks.</p> </li> </ul> <h2 id="rationale"><strong>Rationale</strong></h2> <h3 id="starting-block-number"><strong>Starting Block Number</strong></h3> <p>The chosen block number (<code>21792420</code>) provides ample time to discuss and implement the gas limit increase strategy, additionally, it allows to happen with or slightly before the pectra hard fork.</p> <h3 id="initial-gas-limit"><strong>Initial Gas Limit</strong></h3> <p>The initial gas limit is set to match the current default gas limit of <code>30_000_000</code>.</p> <h3 id="rate-of-increase"><strong>Rate of Increase</strong></h3> <p>A rate of <code>6</code> gas per block is chosen to triple the gas limit in approximately 47 months, which is equivalent to almost 2 years.</p> <h3 id="gas-limit-cap"><strong>Gas Limit Cap</strong></h3> <ul> <li>The gas limit cap of <code>60_000_000</code> provides a safeguard against the gas limit growing beyond what the network can safely handle.</li> </ul> <h2 id="backwards-compatibility"><strong>Backwards Compatibility</strong></h2> <p>These parameters do not require any protocol changes or hard forks. They are fully backward compatible with the current Ethereum network architecture.</p> <h2 id="security-considerations"><strong>Security Considerations</strong></h2> <ul> <li>The gradual nature of the gas limit increase prevents sudden surges in block size that could destabilize the network.</li> <li>The cap on the gas limit ensures that blocks do not become excessively large, which could lead to performance degradation or DOS vulnerabilities.</li> <li>Validators retain the ability to make adjustments to the gas limit in response to potential network attacks or performance issues.</li> </ul> <h2 id="copyright"><strong>Copyright</strong></h2> <p>Copyright and related rights waived via CC0 1.0 Universal.</p> 2024-10-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Marc Harvey-Hillhttps://github.com/Marchhill Ahmad Bitarhttps://github.com/smartprogrammer93 https://wg-eips.ritovision.com/7793/

Transactions that only executes at a specific index and slot

<h2 id="abstract">Abstract</h2> <p>This EIP proposes to add a new transaction format for "conditional transactions", that are only valid at a specified slot and index within the block. A new opcode <code>TXINDEX</code> is introduced to expose the conditional transaction index onchain.</p> <h2 id="motivation">Motivation</h2> <p>The proposal aims to improve support for encrypted mempools. Transactions in an encrypted mempool are ordered while the transactions are encrypted, before being decrypted and included onchain at the top of the block. If the builder does not respect the order when including the decrypted transactions then they could frontrun decrypted transactions. The new transaction type can be used to make this impossible; if a decrypted transaction is not included at the correct index, it will be invalid.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>COND_TX_TYPE</code></td><td><code>Bytes1(0x05)</code></td></tr> <tr><td><code>TXINDEX_OPCODE_BYTE</code></td><td><code>Bytes1(0x4c)</code></td></tr> <tr><td><code>TXINDEX_OPCODE_GAS</code></td><td><code>2</code></td></tr> </tbody></table> <h3 id="conditional-transaction-type">Conditional Transaction Type</h3> <p>We introduce a new type of <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction, "conditional transactions", where the <code>TransactionType</code> is <code>COND_TX_TYPE</code> and the <code>TransactionPayload</code> is the RLP serialization of the following <code>TransactionPayloadBody</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, value, data, access_list, max_fee_per_blob_gas, blob_versioned_hashes, conditional_slot, conditional_tx_index, y_parity, r, s]</span></span></code></pre> <p>The fields <code>chain_id</code>, <code>nonce</code>, <code>max_priority_fee_per_gas</code>, <code>max_fee_per_gas</code>, <code>gas_limit</code>, <code>to</code>, <code>value</code>, <code>data</code>, <code>access_list</code>, <code>max_fee_per_blob_gas</code> follow the same semantics as <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>. The field <code>blob_versioned_hashes</code> is the same except that the list may be empty for a conditional transaction.</p> <p>The fields <code>conditional_slot</code> and <code>conditional_tx_index</code> are both <code>uint64</code> and specify the slot and transaction index in which this transaction should be considered valid respectively. In order to verify that <code>conditional_slot</code> is correct, <a href="https://wg-eips.ritovision.com/7843/">EIP-7843</a> is a dependency, as this adds the slot number to the header. For both fields <code>-1</code> is used as a sentinel value for which the slot or transaction index check will not take place.</p> <h4 id="signature">Signature</h4> <p>The signature values <code>y_parity</code>, <code>r</code>, and <code>s</code> are calculated by constructing a secp256k1 signature over the following digest:</p> <p><code>keccak256(COND_TX_TYPE || rlp([chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, value, data, access_list, max_fee_per_blob_gas, blob_versioned_hashes, conditional_slot, conditional_tx_index]))</code>.</p> <h3 id="txindex-opcode">TXINDEX opcode</h3> <p>A new opcode <code>TXINDEX</code> is introduced at <code>TXINDEX_OPCODE_BYTE</code>.</p> <h4 id="output">Output</h4> <p>One element <code>TransactionIndex</code> is added to the stack. <code>TransactionIndex</code> is a <code>uint64</code> in big endian encoding. It is equal to <code>conditional_tx_index</code> if the current transaction is a conditional transaction, and <code>-1</code> otherwise.</p> <h4 id="gas-cost">Gas Cost</h4> <p>The gas cost for <code>TXINDEX</code> is a fixed fee of <code>TXINDEX_OPCODE_GAS</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="transaction-type">Transaction Type</h3> <p>An alternative design could simply return the current transaction index without adding a new transaction type. Adding a new transaction type is favoured as it means that the expected transaction index must be declared statically upfront, rather than allowing dynamic behaviour based on the returned transaction index. This prevents complex constraints being imposed that makes it difficult to build a block.</p> <h3 id="gas-price">Gas Price</h3> <p>The opcode is priced to match similar opcodes in the <code>W_base</code> set.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>N/A</p> <h2 id="security-considerations">Security Considerations</h2> <p>None.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-10-07T00:00:00+00:00 2026-02-11T14:49:28+00:00 Tim Pecherskyhttps://github.com/peersky https://wg-eips.ritovision.com/7784/

Global byte code accessing by its hash

<h2 id="abstract">Abstract</h2> <p>This is a proposal to add a new opcode, <code>GETCONTRACT</code>. The <code>GETCONTRACT</code> opcode would return the address containing the bytecode by its hash.</p> <h2 id="motivation">Motivation</h2> <p>Content addressing by hash is a common pattern in database design. It allows to store and retrieve data by its unique footprint in the storage. This pattern is widely used in the industry and it allows abstracting the actual storage location and allows reusing the same bytecode in multiple contracts.</p> <p>Today, 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> <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> <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> <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> <p>For decentralized application (dApp) developers, a code index can save gas costs by allowing them to reference existing codebase 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> <p>This also allows to build new core standards more conveniently, for example, <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> can use it as dependency, to allow users who want to set up one-time code on their EOAs by referring to <code>GETCONTRACT</code> instead of specifying potentially mutable address based functionality.</p> <h2 id="specification">Specification</h2> <h3 id="opcode-definition">Opcode Definition</h3> <ul> <li><strong>Mnemonic:</strong> <code>GETCONTRACT</code></li> <li><strong>Opcode Value:</strong> <code>0x4f</code></li> <li><strong>Input:</strong> <ul> <li><code>codehash</code>: A single 32-byte code hash from the stack.</li> </ul> </li> <li><strong>Output:</strong> <ul> <li><code>address</code>: If the <code>codehash</code> exists in the state, pushes the corresponding contract address onto the stack. Otherwise, pushes 0.</li> </ul> </li> <li><strong>Gas Cost:</strong> 150</li> <li><strong>Stack Effects:</strong> Pops 1 item, pushes 1 item.</li> <li><strong>Error Handling:</strong> If the <code>codehash</code> is invalid or the bytecode retrieval encounters an error, the instruction will revert.</li> </ul> <p>Every contract stored in EVM MUST be added to the state trie with the key being the keccak256 hash of the contract's bytecode, provided it is:</p> <ul> <li>not already present</li> <li>The contract did not invoke the <code>SELFDESTRUCT</code> opcode.</li> <li>The <code>EXTCODEHASH</code> return value IS NOT <code>0xeadcdba66a79ab5dce91622d1d75c8cff5cff0b96944c3bf1072cd08ce018329</code> (<code>keccak256(0xef01)</code>)</li> </ul> <h3 id="example-usage">Example Usage</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getContractAddress</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> codehash</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> contractAddress </span><span class="z-keyword">:=</span><span class="z-entity z-name"> GETCONTRACT</span><span>(</span><span>codehash</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> contractAddress</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p><strong>Bytecode over Addresses</strong>: Bytecode is deterministic and can be verified on-chain, while addresses are opaque and mutable.</p> <p><strong>Do not re-index</strong>: There is small, yet non-zero probability of hash collision attack. Disallowing updates to indexed location of bytecode coupes with this.</p> <p><strong>Gas cost</strong>: This operation is more complex than simple data retrieval, however lookup in the database by hash generally is simpler in complexity.</p> <h2 id="security-considerations">Security Considerations</h2> <p><strong>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> <p><strong>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> <p><strong><a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegation:</strong> Temporary code delegation is disallowed to prevent case of registering a code hash that becomes unavailable. Standard explicitly disallows contracts with bytecode delegated via <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> from being indexed.</p> <p><strong>SELFDESTRUCT</strong>: Contracts that <code>selfdestruct</code> are not indexed, as they will not have a codehash in the state trie.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-10-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Giulio Rebuffohttps://github.com/Giulio2002 https://wg-eips.ritovision.com/7783/

Adds a controlled gas limit increase strategy.

<p>This proposal describes the introduction in clients of a controlled gas limit increase strategy to determine the gas limit of a specific block and set as default with conservative parameters, while keeping the possibility to change it in the future to a fixed value.</p> <h2 id="abstract"><strong>Abstract</strong></h2> <p>The EIP proposes the introduction of a new gas limit management mechanism that automatically increases the block gas limit over time. The incremental growth is controlled by a fixed rate, ensuring predictable network scaling while preventing sudden surges in block sizes. This strategy is meant to be used as a default setting, with the option to switch to a fixed gas limit if needed (or different parameters).</p> <h2 id="motivation"><strong>Motivation</strong></h2> <h3 id="predictable-gas-limit-growth"><strong>Predictable Gas Limit Growth</strong></h3> <ul> <li> <p><strong>Current Issue:</strong></p> <ul> <li>The Ethereum network faces increasing demand, but changes to the gas limit are often manually adjusted by miners or validators based on their preferences, which may cause unpredictable block sizes and network performance issues.</li> </ul> </li> <li> <p><strong>Need for Change:</strong></p> <ul> <li>A systematic and predictable increase of the gas limit will help scale the network while giving the ecosystem time to adjust to larger block sizes, without needing to rely on ad hoc decisions by network participants.</li> </ul> </li> </ul> <h3 id="gradual-increase-with-deactivation-safeguard"><strong>Gradual Increase with Deactivation Safeguard</strong></h3> <ul> <li> <p><strong>Controlled Growth:</strong></p> <ul> <li>Instead of sudden or unpredictable changes, this EIP proposes incremental gas limit increases over a specified amount of time, ensuring a smooth transition to higher transaction throughput, while still keeping the governance of the gas limit in the hand of the community.</li> </ul> </li> <li> <p><strong>Automatic Deactivation:</strong></p> <ul> <li>A safeguard deactivation block will halt the increase after some specified time, preventing the gas Limit from growing indefinitely and allowing the community to reassess the network's needs.</li> </ul> </li> </ul> <h2 id="specification"><strong>Specification</strong></h2> <p>There are different approaches to implement a controlled gas limit increase strategy. The following are three possible strategies that can be used:</p> <h3 id="linear-gas-limit-increase-strategy"><strong>Linear Gas Limit Increase Strategy</strong></h3> <p>Add a new "Gas Limit" selection strategy that takes in Block Number <code>N</code> and spits out the Gas Limit <code>GL</code> for that block. The strategy is as follows:</p> <ul> <li>The gas limit <code>GL_t</code> at block <code>t</code> is calculated as:</li> </ul> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> compute_gas_limit</span><span>(</span><span class="z-variable z-parameter z-function">blockNum</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> blockNumStart</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> initialGasLimit</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> r</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> gasLimitCap</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> blockNum</span><span class="z-keyword"> &lt;</span><span> blockNumStart</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> initialGasLimit</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> min</span><span>(</span><span>gasLimitCap</span><span>,</span><span> initialGasLimit</span><span class="z-keyword"> +</span><span> r</span><span class="z-keyword"> *</span><span> (</span><span>blockNum</span><span class="z-keyword"> -</span><span> blockNumStart</span><span>)</span><span>)</span></span></code></pre> <p>Where:</p> <ul> <li><code>blockNum</code> is the block number for which the gas limit is being calculated.</li> <li><code>blockNumStart</code> is the block number at which the gas limit increase starts.</li> <li><code>initialGasLimit</code> is the initial gas limit at block <code>blockNumStart</code>.</li> <li><code>r</code> is the rate at which the gas limit increases per block.</li> <li><code>gasLimitCap</code> is the maximum gas limit that can be reached.</li> </ul> <p>If we set <code>blockNumStart</code> to the current block number, <code>initialGasLimit</code> to the current gas limit (<code>30_000_000</code>), <code>r</code> to 6, and <code>gasLimitCap</code> to <code>60_000_000</code>, the gas limit will increase by 6 gas per block for two years, reaching 30 million gas at the end of a $\approx$ 2 years period. The result of <code>compute_gas_limit</code> will be the gas limit aimed by the proposer for the block <code>blockNum</code>. none of this is enforced at the protocol level, and the proposer needs to still follow protocol rules related to the gas limit.</p> <h3 id="stepwise-linear-gas-limit-increase-strategy"><strong>Stepwise Linear Gas Limit Increase Strategy</strong></h3> <p>Add a new "Gas Limit" selection strategy that takes in Block Number <code>N</code> and spits out the Gas Limit <code>GL</code> for that block. The strategy is as follows:</p> <ul> <li>The gas limit <code>GL_t</code> at block <code>t</code> is calculated as:</li> </ul> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> compute_gas_limit</span><span>(</span><span class="z-variable z-parameter z-function">blockNum</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> blockNumStart</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> r</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> step_blocks_interval</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> gasLimitCap</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> blockNum</span><span class="z-keyword"> &lt;</span><span> blockNumStart</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> initialGasLimit</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> min</span><span>(</span><span>gasLimitCap</span><span>,</span><span> initialGasLimit</span><span class="z-keyword"> +</span><span> r</span><span class="z-keyword"> *</span><span> (</span><span>(</span><span>blockNum</span><span class="z-keyword"> -</span><span> blockNumStart</span><span>)</span><span class="z-keyword"> //</span><span> step_blocks_interval</span><span>)</span><span>)</span></span></code></pre> <p>Where:</p> <ul> <li><code>blockNum</code> is the block number for which the gas limit is being calculated.</li> <li><code>blockNumStart</code> is the block number at which the gas limit increase starts.</li> <li><code>initialGasLimit</code> is the initial gas limit at block <code>blockNumStart</code>.</li> <li><code>step_blocks_interval</code> is the number of blocks after which the gas limit increases (cooldown period).</li> <li><code>r</code> is the rate at which the gas limit increases per step.</li> <li><code>gasLimitCap</code> is the maximum gas limit that can be reached.</li> </ul> <p>This strategy has three main advantages:</p> <ul> <li>It provides larger, more visible, and distinct metric changes over each step.</li> <li>It allows for collection of more stabilized metrics over the length of the cooldown period.</li> <li>It gives the community more time to evaluate the impact of the gas limit increase and act accordingly.</li> </ul> <h3 id="exponential-gas-limit-increase-strategy"><strong>Exponential Gas Limit Increase Strategy</strong></h3> <p>Add a new "Gas Limit" selection strategy that takes in Block Number <code>N</code> and spits out the Gas Limit <code>GL</code> for that block. The strategy is as follows:</p> <ul> <li>The gas limit <code>GL_t</code> at block <code>t</code> is calculated as:</li> </ul> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> compute_gas_limit</span><span>(</span><span class="z-variable z-parameter z-function">blockNum</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> blockNumStart</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> doubling_blocks_interval</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> blockNum</span><span class="z-keyword"> &lt;</span><span> blockNumStart</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> initialGasLimit</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> min</span><span>(</span><span>gasLimitCap</span><span>,</span><span> initialGasLimit</span><span class="z-keyword"> *</span><span> (</span><span class="z-constant">2</span><span class="z-keyword"> **</span><span> (</span><span>(</span><span>blockNum</span><span class="z-keyword"> -</span><span> blockNumStart</span><span>)</span><span class="z-keyword"> /</span><span> doubling_interval</span><span>)</span><span>)</span><span>)</span></span></code></pre> <p>Where:</p> <ul> <li><code>blockNum</code> is the block number for which the gas limit is being calculated.</li> <li><code>blockNumStart</code> is the block number at which the gas limit increase starts.</li> <li><code>initialGasLimit</code> is the initial gas limit at block <code>blockNumStart</code>.</li> <li><code>doubling_blocks_interval</code> is the number of blocks after which the gas limit doubles.</li> </ul> <h2 id="rationale"><strong>Rationale</strong></h2> <h3 id="predictable-growth"><strong>Predictable Growth</strong></h3> <ul> <li><strong>Systematic Adjustment:</strong> <ul> <li>The gradual increase avoids sudden surges in gas limit that could destabilize the network. Instead, it provides a smooth transition, giving the ecosystem time to adapt to larger block sizes.</li> </ul> </li> </ul> <h3 id="controlled-limit-with-deactivation-block"><strong>Controlled Limit with Deactivation Block</strong></h3> <ul> <li> <p><strong>Automatic Safeguard:</strong></p> <ul> <li>The inclusion of a deactivation block ensures that the gas limit does not increase indefinitely, preventing potential negative impacts on network performance beyond the planned growth.</li> </ul> </li> <li> <p><strong>Community Consensus:</strong></p> <ul> <li>The deactivation block serves only as a checkpoint for the community to evaluate the impact of the gas limit increase, however, in the two-year period, the community can decide to halt the increase at any time and can also switch to a fixed gas limit if needed.</li> </ul> </li> </ul> <h2 id="backwards-compatibility"><strong>Backwards Compatibility</strong></h2> <p><strong>No Hard Fork Required</strong></p> <h2 id="security-considerations"><strong>Security Considerations</strong></h2> <ul> <li>The controlled gas limit increase strategy is designed to prevent sudden changes that could lead to network instability or security vulnerabilities.</li> <li>The fact that validators can re-adjust the gas limit in case of a DOS attack or other issues, makes the network more secure than to just increasing the gas limit manually in a cliff-like manner.</li> </ul> <h2 id="copyright"><strong>Copyright</strong></h2> <p>Copyright and related rights waived via CC0 1.0 Universal.</p> 2024-09-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Dev Bearhttps://github.com/itsdevbear https://wg-eips.ritovision.com/7775/

An opcode to burn native ether at the given address

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a <code>BURN</code> opcode to the EVM. When called, the opcode is to burn native ether at the address of the current evm context.</p> <h2 id="motivation">Motivation</h2> <p>The motivation for this proposal is to provide a standardized and efficient way to burn native ether directly within the EVM. Historically, contracts such as the BeaconDepositContract have "burned" ether by making it irrecoverable from the given address. This approach can lead to confusion and potential misuse. By introducing a dedicated <code>BURN</code> opcode, we can ensure a clear and consistent method for burning native ether. This could become useful for Ethereum L2s when transferring ether back to the L1, as well as other EVM L1 chains that could leverage this for their cryptoeconomics.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="behaviour">Behaviour</h3> <p>The <code>BURN</code> opcode <code>(0xFC)</code> is introduced with the following behavior:</p> <ol> <li>Pops one 32-byte word from the top of the stack, treating these bytes as the <code>uint256</code> amount of native ether to be burned.</li> <li>Retrieves the current address from the EVM execution context.</li> <li>Checks the balance of the current address.</li> <li>If the amount to be burned is greater than the balance of the current address, the opcode <code>MUST</code> revert.</li> <li>If the amount to be burned is 0, the execution <code>MUST NOT</code> revert.</li> <li>Subtracts the amount from the current address's native ether balance.</li> </ol> <p>When <code>BURN</code> is used in the context of a DELEGATECALL or CALLCODE, the contract whose balance is to be manipulated is the contract that issued the DELEGATECALL or CALLCODE instruction.</p> <p>When <code>BURN</code> is used in the context of a STATICCALL the call <code>MUST</code> revert.</p> <h3 id="gas-cost">Gas Cost</h3> <p>The base gas cost for the <code>BURN</code> opcode is 100 gas. The dynamic gas cost is determined as follows:</p> <ol> <li>If the value to be burned is 0, the dynamic gas cost is 0.</li> <li>If the account doesn't exist, or the balance of the account is 0, the dynamic gas cost is 0.</li> <li>Otherwise, the dynamic gas cost is 2800.</li> </ol> <p>The total gas cost for the <code>BURN</code> opcode is the sum of the base gas cost and the dynamic gas cost.</p> <h3 id="pseudocode">Pseudocode</h3> <p>Example pseudocode for the <code>BURN</code> opcode:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> op_burn</span><span>(</span><span class="z-variable z-parameter z-function">pc</span><span>,</span><span class="z-variable z-parameter z-function"> interpreter</span><span>,</span><span class="z-variable z-parameter z-function"> scope</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Consume the base gas cost</span></span> <span class="giallo-l"><span> interpreter</span><span>.</span><span>consume_gas</span><span>(</span><span class="z-constant">100</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Pop the value to be burned from the stack</span></span> <span class="giallo-l"><span> value_to_burn</span><span class="z-keyword"> =</span><span> scope</span><span>.</span><span>stack</span><span>.</span><span>pop</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If the value to be burned is 0, do not revert</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> value_to_burn</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> None</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Retrieve the current address from the EVM execution context</span></span> <span class="giallo-l"><span> current_address</span><span class="z-keyword"> =</span><span> scope</span><span>.</span><span>contract</span><span>.</span><span>address</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check the balance of the current address</span></span> <span class="giallo-l"><span> balance</span><span class="z-keyword"> =</span><span> interpreter</span><span>.</span><span>evm</span><span>.</span><span>state_db</span><span>.</span><span>get_balance</span><span>(</span><span>current_address</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If the value to be burned is greater than the balance, revert</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> value_to_burn</span><span class="z-keyword"> &gt;</span><span> balance</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ErrInsufficientBalance</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If the account balance is 0, return.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> balance</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> None</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Subtract the value from the current address&#39;s balance</span></span> <span class="giallo-l"><span> interpreter</span><span>.</span><span>evm</span><span>.</span><span>state_db</span><span>.</span><span>sub_balance</span><span>(</span><span>current_address</span><span>,</span><span> value_to_burn</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The account is known to exist at this point, thus we consume &quot;warm&quot; gas.</span></span> <span class="giallo-l"><span> interpreter</span><span>.</span><span>consume_gas</span><span>(</span><span class="z-constant">2800</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> None</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The introduction of the <code>BURN</code> opcode helps clean up a piece of weird semantics in the Ethereum. Historically, burning native ether involved sending them to an address from which they could not be recovered, such as the zero address or a contract with no withdrawal functionality. This method is not only inefficient but also confusing for indexers and other tools that track token movements. By providing a dedicated <code>BURN</code> opcode, we eliminate this ambiguity and ensure that the act of burning tokens is explicit and standardized.</p> <p>Potential Pros:</p> <ul> <li>Provides a clear and standardized method for burning native ether within smart contracts.</li> <li>Allows for better accounting practices of native token within smart contracts.</li> <li>Reduces the possibility of a smart contract exploit caused by native token that was marked as "burned" being unintetionally recovered.</li> </ul> <p>Potential Cons:</p> <ul> <li>Does not help remove unrecoverable ether sitting in existing contracts.</li> <li>New code in the clients</li> <li>New concept needed to be added to the yellow paper.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a new opcode and thus must be activated via a scheduled hardfork.</p> <h2 id="test-cases">Test Cases</h2> <!-- TODO --> <h2 id="reference-implementation">Reference Implementation</h2> <!-- TODO --> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Potentially opens up misuse when using <code>DELEGATECALL</code>.</li> </ul> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-09-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Andrei Maiborodahttps://github.com/gumb0 Piotr Dobaczewskihttps://github.com/pdobacz Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/7761/

Add EXTCODETYPE instruction to EOF to address common uses of EXTCODE* instructions

<h2 id="abstract">Abstract</h2> <p>Allow EOF contracts to discriminate between EOAs (Externally Owned Accounts) and contract accounts by introducing an <code>EXTCODETYPE</code> instruction.</p> <h2 id="motivation">Motivation</h2> <p>EOFv1 as scoped in <a href="https://wg-eips.ritovision.com/7692/">EIP-7692</a> removes code introspection capabilities from the EVM, including the <code>EXTCODESIZE</code> instruction (in <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>). This makes it hard for <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standard contracts to be implemented, as they rely on discovering whether a token's <code>safeTransfer</code> call target was an EOA or a contract account:</p> <ul> <li><code>safeTransfers</code> to EOAs succeed</li> <li><code>safeTransfers</code> to contract accounts call an <code>onERC721Received</code> (<code>onERC1155Received</code>) on them and expect to get a special magic return value, otherwise the transfer reverts (on the assumption that such a recipient may not be able to interact with the token)</li> </ul> <p>Application and library developers are also concerned about dynamic proxies written in EOF accidentally pointing to legacy accounts which cannot safely be called with <code>EXTDELEGATECALL</code>. They would like a way to differentiate between EOF and legacy contracts.</p> <p><code>EXTCODETYPE</code> is aimed to fill this gap and bring back the possibility to easily implement ERC-721 and ERC-1155 standard contracts in EOF as well as preserve EOF proxy contract safety.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLKNUM</code></td><td>tbd</td></tr> <tr><td><code>GAS_COLD_ACCOUNT_ACCESS</code></td><td>Defined as <code>2600</code> in the [Ethereum Execution Layer Spec Constants]</td></tr> <tr><td><code>GAS_WARM_ACCESS</code></td><td>Defined as <code>100</code> in the [Ethereum Execution Layer Spec Constants]</td></tr> <tr><td><code>TYPE_NONE</code></td><td>0</td></tr> <tr><td><code>TYPE_LEGACY_CONTRACT</code></td><td>1</td></tr> <tr><td><code>TYPE_EOF_CONTRACT</code></td><td>2</td></tr> </tbody></table> <p>We introduce a new EOFv1 instruction on the block number <code>FORK_BLKNUM</code>: <code>EXTCODETYPE</code> (<code>0xe9</code>)</p> <p>EOF code which contains this instruction before <code>FORK_BLKNUM</code> is considered invalid. Beginning with block <code>FORK_BLKNUM</code> <code>0xe9</code> is added to the set of valid EOFv1 instructions.</p> <h3 id="execution-semantics">Execution Semantics</h3> <h4 id="extcodetype"><code>EXTCODETYPE</code></h4> <ul> <li>deduct <code>GAS_WARM_ACCESS</code> gas</li> <li>pop 1 argument <code>target_address</code> from the stack</li> <li>if <code>target_address</code> has any of the high 12 bytes set to a non-zero value (i.e. it does not contain a 20-byte address), then halt with an exceptional failure <ul> <li>Notice: Future expansion of the EVM address space may remove or reduce the number of bytes in this check.</li> </ul> </li> <li>deduct <code>GAS_COLD_ACCOUNT_ACCESS - GAS_WARM_ACCESS</code> if <code>target_address</code> is not in <code>accessed_addresses</code> and add <code>target_address</code> to <code>accessed_addresses</code></li> <li>Load the code from <code>target_address</code> and refer to it as <code>loaded_code</code></li> <li>if <code>loaded_code</code> is empty (does not exist or has zero length), push <code>TYPE_NONE</code> onto the stack and stop processing the operation</li> <li>If <code>loaded_code</code> indicates a delegation designator (for example, <code>0xef0100</code> as defined in <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a>), <ul> <li>replace <code>loaded_code</code> with the delegated code.</li> <li>deduct gas in accordance with the delegation designation rules</li> </ul> </li> <li>If <code>loaded_code</code> indicates an EOFv1 packaged contract (starts with the bytes <code>0xef0001</code>) push <code>TYPE_EOF_CONTRACT</code> onto the stack and stop processing the operation</li> <li>Otherwise, push <code>TYPE_LEGACY_CONTRACT</code> onto the stack and stop processing the operation</li> </ul> <p>Note: if there is not enough gas to deduct for delegation designation the whole message frame will halt, making updating the <code>accessed_addresses</code> irrelevant.</p> <p>Note: If <code>target_address</code> or the delegation designator points to an account with a contract mid-creation then the code is empty and returns <code>0</code> (<code>TYPE_NONE</code>). This is aligned with similar behavior of instructions like <code>EXTCODESIZE</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="alternative-solutions">Alternative solutions</h3> <p>There have been other solutions proposed to alleviate the problems related to lack of code introspection required for ERC-721 and ERC-1155 standards:</p> <ol> <li>Extra status code for <code>EXT*CALL</code> instruction - allowing to discriminate a result coming from calling an EOA</li> <li>Extra argument for <code>EXT*CALL</code> (a "fail if EOA" flag)</li> <li>Two return values from <code>EXT*CALL</code> (status code + whether it was EOA)</li> <li><code>EXT*CALL</code> setting a new <code>callstatus</code> register (+ a new <code>CALLSTATUS</code> instruction)</li> <li>Re-enable <code>EXTCODESIZE</code> in EOF, keeping its behavior same as in legacy</li> </ol> <p><code>EXTCODETYPE</code> has been chosen as the most elegant and minimal solution satisfying the requirements at hand and still able to be introduced in EOFv1.</p> <h3 id="reuse-the-0x3b-extcodesize-opcode-for-extcodetype">Reuse the <code>0x3b</code> (<code>EXTCODESIZE</code>) opcode for <code>EXTCODETYPE</code></h3> <p>A new opcode is preferred by a general policy to not reuse opcodes. Also <code>EXTCODETYPE</code> can be rolled out in legacy EVM if desired.</p> <h3 id="keep-code-introspection-banned">Keep code introspection banned</h3> <p>Removing code introspection is one of the tenets of EOF and <code>EXTCODETYPE</code> would be an exception from the principle. Without <code>EXTCODETYPE</code>, ERC-721 and ERC-1155 standard implementations have to resort to either:</p> <ol> <li>Leveraging a "booster contract" which would be legacy and would call <code>EXTCODESIZE</code> for them. This has been deemed inelegant and inconvenient from the point of view of library implementers, requiring them to hard code an address of such a contract (with the usual address-related problems arising on different EVM chains)</li> <li>Continuing to use legacy EVM themselves. This is suboptimal, since EVM compilers are likely to at some point deprecate legacy EVM as compilation target</li> <li>Updating the standards to not rely on code introspection patterns in <code>safeTransfer</code> safeguards. This can be accomplished for example by leveraging <a href="https://wg-eips.ritovision.com/165/">ERC-165</a>, leaving out only contracts which do not implement ERC-165, and at the same time have non-throwing fallback functions, as indistinguishable from EOAs. This is not easy to achieve since ERC-721 and ERC-1155 are Final and adopted in practice.</li> </ol> <h3 id="endgame-account-abstraction-issues">"Endgame Account Abstraction" issues</h3> <p><code>EXTCODETYPE</code> (and earlier <code>EXTCODESIZE</code> available in legacy EVM) are claimed to slow down AA adoption, because they encourage patterns which discriminate between smart contract and EOA accounts, e.g. not allowing the former to interact. However, there are counterarguments that it is up to other factors which slow down AA adoption (assumption that accounts can produce ECDSA signatures, and the lack of adoption of smart contract signatures).</p> <h3 id="including-safeguarding-against-proxy-bricking">Including safeguarding against proxy bricking</h3> <p>In parallel to the ERC-721 / ERC-1155 problem, another potential risk has been brought to attention. Since EOFv1 prohibits <code>EXTDELEGATECALL</code> targeting legacy contracts, there exists a scenario where an EOF proxy contract accidentally upgrades its implementation to a legacy EVM one. Since reverting this or upgrading again (using current proxy standards) requires the implementation contract to be called, it would effectively render the contract unusable.</p> <p>For this reason it was decided to have a generalized <code>EXTCODETYPE</code> instruction instead of a <code>HASCODE</code> instruction. This provides the means to safeguard against such a scenario that a simpler instruction could not.</p> <h3 id="relation-to-eip-7702-set-eoa-account-code">Relation to <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> "Set EOA account code"</h3> <p>After <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> is activated, the discrimination between EOAs and contract accounts using <code>EXTCODESIZE</code> (or <code>EXTCODETYPE</code>) has an edge case: Whenever an EOA sets its code to a contract account which does not respond as expected to an <code>onERC721Received</code> (<code>onERC1155Received</code>) callback, transfers to it will revert, despite the recipient being able to interact with the token. This has been deemed unlikely to be a problem, as for the intended real-world uses of EIP-7702, those callbacks will be implemented by designator codes.</p> <p>Because of the requirement that EOF proxy contracts be able to determine if the new target is safe we cannot return a value for indicating that the account itself is delegated without also providing the delegated address. Instead, we return the code for the account that has the delegated code, applying the delegation. This is because the executable code is what matters for proxy updates.</p> <p>This differs from <code>EXTCODECOPY</code> and <code>EXTCODEHASH</code> behavior which do return a hash and short code indicating the proxy. The behavior of <code>EXTCODETYPE</code> is closer to a "code executing operation" in purpose as it is meant to describe the execution behavior of the account.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>EXTCODETYPE</code> at <code>0xe9</code> can be introduced in a backwards compatible manner into EOFv1 (no bump to version), because <code>0xe9</code> has been rejected by EOF validation before <code>FORK_BLKNUM</code> and there are no EOF contracts on-chain with a <code>0xe9</code> which would have their behavior altered.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion <!-- TODO --></p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a></p> <p>[Ethereum Execution Layer Spec Constants] :https://github.com/ethereum/execution-specs/blob/1adcc1bfe774798bcacc685aebc17bd9935078c3/src/ethereum/cancun/vm/gas.py#L65-L66</p> 2024-08-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Max Resnickhttps://github.com/MaxResnick Davide Crapishttps://github.com/dcrapis Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/7762/

Adjust the MIN_BASE_FEE_PER_BLOB_GAS to speed up price discovery on blob space

<h2 id="abstract">Abstract</h2> <p>This EIP proposes an increase to the MIN_BASE_FEE_PER_BLOB_GAS to speed up price discovery on blob space. It also resets the excess blob gas to 0, to avoid a blob base fee spike.</p> <h2 id="motivation">Motivation</h2> <p>When scoping 4844, the thinking was that blobs would only enter price discovery once, relatively quickly after the blob rollout; however, this has not been the case. In fact, blobs have entered price discovery several times, and the frequency of price discovery events is likely to increase in the short term as we approach saturation of capacity. Moreover, the roadmap calls for further increases in blob capacity in subsequent hardforks, which may lead to price discovery events happening around those changes in the future.</p> <p>Increasing the MIN_BASE_FEE_PER_BLOB_GAS will speed up price discovery on blob space.</p> <h2 id="specification">Specification</h2> <h3 id="min-base-fee-per-blob-gas-increase"><code>MIN_BASE_FEE_PER_BLOB_GAS</code> Increase</h3> <p>The main specification change introduced by this EIP is setting MIN_BASE_FEE_PER_BLOB_GAS to 2**25:</p> <pre class="giallo z-code"><code data-lang="diff"><span class="giallo-l"><span class="z-punctuation z-definition z-inserted">+</span><span class="z-markup z-inserted"> MIN_BASE_FEE_PER_BLOB_GAS = 2**25</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-deleted">-</span><span class="z-markup z-deleted"> MIN_BASE_FEE_PER_BLOB_GAS = 1</span></span></code></pre><h3 id="excess-blob-gas-reset"><code>excess_blob_gas</code> Reset</h3> <p>To avoid a blob base fee spike, the <code>calc_excess_blob_gas</code> is modified to reset <code>excess_blob_gas</code> to 0 at the fork. To detect the fork height, the block timestamp needs to be passed into <code>calc_excess_blob_gas</code>.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> calc_excess_blob_gas</span><span>(</span><span class="z-variable z-parameter z-function">parent</span><span>:</span><span> Header</span><span>,</span><span class="z-variable z-parameter z-function"> block_timestamp</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> at the fork, set excess_blob_gas to 0</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> parent</span><span>.</span><span>timestamp</span><span class="z-keyword"> &lt;</span><span class="z-constant"> FORK_TIMESTAMP</span><span class="z-keyword"> and</span><span> block_timestamp</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> FORK_TIMESTAMP</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> otherwise, calculate normally</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre> <p><code>validate_block</code> needs to be updated to pass the block timestamp into <code>calc_excess_blob_gas</code>:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> validate_block</span><span>(</span><span class="z-variable z-parameter z-function">block</span><span>:</span><span> Block</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> add timestamp parameter</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> block</span><span>.</span><span>header</span><span>.</span><span>excess_blob_gas</span><span class="z-keyword"> ==</span><span> calc_excess_blob_gas</span><span>(</span><span>block</span><span>.</span><span>parent</span><span>.</span><span>header</span><span>,</span><span> block</span><span>.</span><span>header</span><span>.</span><span>timestamp</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The current MIN_BASE_FEE_PER_BLOB_GAS is 1 wei. This is many orders of magnitude lower than the prevailing price of blobs when blobs enter price discovery. Whenever demand for blobs exceeds supply, blobs enter price discovery, but traversing the 8 orders of magnitude between 1 wei and the point where elasticity of demand starts to decrease takes a long time.</p> <p>The blob base fee can at most double every $\log_{1.125}(10) = 5.885$ blocks when blocks use all available blob space. When blobs enter price discovery, they must climb many factors of 2 to reach the prevailing price.</p> <p>To set the parameter appropriately, one approach is to look at the cost of simple transfers when base fees are low. The cost of a simple transfer when the base fee is 1 GWEI is ~5 cents USD at today's prices (2,445.77$ ETH/USDC). We can try to peg the minimum price of a blob to that. Today, to reach this price, it requires an excess blob gas of <code>63070646</code>. When you calculate how long this would take to reach from 0 excess blob gas, you get:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>63070646/(3 * 2**17) = 160.396947225</span></span></code></pre> <p>The closest power of 2 to the corresponding reserve price would be <code>MIN_BASE_FEE_PER_BLOB_GAS = 2**27</code>. Out of an abundance of caution, we will go with <code>MIN_BASE_FEE_PER_BLOB_GAS = 2**25</code> to ensure that even if the price of ETH rises significantly, the reserve price will not be set too high. This value corresponds to a minimum blob price of ~1 cent at today's prices (2,445.77$ ETH/USDC). Further, decreasing the <code>MIN_BASE_FEE_PER_BLOB_GAS</code> beyond <code>2**25</code> would slow down price discovery without a significant decrease in the price of blobs when the network is unsaturated.</p> <p>Below you will find a plot provided by @dataalways showing the fraction of type 3 transaction fees that are paid in blob base fees for different values of <code>MIN_BASE_FEE_PER_BLOB_GAS</code>. Note that even after the proposed change, for historical values of l1 gas, the price of blobs would have been dominated by the price of the L1 gas.</p> <p><img src="https://wg-eips.ritovision.com/7762/./assets/base_fee_1.png" alt="Base Fee 1" /></p> <p><img src="https://wg-eips.ritovision.com/7762/./assets/base_fee_225.png" alt="Base Fee 2^25" /></p> <hr /> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is not backwards compatible and requires a coordinated upgrade across all clients at a specific block number.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Rollups that use blobs as a data availability layer will need to update their posting strategies.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-08-13T00:00:00+00:00 2026-02-11T14:49:28+00:00 Martin Holst Swendehttps://github.com/holiman Marius van der Wijdenhttps://github.com/MariusVanDerWijden Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/7756/

Updates EIP-3155 tracing to add EOF support

<h2 id="abstract">Abstract</h2> <p>Updates the <a href="https://wg-eips.ritovision.com/3155/">EIP-3155</a> JSON tracing specification to support EOF features.</p> <h2 id="motivation">Motivation</h2> <p>EIP-3155 defined a tracing standard for Legacy EVM operations. However, the EVM Object Format (<a href="https://wg-eips.ritovision.com/7692/">EIP-7692</a>) adds a number of features that need to be reflected in debugging traces.</p> <p>The use of these traces has also moved out from state testing, including live block tracing and differential fuzzing, increasing the need to keep tracing up to date.</p> <p>This EIP has multiple goals:</p> <ul> <li>Add members to the trace object to support new EOF features.</li> <li>Support tracing contracts contained in an EOF container as well as uncontained "legacy" contracts in the same trace.</li> <li>Clarify any previous ambiguities in the EIP-3155 specification.</li> </ul> <h2 id="specification">Specification</h2> <p>To promote clarity and provide a cohesive specification, the entire tracing specification will be presented with alterations in-line rather than as a set of diffs on top of EIP-3155. Differences will be highlighted in the Backwards Compatibility section.</p> <p>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> <h3 id="datatypes">Datatypes</h3> <table><thead><tr><th>Type</th><th>Explanation</th><th>JSON member example</th></tr></thead><tbody> <tr><td>Number</td><td>JSON number</td><td><code>"pc":0</code></td></tr> <tr><td>Hex-Number</td><td>Hex-encoded number</td><td><code>"gas":"0x2540be400"</code></td></tr> <tr><td>String</td><td>Plain string</td><td><code>"opName":"PUSH1"</code></td></tr> <tr><td>Hex-String</td><td>Hex-encoded string</td><td><code>"returnData":"0x60616203"</code></td></tr> <tr><td>Array</td><td>Array of Hex-Strings</td><td><code>"stack":["0x0", "0x0"]</code></td></tr> <tr><td>Key-Value</td><td>Key-Value structure with key and values encoded as hex strings</td><td><code>"storage":{"0x0":"0x1", "0x1":"0x1"}</code></td></tr> <tr><td>Boolean</td><td>Json bool can either be true or false</td><td><code>"pass": true</code></td></tr> </tbody></table> <ul> <li>Clients may OPTIONALLY output Number where a Hex-Number is expected and vice-versa. Clients that do this SHOULD provide a CLI option to strictly observe the correct output type.</li> <li>Numbers larger than 2^53 - 1 must be represented as Hex-Numbers. This is a limitation of JSON.</li> <li>Consumers of EIP-7756 traces SHOULD be written in a way that members of type Hex-Number and Number may be provided a Number or Hex-Number instead, respectively.</li> <li>Note that there is no string formatted decimal number alternative. Decimal representations are always JSON numbers, and hex representations are always strings encoding hex numbers.</li> </ul> <h3 id="output">Output</h3> <ul> <li>The client outputs one JSON object per EVM operation executed.</li> <li>The client MUST NOT output multiple lines for the same operation execution.</li> <li>The client MUST NOT output a line for the <code>STOP</code> operation if an error occurred, or if the contract runs out of instructions.</li> </ul> <h4 id="required-fields">Required Fields</h4> <p>Each trace line MUST have these fields.</p> <table><thead><tr><th>Name</th><th>Type</th><th>Explanation</th></tr></thead><tbody> <tr><td><code>pc</code></td><td>Number</td><td>Program Counter</td></tr> <tr><td><code>op</code></td><td>Hex-Number</td><td>OpCode</td></tr> <tr><td><code>opName</code></td><td>String</td><td>Name of the operation</td></tr> <tr><td><code>gas</code></td><td>Number</td><td>Gas left before executing this operation</td></tr> <tr><td><code>stack</code></td><td>Array of Hex-Numbers</td><td>Array of all values on the stack</td></tr> <tr><td><code>depth</code></td><td>Number</td><td>Depth of the call stack</td></tr> <tr><td><code>error</code></td><td>Hex-String</td><td>Description of an error (SHOULD contain revert reason if supported)</td></tr> </tbody></table> <ul> <li> <p>The <code>pc</code> value is zero indexed from the beginning of the contract when the contract is not in an EOF container, or from the beginning of the container EOF container. For legacy contracts the first execution line is for <code>"pc":0</code>. For EOF contracts the zero byte corresponds to the <code>0xEF</code> magic byte. The first line of execution will not be at <code>"pc":0</code> but at the first byte of the first code section executed.</p> </li> <li> <p><code>opName</code> SHOULD be the most current name of the operation, in cases where operations have multiple specification names (<code>SELFDESTRUCT</code> and <code>PREVRANDAO</code>)</p> </li> <li> <p>If <code>stack</code> is empty an empty array (<code>[]</code>) is used instead of <code>null</code>.</p> </li> <li> <p><code>depth</code> starts at 1.</p> </li> <li> <p><code>error</code> SHOULD be omitted if a prior CALL series or CREATE series operation within the current frame has not returned a revert reason and the current operation did not trigger an exceptional halt.</p> </li> </ul> <!-- - `stack` MAY exclude stack items that are more than any operation will need to execute, which is currently seven stack items. If any stack items are excluded past that point then all stack items past that point MUST be excluded --> <h4 id="recommended-fields">Recommended Fields</h4> <p>Each trace line SHOULD have these fields in the conditions they are indicated for.</p> <table><thead><tr><th>Name</th><th>Type</th><th>Explanation</th></tr></thead><tbody> <tr><td><code>gasCost</code></td><td>Number</td><td>Gas cost of this operation</td></tr> <tr><td><code>memSize</code></td><td>Number</td><td>Size of memory array</td></tr> <tr><td><code>returnData</code></td><td>Hex-String</td><td>Data returned by function call</td></tr> <tr><td><code>refund</code></td><td>Hex-Number</td><td>Amount of <strong>global</strong> gas refunded</td></tr> </tbody></table> <ul> <li><code>gasCost</code> is the sum of all gas costs, including dynamic costs such as memory expansion, call stipend, and account warming costs.</li> <li><code>memSize</code> is counted in 8-bit bytes, not 256-bit words.</li> <li><code>returnData</code> SHOULD NOT be present if a CALL series operation has not completed within the current frame.</li> </ul> <h4 id="optional-fields">Optional Fields</h4> <p>Each trace line MAY have these fields in the conditions they are indicated for. If a field is to be omitted within a trace, it MUST always be omitted within the same trace.</p> <table><thead><tr><th>Name</th><th>Type</th><th>Explanation</th></tr></thead><tbody> <tr><td><code>section</code></td><td>Number</td><td>Current EOF section being executed</td></tr> <tr><td><code>immediate</code></td><td>Hex-String</td><td>Immediate argument of the Opcode</td></tr> <tr><td><code>functionDepth</code></td><td>Number</td><td>Depth of the <a href="https://wg-eips.ritovision.com/4750/">EIP-4750</a> CALLF return stack</td></tr> <tr><td><code>memory</code></td><td>Array of Hex-Strings</td><td>Array of all allocated values</td></tr> <tr><td><code>storage</code></td><td>Key-Value</td><td>Array of all stored values</td></tr> </tbody></table> <ul> <li>The <code>section</code> member must only be present when tracing a contract contained in an EOF container.</li> <li>The <code>immediate</code> field MUST NOT be present for operations without immediate data. <ul> <li>For PUSH series operations, this field is OPTIONAL as the immediate data is pushed onto the stack</li> <li>For RJUMPV this would include the table length and the entire table. Clients MAY instead store just the table length.</li> <li>For all other operations with immediate data the entire immediate data, including leading zeros, SHOULD be present.</li> </ul> </li> <li><code>functionDepth</code> starts at 1, and MAY be omitted if it is 1.</li> <li><code>functionDepth</code> MUST NOT be present for trace lines of code not in an EOF container.</li> <li>If <code>memory</code> is empty an empty array (<code>[]</code>) is used instead of <code>null</code>.</li> <li>The <code>storage</code> member SHOULD only include items read or written via <code>SSTORE</code> or <code>SLOAD</code>, and not the account's entire storage.</li> </ul> <p><em>Example:</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{&quot;pc&quot;:0,&quot;op&quot;:96,&quot;gas&quot;:&quot;0x2540be400&quot;,&quot;gasCost&quot;:&quot;0x3&quot;,&quot;memory&quot;:&quot;0x&quot;,&quot;memSize&quot;:0,&quot;stack&quot;:[],&quot;depth&quot;:1,&quot;error&quot;:null,&quot;opName&quot;:&quot;PUSH1&quot;}</span></span></code></pre><h3 id="summary-line">Summary Line</h3> <p>At the end of execution, the client SHOULD print summary info. This summary MUST be a single JSON object.</p> <p>This info SHOULD have the following members.</p> <table><thead><tr><th>Name</th><th>Type</th><th>Explanation</th></tr></thead><tbody> <tr><td><code>stateRoot</code></td><td>Hex-String</td><td>Root of the state trie after executing the transaction</td></tr> <tr><td><code>output</code></td><td>Hex-String</td><td>Return values of the function</td></tr> <tr><td><code>gasUsed</code></td><td>Number</td><td>All gas used by the transaction</td></tr> <tr><td><code>pass</code></td><td>Boolean</td><td>If the tx was successful, or if the test passed</td></tr> <tr><td><code>time</code></td><td>Number</td><td>Time in nanoseconds needed to execute the transaction</td></tr> <tr><td><code>fork</code></td><td>String</td><td>Name of the fork rules used for execution</td></tr> </tbody></table> <ul> <li><code>time</code> and <code>fork</code> fields MAY be provided.</li> </ul> <p><em>Example</em>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{&quot;stateRoot&quot;:&quot;0xd4c577737f5d20207d338c360c42d3af78de54812720e3339f7b27293ef195b7&quot;,&quot;output&quot;:&quot;&quot;,&quot;gasUsed&quot;:&quot;0x3&quot;,&quot;pass&quot;:&quot;true&quot;,&quot;time&quot;:141485}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This EIP is an extension of the EIP-3155 tracing features that has been in use for years. Rather than dramatically re-boot the feature, the information was added to the existing traces.</p> <p>A "mini" trace was contemplated to allow for tracing to be included in tools such as <code>t8n</code> and to allow for more efficient RPC tracing calls, but that seemed sufficiently different that it would be a stand-alone EIP rather than an EIP that adds features to the existing tracing capabilities.</p> <p>The idea of moving to a JSON Schema was rejected to ensure maximum compatibility with existing clients.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Clients emitting tracing JSON for uncontained "legacy" contracts will produce a compatible trace, except as outlined below</p> <h3 id="changes-from-eip-3155">Changes from EIP-3155</h3> <ul> <li>The term Client Under Test or CUT has been replaced simply with "client."</li> <li><code>gas</code>, <code>gasCost</code>, and <code>gasUsed</code> are now Number types.</li> <li><code>opcode</code> is now a Hex-Number type.</li> </ul> <h3 id="additions-to-eip-3155">Additions to EIP-3155</h3> <ul> <li>The <code>immediate</code> member was added to support the large number of instructions that contain immediate operations. Without this change, users would need bytes of the contracts being executed to rationalize the traces.</li> <li>The <code>section</code> and <code>functionDepth</code> members were added to support <a href="https://wg-eips.ritovision.com/4750/">EIP-4750</a> EOF Functions.</li> <li>Added clarification around where <code>pc</code> indexes when run in an EOF container.</li> <li>Added Hex-Number/Number interchangeability expectations. Clients MAY provide either types when one is specified and consumers SHOULD be prepared to accept either type. Clients SHOULD provide a flag to output members with the specified number type only.</li> </ul> <h3 id="clients">Clients</h3> <p>Besu, evmone, EthereumJS, Geth, Nethermind, and Reth already produce these standard traces in various tools. Adding the new fields will align with work needed to support the EOF EIPs enumerated in EIP-7692.</p> <h2 id="test-cases">Test Cases</h2> <p>This is the trace output from the Ethereum Execution Specification Test from one of the parameterized executions of <a rel="external" href="https://github.com/ethereum/execution-spec-tests/blob/632d151ea8a71d09a3a0acbdb85d97fa18c8456b/tests/prague/eip7692_eof_v1/eip3540_eof_v1/test_execution_function.py#L304-L335">test_eof_functions_contract_call_succeed</a>. Memory and return data is disabled.</p> <pre class="giallo z-code"><code data-lang="jsonl"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x60</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49979000</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">3</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">PUSH1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">2</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x60</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49978997</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">3</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">PUSH1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">4</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x60</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49978994</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">3</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">PUSH1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">6</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x60</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49978991</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">3</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">PUSH1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">8</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x60</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49978988</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">3</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">PUSH1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">10</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x61</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49978985</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">3</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">PUSH2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">13</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x5a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49978982</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">2</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x1000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">GAS</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">14</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xf1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49978980</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49198100</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x1000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x2fa9e64</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">CALL</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">25</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">section</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xe3</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">immediate</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0001</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49195500</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">5</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">2</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">CALLF</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">29</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">section</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xe4</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49195495</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">3</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">2</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">functionDepth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">2</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">RETF</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">28</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">section</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x00</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49195492</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">2</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">STOP</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">15</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x60</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49976372</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">3</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">PUSH1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">17</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x55</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49976369</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">22100</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">SSTORE</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">pc</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">18</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x00</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gas</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">49954269</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasCost</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">memSize</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">stack</span><span class="z-support">&quot;</span><span>:</span><span>[</span><span>]</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">depth</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">refund</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">0</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">opName</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">STOP</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">output</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">gasUsed</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">45731</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">fork</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Osaka</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">postHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x2c47b4070c1eef501d9548959c3abde2d8dc78ed1d819697c61d2b0861cc78cf</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">pass</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">true</span><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Clients should be aware that tracing can be expensive both in terms of CPU overhead and network bandwidth. Tracing endpoints should not be enabled by default, and when they are enabled should have access restrictions on the network level. Failure to do so could result in a client being overwhelmed with requests and, if operating as a validator, cause the client to fail to provide execution attestations in a timely manner.</p> <p>Differential fuzzing is also a double-edged sword. While it allows client teams the ability to identify consensus splits, the client teams need to be prompt in fixing any issues that are discovered.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-07-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Stokeshttps://github.com/ralexstokes https://wg-eips.ritovision.com/7742/

Have CL verify blob maximum and have EL get target value from CL

<h2 id="abstract">Abstract</h2> <p>Update blob maximum and target verification from <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>.</p> <p>The execution layer no longer verifies the blob maximum and receives the target dynamically from the consensus layer.</p> <h2 id="motivation">Motivation</h2> <p>Following EIP-4844, the execution layer (EL) maintains a hard-coded blob target value and blob maximum value. Given the relationship of the EL and the consensus layer (CL) node software, the verification of the blob maximum is redundant so it can be removed entirely without any change in security. The blob maximum is still provided during block construction via the Engine API. This EIP also changes how the EL sources the current blob target value for two reasons:</p> <ol> <li> <p>Gain more flexibility over the value, rather than the static <code>TARGET == MAX // 2</code> relation in EIP-4844.</p> </li> <li> <p>Uncouple development and deployment of the CL and EL layers in the event it is desirable to change the blob target value.</p> </li> </ol> <h3 id="background">Background</h3> <p>The data facility introduced via EIP-4844 adds blobs to Ethereum blocks, which are simply fixed sets of data that can be included in the canonical chain but have no execution semantics (cf. <code>calldata</code> in an Ethereum transaction).</p> <p>The protocol specifies a maximum allowed blob count per block to prevent DoS vectors via the abuse of this data facility. The protocol also maintains an <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>-like "target" value for an intended running average amount of blob throughput per unit time. Blob usage is compared against this target to influence a "blob base fee" to administer allocation of this resource to users of the Ethereum protocol.</p> <p>Both of these values are currently hard-coded in the EL after EIP-4844 and the blob maximum is separately hard-coded in the CL following EIP-4844. This EIP proposes a set of changes to uncouple these values across the CL and EL to make development and deployment of changes to the blob count easier.</p> <h4 id="maximum-blobs-per-block">Maximum blobs per block</h4> <p>The blob maximum is verified in the CL node and the EL inherits this verification during the consistency check of the versioned hashes corresponding to each blob as specified by the Engine API. Because of this, the strict check specified by EIP-4844 is unnecessary.</p> <h4 id="target-amount-of-blobs-per-block">Target amount of blobs per block</h4> <p>The target is currently specified as a fixed value in relation to the blob count. The Ethereum community intends to increase the blob parameters as part of its scaling strategy and the ability to have a more flexible target value in relation to the blob max is desirable to reduce rigidity in this protocol parameter.</p> <p>Even if the EL keeps a fixed target value based on the max, removing the max implies the EL would not know what the target value should be. To address this lack of information, this EIP proposes the CL sends the current target value to the EL with each provided payload over the Engine API. The EL block header will also need to be extended with this target value to preserve the security of optimistic sync.</p> <h2 id="specification">Specification</h2> <h3 id="block-structure-and-validity">Block structure and validity</h3> <p>Upon activation of this EIP, execution clients <strong>MUST</strong> extend the header schema with an additional 64-bit field: the <code>target_blobs_per_block</code>. This value is set to the current target blob count. The Engine API is modified along with this EIP to provide the <code>target_blobs_per_block</code> with each payload and implementations can use this value to correctly set the block header field.</p> <p>Validity of the <code>target_blobs_per_block</code> is guaranteed from the consensus layer, much like how withdrawals are handled.</p> <p>When verifying a block, execution clients <strong>MUST</strong> ensure the target blob count in the block header matches the one provided by the consensus client.</p> <p>For a genesis block with no existing parent, the value should be set according to the agreed specification for the target blob count given by that genesis block's protocol rule set.</p> <h3 id="block-processing">Block processing</h3> <p>Upon activating this EIP (i.e. before processing any transactions), the verification of the blob maximum as given in EIP-4844 can be skipped. Concretely, this means any logic relating to <code>MAX_BLOB_GAS_PER_BLOCK</code> as given in EIP-4844 can be deprecated.</p> <p>Additionally, <code>calc_excess_blob_gas</code> is updated as follows:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> calc_excess_blob_gas</span><span>(</span><span class="z-variable z-parameter z-function">parent</span><span>:</span><span> Header</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span> target_blob_gas</span><span class="z-keyword"> =</span><span> parent</span><span>.</span><span>target_blobs_per_block</span><span class="z-keyword"> *</span><span class="z-constant"> GAS_PER_BLOB</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> parent</span><span>.</span><span>excess_blob_gas</span><span class="z-keyword"> +</span><span> parent</span><span>.</span><span>blob_gas_used</span><span class="z-keyword"> &lt;</span><span> target_blob_gas</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> parent</span><span>.</span><span>excess_blob_gas</span><span class="z-keyword"> +</span><span> parent</span><span>.</span><span>blob_gas_used</span><span class="z-keyword"> -</span><span> target_blob_gas</span></span></code></pre> <p>Otherwise, the specification of EIP-4844 is not changed. For example, blob base fee accounting and excess blob gas tracking occur in the exact same way.</p> <h3 id="block-construction">Block construction</h3> <p>The Engine API is extended to provide both the <code>target_blobs_per_block</code> and the <code>max_blobs_per_block</code> when the CL requests the EL to construct a payload for proposal.</p> <p>These values should be used to ensure the correct number of blobs are included in any constructed payload, and to ensure that the blob base fee accounting is correctly computed.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-not-have-the-cl-also-compute-the-blob-base-fee-and-remove-any-notion-of-blob-counts-from-el-processing">Why not have the CL also compute the blob base fee and remove any notion of blob counts from EL processing?</h3> <p>Hoisting the full computation into the CL is possible, but it does violate the separation of concerns between these two layers of the protocol stack. The CL maintains a maximum value to address e.g. DoS risks, and the EL maintains knowledge of the target value to address fee accounting. Putting the target computation in the CL violates the respective responsibilities of each layer.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No issues.</p> <h2 id="test-cases">Test Cases</h2> <p>N/A</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>N/A</p> <h2 id="security-considerations">Security Considerations</h2> <p>N/A</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-07-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Guillaume Ballethttps://github.com/gballet Wei Han Nghttps://github.com/weiihann https://wg-eips.ritovision.com/7736/

Simple state expiry scheme in which only "extension-and-suffix trees" are expired.

<h2 id="abstract">Abstract</h2> <p>Adds an "update epoch" to the verkle tree extension node. When it is time for an epoch to expire, the extension node and its suffix nodes can be deleted.</p> <p>A new transaction type with a simple verkle proof pays for the costs of reactivating the extension and suffix nodes, and updating the epoch counter.</p> <h2 id="motivation">Motivation</h2> <p>Previous attempts at implementing state expiry have been stalled by the quickly-increasing complexity, require heavy change in the structure of ethereum (address space extension, oil, multiple trees, ...). This proposal is offering a simpler albeit non-exhaustive approach to state expiry: only removing the leaf nodes and leaving the rest of the tree intact. This removes the need for methods that would be detrimental to the user and developer experience.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="constants">Constants</h3> <table><thead><tr><th>Name</th><th>Description</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_TIME</code></td><td>Fork activation time</td><td>TBD</td></tr> <tr><td><code>EPOCH_LENGTH</code></td><td>Duration of an epoch, in s</td><td>15778800 (6 months)</td></tr> <tr><td><code>INITIAL_EPOCH_COUNTER</code></td><td>The epoch that ends at timestamp <code>FORK_TIME</code></td><td>0</td></tr> <tr><td><code>NUM_ACTIVE_EPOCHS</code></td><td>Number of concurrently unexpired epochs</td><td>2</td></tr> <tr><td><code>RESURRECT_TX_TYPE</code></td><td>Type ID for resurrection transactions</td><td>TBD</td></tr> </tbody></table> <h3 id="change-to-the-verkle-tree">Change to the verkle tree</h3> <p>Add an integral variable called <code>current_epoch</code>. It is initialized to <code>INITIAL_EPOCH_COUNTER</code> before the fork, and contains the current epoch number.</p> <p>Add a new <code>last_epoch</code> field to the extension node:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> extension_and_suffix_tree</span><span>(</span><span class="z-variable z-parameter z-function">stem</span><span>:</span><span> bytes31</span><span>,</span><span class="z-variable z-parameter z-function"> values</span><span>:</span><span> Dict</span><span>[</span><span>byte</span><span>,</span><span> bytes32</span><span>]</span><span>,</span><span class="z-variable z-parameter z-function"> last_epoch</span><span>:</span><span class="z-support"> int</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span> sub_leaves</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> *</span><span class="z-constant"> 512</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> suffix</span><span>,</span><span> value</span><span class="z-keyword"> in</span><span> values</span><span>.</span><span>items</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> sub_leaves</span><span>[</span><span class="z-constant">2</span><span class="z-keyword"> *</span><span> suffix</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>value</span><span>[</span><span>:</span><span class="z-constant">16</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">little</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">128</span></span> <span class="giallo-l"><span> sub_leaves</span><span>[</span><span class="z-constant">2</span><span class="z-keyword"> *</span><span> suffix</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>value</span><span>[</span><span class="z-constant">16</span><span>:</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">little</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> C1</span><span class="z-keyword"> =</span><span> compute_commitment_root</span><span>(</span><span>sub_leaves</span><span>[</span><span>:</span><span class="z-constant">256</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> C2</span><span class="z-keyword"> =</span><span> compute_commitment_root</span><span>(</span><span>sub_leaves</span><span>[</span><span class="z-constant">256</span><span>:</span><span>]</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> compute_commitment_root</span><span>(</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Extension marker</span></span> <span class="giallo-l"><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>stem</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">little</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> group_to_scalar_field</span><span>(</span><span>C1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> group_to_scalar_field</span><span>(</span><span>C2</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> last_epoch</span><span>]</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Added in this EIP</span></span> <span class="giallo-l"><span> [</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> *</span><span class="z-constant"> 251</span><span>)</span></span></code></pre> <p>The following rules are added to tree update operations:</p> <ul> <li>For a read or write event to the tree, check that <code>current_epoch &lt; last_epoch + NUM_ACTIVE_EPOCHS</code>. <ul> <li>If this is <code>true</code>, proceed with the write/read</li> <li>Otherwise, revert.</li> </ul> </li> <li><code>last_epoch</code> is updated with the value of <code>current_epoch</code> each time that a <em>write</em> event is processed for this extension node.</li> </ul> <h3 id="expiry">Expiry</h3> <p>At the start of block processing, before transactions are executed, run <code>check_epoch_end</code>:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> check_epoch_end</span><span>(</span><span class="z-variable z-parameter z-function">block</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> block</span><span>.</span><span>timestamp</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> FORK_TIME</span><span class="z-keyword"> +</span><span> current_epoch</span><span class="z-keyword"> *</span><span class="z-constant"> EPOCH_LENGTH</span><span>:</span></span> <span class="giallo-l"><span> current_epoch</span><span class="z-keyword"> =</span><span> current_epoch</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> schedule_expiry</span><span>(</span><span>current_epoch</span><span class="z-keyword">-</span><span class="z-constant">NUM_ACTIVE_EPOCHS</span><span>)</span></span></code></pre> <p>It is left to client implementers to decide on the behavior of the <code>schedule_expiry</code> function.</p> <p>Data that needs to be kept for the expiry:</p> <ul> <li>the <code>stem</code> value, so that siblings can be inserted</li> <li>The commitment <code>C</code> to the node</li> </ul> <p>That data is referred to as the <em>keepsake</em> for this extension-and-suffix node.</p> <p><strong>Note</strong>: that actual deletion may not happen before the first block in the epoch has finalized, unless there is a way for the client to recover the block in case of a reorg.</p> <h3 id="resurrection">Resurrection</h3> <p>The resurrection transaction is defined as follows:</p> <p><code>RESURRECT_TX_TYPE|ssz(Vector[stem,last_epoch,values])</code></p> <p>Where:</p> <ul> <li><code>stem</code> is used to find the location in the tree, so that the node can be recreated;</li> <li><code>last_epoch</code> and <code>values</code> are the items that were deleted;</li> </ul> <p>At the start of the validation, charge the costs using constants defined in <a href="https://wg-eips.ritovision.com/4762/">EIP-4762</a>:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> resurrect_gas_cost</span><span>(</span><span class="z-variable z-parameter z-function">values</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> WITNESS_BRANCH_COST</span><span class="z-keyword"> +</span><span> </span></span> <span class="giallo-l"><span class="z-constant"> SUBTREE_EDIT_COST</span><span class="z-keyword"> +</span></span> <span class="giallo-l"><span class="z-support"> sum</span><span>(</span><span class="z-constant">WITNESS_CHUNK_COST</span><span class="z-keyword"> +</span><span class="z-constant"> CHUNK_EDIT_COST</span><span class="z-keyword"> +</span><span class="z-constant"> CHUNK_FILL_COST</span><span class="z-keyword"> for</span><span> i</span><span class="z-keyword"> in</span><span> values</span><span>)</span></span></code></pre> <p>Once the gas cost has been paid, the validation process begins:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> validate_subtrees</span><span>(</span><span class="z-variable z-parameter z-function">tree</span><span>,</span><span class="z-variable z-parameter z-function"> tx</span><span>,</span><span class="z-variable z-parameter z-function"> current_epoch</span><span>)</span><span> -&gt;</span><span class="z-support"> bool</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The tx is a SSZ payload</span></span> <span class="giallo-l"><span> subtrees</span><span class="z-keyword"> =</span><span> deserialize_ssz</span><span>(</span><span>tx</span><span>[</span><span class="z-constant">1</span><span>:</span><span>]</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> subtrees</span><span class="z-keyword"> ==</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> false</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Process all subtrees in the transaction</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> subtree</span><span class="z-keyword"> in</span><span> subtrees</span><span>:</span></span> <span class="giallo-l"><span> ok</span><span class="z-keyword"> =</span><span> validate_subtree</span><span>(</span><span>tree</span><span>,</span><span> subtree</span><span>.</span><span>stem</span><span>,</span><span> subtree</span><span>.</span><span>values</span><span>,</span><span> subtree</span><span>.</span><span>last_epoch</span><span>,</span><span> current_epoch</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> ok</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> false</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> validate_subtree</span><span>(</span><span class="z-variable z-parameter z-function">tree</span><span>,</span><span class="z-variable z-parameter z-function"> stem</span><span>,</span><span class="z-variable z-parameter z-function"> values</span><span>,</span><span class="z-variable z-parameter z-function"> last_epoch</span><span>,</span><span class="z-variable z-parameter z-function"> current_epoch</span><span>)</span><span> -&gt;</span><span class="z-support"> bool</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Compute the commitment to the expired</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> tree, get the </span></span> <span class="giallo-l"><span> expired_C</span><span class="z-keyword"> =</span><span> extension_and_suffix_tree</span><span>(</span><span>stem</span><span>,</span><span> values</span><span>,</span><span> last_epoch</span><span>)</span></span> <span class="giallo-l"><span> expired</span><span class="z-keyword"> =</span><span> tree</span><span>.</span><span>get_keepsake</span><span>(</span><span>stem</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> keepsake</span><span>.</span><span>C</span><span class="z-keyword"> !=</span><span> expired_C</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Replace the keepsake with the resurrected</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> extension-and-suffix tree.</span></span> <span class="giallo-l"><span> new_C</span><span class="z-keyword"> =</span><span> extension_and_suffix_tree</span><span>(</span><span>stem</span><span>,</span><span> values</span><span>,</span><span> current_epoch</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> tree</span><span>.</span><span>resurrect_subtree</span><span>(</span><span>stem</span><span>,</span><span> new_C</span><span>,</span><span> values</span><span>,</span><span> current_epoch</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> None</span></span></code></pre> <p>where <code>resurrect_subtree</code> will return <code>None</code> upon success, and an error otherwise.</p> <h2 id="rationale">Rationale</h2> <p>This approach has the benefit of simplicity, over previous proposals for state expiry:</p> <ul> <li>no Address Space Extension (ASE) required</li> <li>it only uses a single tree instead of multiple, per-epoch trees</li> <li>smaller resurrection proofs, as only providing the data is necessary to resurrect.</li> <li>clear gas costs</li> <li>only expire "cold" data, the "hot" data set remains active</li> <li>it is forward-compatible, as ASE or multiple trees are still possible.</li> <li>the exponentiation/addition computation for <code>current_epoch</code> need only be paid once per epoch, which is quickly amortized.</li> </ul> <p>While it's not deleting <em>all</em> the data, it deletes <em>most</em> of it, namely the values and subcommitments, while retaining the ability to easily insert siblings.</p> <p>It is also more expensive than resurrecting a single leaf, which is the cost paid for simplification.</p> <p>The reason why only writes update the resurrection counter, is that any update to the resurrection counter has the effect of a write. Doing so would mean either:</p> <ul> <li>Increasing the cost of a read to that of a write. This would increase the gas costs even more than they did in EIP-4762.</li> <li>Effectively doing a write for the cost of a read. This would both neuter state expiry and possibly add a DOS vector.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is backwards-compatible with verkle, as by default the value for the 4th (index starting at 0) evaluation point is set to <code>0</code> in <a href="https://wg-eips.ritovision.com/6800/">EIP-6800</a>, which is the value of <code>INITIAL_EPOCH_COUNTER</code>.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>TODO</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-06-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Lily Johnsonhttps://github.com/lilyjjo https://wg-eips.ritovision.com/7727/

Enable meta transactions to order other transactions without revert protections.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces two new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction types and one new opcode, enabling smart contracts and transactions to delegate their local sequencing rights to an off-chain entity. These new transaction types work together to create EVM-native 'bundles', which are similar to but weaker than the Proposer-Builder Separation (PBS) bundles offered by builders to searchers.</p> <p>One of the EIP-2718 transactions is an extended normal transaction that supports:</p> <ul> <li>Specifying the entity who can place the transaction in a bundle.</li> <li>An optional block number that the transaction is valid in.</li> </ul> <p>The other EIP-2718 transaction is a 'meta' transaction that does not enter into execution, but rather orders transactions of its own type and the other new type. The 'meta' transaction can also specify an entity allowed to include it in a bundle and a valid block number.</p> <p>The new opcode reveals to the EVM the entity that placed the transaction in a bundle if the transaction was in a bundle.</p> <h2 id="motivation">Motivation</h2> <p>Currently, a single block builder has unrestricted control over the final sequencing of a block’s transactions. This poses a problem, as sequencing—the choice of who gets to interact with specific pieces of state and in what order—significantly influences value flow. The objective of this EIP is to allow more parties to participate in the construction of single blocks by exposing sequencing concepts inside of the EVM. This change would enable EVM applications to reclaim some of the sequencing value that is currently monopolized by block builders, redirecting it back to the applications themselves.</p> <h2 id="specification">Specification</h2> <h3 id="constants">Constants</h3> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td>DELEGATED_TX_TYPE</td><td>0x05</td></tr> <tr><td>BUNDLE_TX_TYPE</td><td>0x06</td></tr> <tr><td>BUNDLE_BASE_GAS_COST</td><td>TBD <!-- TODO --></td></tr> <tr><td>BUNDLE_SIGNER_OPCODE_NUMBER</td><td>TBD <!-- TODO --></td></tr> </tbody></table> <h3 id="new-transaction-payload-types">New Transaction Payload Types</h3> <p>Two new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transactions with types <code>DELEGATED_TX_TYPE</code> and <code>BUNDLE_TX_TYPE</code>.</p> <p>For the <code>DELEGATED_TX_TYPE</code>, the transaction payload should be interpreted as:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-keyword">0x</span><span class="z-constant">05</span><span class="z-keyword"> ||</span><span class="z-entity z-name"> rlp</span><span>(</span><span>[</span></span> <span class="giallo-l"><span class="z-variable z-other"> bundleSigner</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> blockNumber</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> chainId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> nonce</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> gasPrice</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> gasLimit</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> to</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> value</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> data</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> signatureYParity</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> signatureR</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> signatureS</span></span> <span class="giallo-l"><span>]</span><span>)</span></span></code></pre> <p>The <code>signatureYParity</code>, <code>signatureR</code>, <code>signatureS</code> elements of the <code>DELEGATED_TX_TYPE</code> represent a secp256k1 signature over:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-entity z-name">keccak256</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">05</span><span class="z-keyword"> ||</span><span class="z-entity z-name"> rlp</span><span>(</span><span>[</span><span class="z-variable z-other">bundleSigner</span><span>,</span><span class="z-variable z-other"> blockNumber</span><span>,</span><span class="z-variable z-other"> chain_id</span><span>,</span><span class="z-variable z-other"> nonce</span><span>,</span><span class="z-variable z-other"> gasPrice</span><span>,</span><span class="z-variable z-other"> gasLimit</span><span>,</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> value</span><span>,</span><span class="z-variable z-other"> data</span><span>]</span><span>)</span><span>)</span></span></code></pre> <p>For the <code>BUNDLE_TX_TYPE</code>, the transaction payload should be interpreted as:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-keyword">0x</span><span class="z-constant">06</span><span class="z-keyword"> ||</span><span class="z-entity z-name"> rlp</span><span>(</span><span>[</span></span> <span class="giallo-l"><span class="z-variable z-other"> bundleSigner</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> blockNumber</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> chainId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> nonce</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> gasPrice</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> transactionList</span></span> <span class="giallo-l"><span class="z-variable z-other"> signatureYParity</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> signatureR</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> signatureS</span></span> <span class="giallo-l"><span>]</span><span>)</span></span></code></pre> <p>Where the <code>transactionList</code> element is a list of syntactically valid transactions of either type <code>DELEGATED_TX_TYPE</code> or <code>BUNDLE_TX_TYPE</code>. At least one transaction must be in the list.</p> <p>An example would of the <code>transactionList</code> would be:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span class="z-variable z-other"> DELEGATED_TX_TYPE</span><span>.</span><span class="z-variable z-other">payload</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> BUNDLE_TX_TYPE</span><span>.</span><span class="z-variable z-other">payload</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> DELEGATED_TX_TYPE</span><span>.</span><span class="z-variable z-other">payload</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>The <code>signatureYParity</code>, <code>signatureR</code>, <code>signatureS</code> elements of the <code>BUNDLE_TX_TYPE</code> represent a secp256k1 signature over:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-entity z-name">keccak256</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">06</span><span class="z-keyword"> ||</span><span class="z-entity z-name"> rlp</span><span>(</span><span>[</span><span class="z-variable z-other">bundleSigner</span><span>,</span><span class="z-variable z-other"> blockNumber</span><span>,</span><span class="z-variable z-other"> chainId</span><span>,</span><span class="z-variable z-other"> nonce</span><span>,</span><span class="z-variable z-other"> gasPrice</span><span>,</span><span class="z-variable z-other"> transactionList</span><span>]</span><span>)</span><span>)</span></span></code></pre> <p>We’ll refer to address resolved by this signature the bundle transaction’s signer.</p> <h3 id="bundle-signer-opcode"><code>BUNDLE_SIGNER</code> Opcode</h3> <p>The <code>BUNDLE_SIGNER</code> is a new opcode identified by <code>BUNDLE_SIGNER_OPCODE_NUMBER</code> that requires zero stack arguments.</p> <p>When the transaction type is <code>DELEGATED_TX_TYPE</code>, this opcode pushes the <code>bundleSigner</code> from the transaction payload onto the stack as an address. If the transaction is of a different type, it returns the zero address.</p> <p>The gas cost for this opcode is the <code>GAS_VERY_LOW</code> gas constant.</p> <h3 id="transaction-validity-rules">Transaction Validity Rules</h3> <p>For a <code>DELEGATED_TX_TYPE</code> to be valid, the following must be true:</p> <ul> <li>The transaction must be included in a <code>BUNDLE_TX_TYPE</code>'s <code>transactionList</code> to be valid.</li> <li>The transaction’s specified <code>bundleSigner</code> must be equal to the address who signed over the <code>BUNDLE_TX_TYPE</code> that included the transaction in a <code>transactionList</code>.</li> <li>The payload variable <code>blockNumber</code>, if not zero, must be the block number that the transaction is executed in.</li> </ul> <p>For a <code>BUNDLE_TX_TYPE</code> to be valid, the following MUST be true:</p> <ul> <li>All transactions in the <code>transactionList</code> must specify the signer of the <code>BUNDLE_TX_TYPE</code> as the <code>bundleSigner</code>.</li> <li>The transaction must be included in a <code>BUNDLE_TX_TYPE</code>'s <code>transactionList</code> if the <code>bundleSigner</code> payload variable is not the zero address.</li> <li>The payload variable <code>blockNumber</code>, if not zero, must be the block number that the transaction is executed in.</li> </ul> <h3 id="gas-costs">Gas Costs</h3> <p>The <code>BUNDLE_TX_TYPE</code> has a new gas cost formula that changes based on whether the transactions in the <code>transactionList</code> are valid at the time of execution.</p> <p>If a transaction in the <code>transactionList</code> is invalid, the <code>BUNDLE_TX_TYPE</code> transaction is charged as if the invalid transaction's bytes were part of a typical transaction's <code>CALL_DATA</code>. If an inner transaction is valid, there is no cost for its inclusion in the list.</p> <p>The formula is calculated as follows:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-variable z-other">BUNDLE_BASE_GAS_COST</span><span class="z-keyword"> +</span></span> <span class="giallo-l"><span> (</span><span class="z-variable z-other">CALL_DATA_TOKEN_COST</span><span class="z-keyword"> *</span><span class="z-variable z-other"> transaction_list_invalid_tx_byte_length</span><span>)</span></span> <span class="giallo-l"></span></code></pre> <p>At the start of processing, the <code>BUNDLE_TX_TYPE</code>'s signer is charged as if all inner transactions were invalid and is refunded the gas for the valid transactions as each valid transaction finishes execution.</p> <p>The <code>DELEGATED_TX_TYPE</code> follows typical gas costing rules.</p> <h3 id="execution">Execution</h3> <p><code>DELEGATED_TX_TYPE</code> execute normally with the <code>BUNDLE_SIGNER</code> opcode returning the <code>bundleSigner</code> payload variable.</p> <p><code>BUNDLE_TX_TYPE</code> do not start execution contexts. The<code>BUNDLE_TX_TYPE</code>'s <code>NONCE</code> must be incremented before the start of any <code>transactionList</code> execution.</p> <h3 id="receiptpayload-definitions">ReceiptPayload Definitions</h3> <p>For <code>DELEGATED_TX_TYPE</code> transaction that are able to begin execution, their <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> receipt payload should be interpreted as:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-entity z-name">rlp</span><span>(</span><span>[</span><span class="z-variable z-other">status</span><span>,</span><span class="z-variable z-other"> cumulativeGasUsed</span><span>,</span><span class="z-variable z-other"> logsBloom</span><span>,</span><span class="z-variable z-other"> logs</span><span>]</span><span>)</span></span></code></pre> <p><code>DELEGATED_TX_TYPE</code> transactions that are invalid do not get transaction receipts.</p> <p>The <code>BUNDLE_TX_TYPE</code> transaction’s <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> receipt payload should be interpreted as:</p> <pre class="giallo z-code"><code data-lang="go"><span class="giallo-l"><span class="z-entity z-name">rlp</span><span>(</span><span>[</span><span class="z-variable z-other">statusArray</span><span>,</span><span class="z-variable z-other"> cumulativeGasUsed</span><span>]</span><span>)</span></span></code></pre> <p>Where the <code>statusArray</code> is a list of status results for the inner <code>transactionList</code>'s transactions. The list must be the same length as the <code>transactionList</code> and report the statuses in the same order. The status type <code>0x3</code> should be used to report invalid transactions.</p> <p>The <code>cumulateGasUsed</code> is the amount of gas spent by the <code>BUNDLE_TX_TYPE</code>'s signer on the <code>BUNDLE_TX_TYPE</code> transaction costs post <code>CALLDATA</code> refund.</p> <h2 id="rationale">Rationale</h2> <h3 id="allowing-invalid-transactions-to-be-included-in-a-bundle-tx-type-s-transactionlist">Allowing invalid transactions to be included in a <code>BUNDLE_TX_TYPE</code>'s <code>transactionList</code></h3> <p>Knowing how a transaction will execute is challenging without knowing the state root to which the transaction is applied. Creators of <code>BUNDLE_TX_TYPE</code> transactions can only access the previous block’s state root and cannot predict which transactions will precede the <code>BUNDLE_TX_TYPE</code> transaction in the upcoming block's total order. If only valid transactions were permitted, <code>BUNDLE_TX_TYPE</code> transaction lists could be easily invalidated by a single inner transaction attempting to grief the bundle through nonce or gas invalidations.</p> <h3 id="charging-the-bundle-tx-type-s-signer-calldata-gas-costs-for-invalid-transactions">Charging the <code>BUNDLE_TX_TYPE</code>'s signer <code>CALLDATA</code> gas costs for invalid transactions</h3> <p>Blockchains must charge for the work that nodes perform to prevent DoS attacks. Even though invalid transactions in <code>BUNDLE_TX_TYPE</code> transaction lists do not execute, they still occupy block space as bytes and must be paid for by some entity. It is assumed that <code>BUNDLE_TX_TYPE</code> creators will be sophisticated entities capable of simulating the previous block’s state with relative accuracy and able to generate enough profit to offset any invalidation costs incurred.</p> <p>The <code>BUNDLE_BASE_GAS_COST</code> should be set to make the cost of attempting to grief the <code>BUNDLE_TX_TYPE</code> signer more expensive than the cost of the bytes to cover the invalid transaction.</p> <h3 id="requiring-delegated-tx-type-typed-transactions-to-be-included-in-a-bundle-tx-type-s-transactionlist">Requiring <code>DELEGATED_TX_TYPE</code> typed transactions to be included in a <code>BUNDLE_TX_TYPE</code>'s <code>transactionList</code></h3> <p>If <code>DELEGATED_TX_TYPE</code> transactions were able to be executed outside of a <code>BUNDLE_TX_TYPE</code> transaction list, then there would be competition between the <code>BUNDLE_TX_TYPE</code> signer and the total block builder for the right to choose how to locally sequence the transaction. If the <code>DELEGATED_TX_TYPE</code> transaction signer wished to allow the total block builder to choose the local ordering, then the <code>DELEGATED_TX_TYPE</code> transaction type should not be used.</p> <p>The same principle applies to <code>BUNDLE_TX_TYPE</code> transactions. Those that specify a <code>bundleSigner</code> must only be included in a <code>BUNDLE_TX_TYPE</code> list, while those that do not specify a <code>bundleSigner</code> must not be included in such a list.</p> <h3 id="not-allowing-other-transactions-types-to-be-included-in-a-bundle-tx-type-s-transactionlist">Not allowing other transactions types to be included in a <code>BUNDLE_TX_TYPE</code>'s <code>transactionList</code></h3> <p>This restriction was implemented as a precautionary measure and could be reconsidered in the future. Allowing the inclusion of other transaction types that do not specify a <code>bundleSigner</code> into the <code>transactionList</code> could result in multiple searchers attempting to include the same transaction in a bundle. This could potentially create spam within a block.</p> <h3 id="differences-from-pbs-searcher-bundles">Differences from PBS Searcher Bundles</h3> <p>PBS block builders currently offer 'bundles' as a service to searchers in the form of transaction lists that either all execute without reversion or are not included in a block. Searchers typically use these bundles to bid for the right to be the first to interact with a piece of state or to place logic before or after transactions created by non-searcher entities, with back-running and sandwiching being examples. PBS block builders provide this service as a way to gain order flow and increase their block's value.</p> <p>The <code>BUNDLE_TX_TYPE</code> transaction differ in two key ways:</p> <ol> <li>There is no revert protection.</li> <li>Only transactions explicitly delegating to a <code>bundleSigner</code> can be bundled.</li> </ol> <p>These choices were made to prevent DoS attacks on builders and to be compatible with non-PBS block builders running other algorithms.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Block builders are problematic today partly due to their ability to perform censorship and enforce malicious orderings. These concerns persist even when sequencing rights are delegated to a specific entity. The code that generates the off-chain ordering should be public and executed in a trust-minimized manner, such as in a TEE (Trusted Execution Environment) or on a blockchain with faster block times.</p> <p>Similarly, smart contracts that restrict functionality to transactions signed by a specific <code>BUNDLE_SIGNER</code> should provide mechanisms for users to withdraw funds without relying on the delegated sequencing entity to be online or non-malicious. A two-step fund removal process could be implemented to allow safe interaction with bundle construction and simulation logic.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-05-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 dapplionhttps://github.com/dapplion Toni Wahrstätterhttps://github.com/nerolation Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7716/

Adjust penalties for missed attestations based on in-slot correlation of missed attestation

<h2 id="abstract">Abstract</h2> <p>The decentralization of the validator set is one of the most important properties of Ethereum for credible neutrality and censorship resistance. By adjusting penalties to foster decentralization, diversification and fault-tolerance, this EIP proposes to adjust penalties in a way that more diversified entities get lower penalties while entities with high correlations in their setup face more severe ones.</p> <h2 id="motivation">Motivation</h2> <p>As of now, during times of usual network operation, there are no economic incentives to diversify node operations through using multiple different nodes, geographical locations, clients, ISP providers, etc., except for reducing the risk of penalties affecting all validators simultaneously, thereby limiting the impact to only a fraction of them.</p> <p>Attestation penalties are currently agnostic to other participation actions. This proposal scales attestation penalties as a function of other participants' actions. The goal is to decrease the profitability of participants that exhibit correlated behavior.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>PENALTY_ADJUSTMENT_FACTOR</code></td><td><code>4096</code></td></tr> <tr><td><code>MAX_PENALTY_FACTOR</code></td><td><code>4</code></td></tr> </tbody></table> <p>Add a variable <code>NET_EXCESS_PENALTIES</code> to the beacon state.</p> <p>Let <code>penalty_factor</code> be determined through</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>min(</span></span> <span class="giallo-l"><span> (non_attesting_balance * PENALTY_ADJUSTMENT_FACTOR) // (NET_EXCESS_PENALTIES * total_active_balance + 1), </span></span> <span class="giallo-l"><span> MAX_PENALTY_FACTOR</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Let <code>NET_EXCESS_PENALTIES</code> be <code>max(1, NET_EXCESS_PENALTIES + penalty_factor) - 1</code></p> <h2 id="rationale">Rationale</h2> <h3 id="penalty-adjustment-factor">PENALTY_ADJUSTMENT_FACTOR</h3> <p>This variable impacts the sensitivity of the <code>NET_EXCESS_PENALTIES</code>.</p> <p>Given stable participation, the <code>penalty_factor</code> is one. If participation decreases, the <code>penalty_factor</code> will temporarily increase above one until <code>net_excess_penalties</code> catches up. If participation increases, the <code>penalty_factor</code> will temporarily be zero until <code>net_excess_penalties</code> catches up.</p> <p>The <code>PENALTY_ADJUSTMENT_FACTOR</code> regulates how fast <code>net_excess_penalties</code> catches up. In other words, the <code>PENALTY_ADJUSTMENT_FACTOR</code> determines the frequency that the penalty_factor is not one.</p> <p>A high <code>PENALTY_ADJUSTMENT_FACTOR</code> causes the <code>net_excess_penalties</code> to adjust slower. A low <code>PENALTY_ADJUSTMENT_FACTOR</code> causes the <code>net_excess_penalties</code> to react more sensitively to changes in participation.</p> <h3 id="max-penalty-factor"><code>MAX_PENALTY_FACTOR</code></h3> <p>The <code>MAX_PENALTY_FACTOR</code> puts a ceiling onto the maximum factor with which the penalty for missed attestations is scaled to prevent overly harsh punishments.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible adjustment of attestations rewards and penalties that requires a scheduled network upgrade.</p> <h2 id="security-considerations">Security Considerations</h2> <p>We acknowledge that splitting validator views can be leveraged as an attack to increase the <code>penalty_factor</code> for validators of consecutive slots with little risk for the proposer. TBD.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-05-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Francisco Giordanohttps://github.com/frangio https://wg-eips.ritovision.com/7713/

A mechanism for EIP-712 messages to contain parameters of arbitrary type

<h2 id="abstract">Abstract</h2> <p>This EIP defines a new type <code>box</code> for use in <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> messages. A <code>box</code> value is a value of an arbitrary struct type whose underlying type is encapsulated and hidden from the outer struct but transparent and type-checkable by the wallet, and thus able to be fully inspected by the user prior to signing. A verifying contract can be made agnostic to the underlying type of a <code>box</code> value, but this type is not erased and can be verified on-chain if necessary.</p> <h2 id="motivation">Motivation</h2> <p>EIP-712 signatures have become a widely used primitive for users to express and authorize intents off-chain. Wide-ranging applications are able to define parameterized messages for users to sign in their wallet through a general-purpose interface that clearly surfaces the type, parameters, and domain of authorization. This crucially applies to hardware wallets as a last line of defense.</p> <p>The general-purpose nature of EIP-712 is key to its success, but in addition wallets are able to develop special-purpose interfaces and capabilities for specific types of messages as they become more widely used. For example, <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> Permits are a well-known EIP-712 message that wallets display to the user in a special way that clearly surfaces the known implications and risks of signing.</p> <p>Special-purpose interfaces improve usability and security for the user, but rely on standardized message types such as Permits. This EIP concerns the ability to standardize messages that contain within them parameters of arbitrary type.</p> <p>A recent example is found in <a href="https://wg-eips.ritovision.com/7683/">ERC-7683</a>, which defines a struct with the following member:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Arbitrary implementation-specific data</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Can be used to define tokens, amounts, destination chains, fees, settlement parameters,</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> or any other order-type specific information</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span> orderData</span><span>;</span></span></code></pre> <p>Defining this parameter with type <code>bytes</code> enables the message to contain data of arbitrary type and is sufficient to bind the signature to implementation-specific data, but it amounts to type erasure. As a consequence, the user will be presented with an opaque bytestring in hexadecimal format in the wallet's signing interface. This negates the benefit of using EIP-712 signatures because the true contents of the parameter are invisible to the wallet's general-purpose interface.</p> <p>Another example is found in recent efforts to make <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> signatures secure against replay. Achieving this without making the message contents opaque to the signer requires embedding an application's EIP-712 message inside an outer message that binds it to a specific account. The type of the outer message depends on the type of the inner message, and making the type reproducible by the smart contract account on-chain for verification requires an inefficient scheme to communicate the string-encoded type of the inner message as a part of the signature.</p> <p>Both of these use cases would benefit from the ability to define EIP-712 struct parameters of arbitrary type in such a way that the verifying contract can be agnostic to the type of the parameter's value in a message while the wallet retains the ability to transparently display it to the user for inspection.</p> <h2 id="specification">Specification</h2> <p>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>EIP-712 is extended as follows:</p> <h3 id="typed-structured-data">Typed structured data</h3> <p>A struct type may contain a <em>boxed member</em> by declaring it with type <code>box</code>. Example:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Envelope</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> account</span><span>;</span></span> <span class="giallo-l"><span> box contents</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A boxed member has an underlying <em>unboxed type</em>, which is an arbitrary struct type and may be different in each message.</p> <h3 id="encodetype"><code>encodeType</code></h3> <p>A boxed member is encoded as <code>"box " || name</code>. For example, the above <code>Envelope</code> struct is encoded as <code>Envelope(address account,box contents)</code>.</p> <h3 id="encodedata"><code>encodeData</code></h3> <p>A boxed value is encoded as its underlying <em>unboxed value</em>, i.e., <code>hashStruct(value) = keccak256(typeHash, encodeData(value))</code> where <code>typeHash</code> corresponds to the unboxed type and <code>encodeData</code> is operating on a value of that type.</p> <h3 id="signtypeddata-schema"><code>signTypedData</code> schema</h3> <p>A signature request for an EIP-712 message that involves a boxed member shall include the unboxed type as a part of the message object. A boxed value must be an object with properties <code>value</code>, <code>primaryType</code>, and <code>types</code>. The <code>value</code> shall be type-checked and encoded according to <code>primaryType</code> and <code>types</code>, analogously to an EIP-712 message (though without the <code>\x19</code> prefix). The <code>types</code> defined in the message outside of the boxed value shall not be in scope for the encoding of a boxed value.</p> <p>For example, a message for the <code>Envelope</code> type above may be represented as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> domain</span><span>:</span><span class="z-keyword"> ...</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> primaryType</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Envelope</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> types</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> Envelope</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">account</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&#39;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">contents</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">box</span><span class="z-punctuation z-definition z-string">&#39;</span><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> message</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> account</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x...</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> contents</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> primaryType</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Mail</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> types</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> Mail</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">greeting</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&#39;</span><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> value</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> greeting</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Hello world</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="json-schema-of-a-boxed-value">JSON Schema of a boxed value</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> properties</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> value</span><span>:</span><span> {</span><span class="z-entity z-name">type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&#39;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> primaryType</span><span>:</span><span> {</span><span class="z-entity z-name">type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&#39;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> types</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> additionalProperties</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">array</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> items</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> properties</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> name</span><span>:</span><span> {</span><span class="z-entity z-name">type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&#39;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> type</span><span>:</span><span> {</span><span class="z-entity z-name">type</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&#39;</span><span>}</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> required</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> required</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">value</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">primaryType</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">types</span><span class="z-punctuation z-definition z-string">&#39;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>TBD <!-- TODO --></p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion. <!-- TODO --></p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-05-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Tomasz Stanczakhttps://github.com/tkstanczak Guillaume Ballethttps://github.com/gballet Gajinder Singhhttps://github.com/g11tech Tanishq Jasoriahttps://github.com/tanishqjasoria Ignacio Hagopianhttps://github.com/jsign Jochem Brouwerhttps://github.com/jochem-brouwer Gabriel Rocheleauhttps://github.com/gabrocheleau https://wg-eips.ritovision.com/7709/

Read the `BLOCKHASH (0x40)` opcode from the EIP-2935 system contract storage and adjust its gas cost to reflect storage access.

<h2 id="abstract">Abstract</h2> <p>Update the <code>BLOCKHASH (0x40)</code> opcode to read and serve from the system contract storage and charge the <strong>additional</strong> (cold or warm) storage costs.</p> <h2 id="motivation">Motivation</h2> <p>The <code>BLOCKHASH (0x40)</code> opcode currently assumes that the client has knowledge of the previous blocks, which in Verkle <a href="https://wg-eips.ritovision.com/6800/">EIP-6800</a> would prevent stateless execution. However with <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> blockhashes can be retrieved and served from its system contract storage which allows Verkle blocks to include a storage access witness for stateless execution.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_TIMESTAMP</code></td><td>TBD</td></tr> <tr><td><code>HISTORY_STORAGE_ADDRESS</code></td><td><code>0x0000F90827F1C53a10cb7A02335B175320002935</code></td></tr> <tr><td><code>BLOCKHASH_SERVE_WINDOW</code></td><td><code>256</code></td></tr> </tbody></table> <p>The <code>BLOCKHASH</code> opcode semantics remains the same as before. From the <code>fork_block</code> (defined as <code>fork_block.timestamp &gt;= FORK_TIMESTAMP and fork_block.parent.timestamp &lt; FORK_TIMESTAMP</code>), the <code>BLOCKHASH</code> instruction should be updated to resolve block hash in the following manner:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> resolve_blockhash</span><span>(</span><span class="z-variable z-parameter z-function">block</span><span>:</span><span> Block</span><span>,</span><span class="z-variable z-parameter z-function"> state</span><span>:</span><span> State</span><span>,</span><span class="z-variable z-parameter z-function"> arg</span><span>:</span><span> uint64</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> note that outside the BLOCKHASH_SERVE_WINDOW we continue to return 0</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> despite the 2935 history contract being able to serve more hashes</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> arg</span><span class="z-keyword"> &gt;=</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> or</span><span> (</span><span>arg</span><span class="z-keyword"> +</span><span class="z-constant"> BLOCKHASH_SERVE_WINDOW</span><span>)</span><span class="z-keyword"> &lt;</span><span> block</span><span>.</span><span>number</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> performs an sload on arg % HISTORY_SERVE_WINDOW including gas charges,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> warming effects as well as execution accesses</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> note that the `BLOCKHASH_SERVE_WINDOW` and the 2935 ring buffer window</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> `HISTORY_SERVE_WINDOW` for slot calculation are different</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> state</span><span>.</span><span>load_slot</span><span>(</span><span class="z-constant">HISTORY_STORAGE_ADDRESS</span><span>,</span><span> arg</span><span class="z-keyword"> %</span><span class="z-constant"> HISTORY_SERVE_WINDOW</span><span>)</span></span></code></pre> <p>ONLY if the <code>arg</code> is within the correct <code>BLOCKHASH</code> window, clients can choose to either</p> <ul> <li>do a direct <code>SLOAD</code> from state, or</li> <li>do a system call to <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> contract via its <code>get</code> mechanism (caller other than <code>SYSTEM_ADDRESS</code>) or</li> <li>serve from memory or as per current designs if maintaining requisite history (full clients for e.g.)</li> </ul> <p>However the entire semantics and after effects of the <code>SLOAD</code> operation needs to be applied as per the current fork if the <code>arg</code> is within the correct <code>BLOCKHASH</code> window:</p> <ul> <li><code>SLOAD</code> gas costs (cold or warm) for the <code>arg % HISTORY_SERVE_WINDOW</code> slot.</li> <li><code>SLOAD</code> after effects on the slot (warming the slot)</li> <li><code>SLOAD</code> accesses added to execution witnesses if Verkle (<a href="https://wg-eips.ritovision.com/6800/">EIP-6800</a> and <a href="https://wg-eips.ritovision.com/4762/">EIP-4762</a>) is activated</li> </ul> <h3 id="activation">Activation</h3> <p>This EIP specifies the transition to the new logic assuming that <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> has been activated:</p> <ul> <li>sufficiently ahead of this EIP's activation (&gt;= <code>BLOCKHASH_SERVE_WINDOW</code>) or</li> <li>at genesis for testnets/devnets where this EIP could also be activated at genesis</li> </ul> <p>The current proposal is to activate this EIP with Verkle to allow for stateless execution of the block.</p> <h3 id="gas-costs">Gas costs</h3> <p>As described above, if the <code>arg</code> to be resolved is within the correct window, the corresponding <code>SLOAD</code> charges and accesses are to be applied for the slot <code>arg % HISTORY_SERVE_WINDOW</code>. Note that the <code>HISTORY_SERVE_WINDOW</code> and <code>BLOCKHASH_SERVE_WINDOW</code> are different.</p> <h3 id="reading-from-the-system-contract">Reading from the System contract</h3> <p>Even if the clients choose to resolve <code>BLOCKHASH</code> through system call to <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> contract, the gas cost for the system code execution (and also the code witnesses if Verkle activated) is not applied. Only the effect of <code>SLOAD</code> is applied as described above.</p> <h2 id="rationale">Rationale</h2> <ul> <li>The reason behind the updated gas cost is to match the real operation, which is equivalent to an <code>SLOAD</code>.</li> <li>The <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> system contract execution charges (and accesses) are not applied to keep the gas low and to keep things simple for clients which choose to resolve <code>BLOCKHASH</code> in other ways (directly or though memory/maintained history)</li> </ul> <p>Note that <code>BLOCKHASH</code> opcode only serves a limited <code>BLOCKHASH_SERVE_WINDOW</code> to be backward compatible (and to not extend the above exemptions). For deeper accesses one will need to directly call <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> system contract which will lead to a normal contract execution (as well as charges and accesses)</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a significant increase in the cost of <code>BLOCKHASH</code>, which could break use-cases that rely on the previous gas cost. Also, this EIP introduces a breaking change in the case where less than <code>BLOCKHASH_SERVE_WINDOW</code> elapse between the <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> fork and this EIP's fork (unless <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> is activated in genesis for e.g. in testnets/devnets) as the <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> system contract would not have saved the required history.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li>If <code>BLOCKHASH</code> is not called or there is no <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> contract call by any transaction, only the <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> system update of the parent hash shows up in witnesses if Verkle is activated.</li> <li>If <code>BLOCKHASH</code> is called, there MUST be a storage access gas charge (and corresponding access witness if Verkle is activated) for the storage slot but ONLY if the <code>BLOCKHASH</code> query is for the last <code>BLOCKHASH_SERVE_WINDOW</code> ancestors. This is irrespective of how the client chooses to resolve the <code>BLOCKHASH</code> (directly, via system contract or via memory)</li> <li>The gas cost for each <code>BLOCKHASH</code> operation should still be charged, in addition to the <code>SLOAD</code> cost of each lookup (if performed)</li> <li>If the <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> contract is called directly (i.e. not through <code>BLOCKHASH</code>), then the witness and gas costs (including those related to contract code) are applied as per normal contract execution of the current fork.</li> <li><code>BLOCKHASH</code> should be consistently resolved if this EIP is activated correctly <code>&gt;= BLOCKHASH_SERVE_WINDOW</code> after <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>No security considerations other than the ones contained in <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a> are determined as of now.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-05-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7706/

Create a separate basefee and gaslimit for calldata

<h2 id="abstract">Abstract</h2> <p>Add a new type of gas for transaction calldata. Add a new transaction type that provides <code>max_basefee</code> and <code>priority_fee</code> as a vector, providing values for execution gas, blob gas and calldata gas. Modify the basefee adjustment to use the same mechanism for the three types of gas.</p> <h2 id="motivation">Motivation</h2> <p>A major argument against raising the Ethereum gas limit, making calldata cheaper, or increasing the <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> blob count before technologies like PeerDAS become available, is that the theoretical maximum size of an Ethereum block is already too large, and we cannot afford to increase it further. However, there is an inefficiency here: the current average size of a block (not including blobs) is ~100 kB, and the theoretical max is <code>30,000,000 / 16 = 1,875,000</code> bytes (one could make larger blocks using zero bytes, but in practice zero-byte-heavy blocks would be compressed to less than 1.87 million bytes due to snappy compression). Ideally, we would have a way to bound the maximum, without making calldata more scarce <em>on average</em>.</p> <p>This EIP does exactly this, by adopting the same technique that was applied for blob data in EIP-4844: we introduce a separate fee market for calldata, with a separate basefee and a separate per-block gas limit. The theoretical max calldata size of a block would be greatly reduced, while basic economic analysis suggests that <em>on average</em>, calldata would become considerably cheaper.</p> <p>The EIP also introduces a new transaction type which includes the three types of max-basefees and priority fees as a vector, allowing the same code paths to handle all three types of gas. We also make the basefee adjustment, which currently uses separate mechanisms for execution gas (introduced in <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>) and blobs (introduced in EIP-4844), use the same approach for all three types of gas. This simplifies the basefee adjustment rules, and ensures that the stronger mathematical properties of the newer EIP-4844 basefee adjustment algorithm cover all three types of gas.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="parameters">Parameters</h3> <ul> <li><code>FORK_BLKNUM</code> = <code>TBD</code></li> <li><code>NEW_TX_TYPE</code> = <code>TBD</code></li> <li><code>CALLDATA_GAS_PER_TOKEN</code> = <code>4</code></li> <li><code>TOKENS_PER_NONZERO_BYTE</code> = <code>4</code></li> <li><code>CALLDATA_GAS_LIMIT_RATIO</code> = <code>4</code></li> <li><code>LIMIT_TARGET_RATIOS = [2, 2, 4]</code></li> <li><code>MIN_BASE_FEE_PER_GAS = 1</code> # Rename of EIP-4844 MIN_BASE_FEE_PER_BLOB_GAS</li> <li><code>BASE_FEE_UPDATE_FRACTION = 8</code> # Roughly matches EIP-4844 parameters</li> </ul> <h3 id="new-transaction-type">New transaction type</h3> <p>As of <code>FORK_BLOCK_NUMBER</code>, a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction is introduced with <code>TransactionType</code> = <code>TX_TYPE(NEW_TX_TYPE)</code>.</p> <p>The <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>TransactionPayload</code> for this transaction is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[chain_id, nonce, gas_limit, to, value, data, access_list, blob_versioned_hashes, max_fees_per_gas, priority_fees_per_gas, y_parity, r, s]</span></span></code></pre> <p>We require <code>max_fees_per_gas</code> and <code>priority_fees_per_gas</code> to be length-3 vectors, each of which contain integers from <code>0</code> to <code>2**64-1</code>.</p> <p>The intrinsic cost of the new transaction is inherited from EIP-4844, except that the calldata gas cost (16 per nonzero byte, 4 per zero byte) is removed.</p> <h3 id="block-processing-and-transaction-fees">Block processing and transaction fees</h3> <p>We add the functions <code>get_max_fees</code> and <code>get_priority_fees</code>, to compute these length-3 vectors for previous transaction types:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_max_fees(tx: Transaction) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> if tx.type == NEW_TX_TYPE:</span></span> <span class="giallo-l"><span> return tx.max_fees_per_gas</span></span> <span class="giallo-l"><span> elif tx.type == BLOB_TX_TYPE:</span></span> <span class="giallo-l"><span> return [tx.max_fee_per_gas, tx.max_fee_per_blob_gas, tx.max_fee_per_gas]</span></span> <span class="giallo-l"><span> elif is_eip_1559(tx.type):</span></span> <span class="giallo-l"><span> return [tx.max_fee_per_gas, 0, tx.max_fee_per_gas]</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> return [tx.gasprice, 0, tx.gasprice]</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_priority_fees(tx: Transaction) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> if tx.type == NEW_TX_TYPE:</span></span> <span class="giallo-l"><span> return tx.priority_fees_per_gas</span></span> <span class="giallo-l"><span> elif tx.type == BLOB_TX_TYPE:</span></span> <span class="giallo-l"><span> return [tx.max_priority_fee_per_gas, 0, tx.max_priority_fee_per_gas]</span></span> <span class="giallo-l"><span> elif is_eip_1559(tx.type):</span></span> <span class="giallo-l"><span> return [tx.max_priority_fee_per_gas, 0, tx.max_priority_fee_per_gas]</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> return [tx.gasprice, 0, tx.gasprice]</span></span></code></pre> <p>We also add some helpers:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def all_less_or_equal(v1: [int, int, int], v2: [int, int, int]) -&gt; bool:</span></span> <span class="giallo-l"><span> return all(x &lt;= y for x, y in zip(v1, v2))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def vector_add(v1: [int, int, int], v2: [int, int, int]) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> return [x+y for x, y in zip(v1, v2)]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def vector_subtract(v1: [int, int, int], v2: [int, int, int]) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> return [x-y for x, y in zip(v1, v2)]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def vector_subtract_clamp_at_zero(v1: [int, int, int], v2: [int, int, int]) -&gt; [uint, uint, uint]:</span></span> <span class="giallo-l"><span> return [x-y if x &gt;= y else 0 for x, y in zip(v1, v2)]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def vector_mul(v1: [int, int, int], v2: [int, int, int]) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> return [x*y for x, y in zip(v1, v2)]</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># Same rules as current calldata pricing, but rephrased (similar language to EIP-7623)</span></span> <span class="giallo-l"><span>def get_calldata_gas(calldata: bytes) -&gt; int:</span></span> <span class="giallo-l"><span> tokens = calldata.count(0) + (len(calldata) - calldata.count(0)) * TOKENS_PER_NONZERO_BYTE</span></span> <span class="giallo-l"><span> return tokens * CALLDATA_GAS_PER_TOKEN</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_gaslimits(tx: Transaction) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> if tx.type == NEW_TX_TYPE:</span></span> <span class="giallo-l"><span> return [tx.gaslimit, len(tx.blob_versioned_hashes) * GAS_PER_BLOB, get_calldata_gas(tx.data)]</span></span> <span class="giallo-l"><span> elif tx.type == BLOB_TX_TYPE:</span></span> <span class="giallo-l"><span> return [tx.gaslimit, len(tx.blob_versioned_hashes) * GAS_PER_BLOB, get_calldata_gas(tx.data)]</span></span> <span class="giallo-l"><span> elif is_eip_1559(tx.type):</span></span> <span class="giallo-l"><span> return [tx.gaslimit, 0, get_calldata_gas(tx.data)]</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> return [tx.gaslimit, 0, get_calldata_gas(tx.data)]</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_fees_per_gas(tx: Transaction, block_basefees: [int, int, int]) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> max_fees = get_max_fees(tx)</span></span> <span class="giallo-l"><span> priority_fees = get_priority_fees(tx)</span></span> <span class="giallo-l"><span> output = []</span></span> <span class="giallo-l"><span> # Fee sufficiency check, similar to EIP-1559 and 4844</span></span> <span class="giallo-l"><span> require(all_less_or_equal(block_basefees, max_fees))</span></span> <span class="giallo-l"><span> # Similar logic to EIP-1559 and 4844</span></span> <span class="giallo-l"><span> return [</span></span> <span class="giallo-l"><span> min(basefee + priority_fee, max_fee)</span></span> <span class="giallo-l"><span> for block_basefee, max_fee, priority_fee in zip(block_basefees, max_fees, priority_fees)</span></span> <span class="giallo-l"><span> ]</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>get_block_gaslimits(block: Block) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> return [block.gaslimit, MAX_BLOB_GAS_PER_BLOCK, block.gaslimit // CALLDATA_GAS_LIMIT_RATIO]</span></span></code></pre> <p><strong>At the start of block processing</strong>:</p> <ul> <li>We initialize a vector <code>gas_used_so_far</code> to <code>[0, 0, 0]</code></li> </ul> <p><strong>At the start of processing a transaction</strong>:</p> <ul> <li>Compute <code>fees_per_gas = get_fees_per_gas(tx, get_block_basefees(block))</code> and <code>tx_gaslimits = get_gaslimits(tx)</code></li> <li>Check that <code>all_less_or_equal(vector_add(gas_used_so_far, tx_gaslimits), block.gas_limits)</code></li> <li>Deduct <code>sum(vector_mul(fees_per_gas, tx_gaslimits))</code> wei from the <code>tx.origin</code> account</li> </ul> <p>Note that <code>get_block_basefees(block)</code> is not yet defined, we will define it in the section below. The <code>block.gas_limits</code> field is also defined in the section below.</p> <p><strong>At the end of processing a transaction</strong>:</p> <ul> <li>Compute <code>tx_gas_consumed</code> as a three item vector, where the first item is the amount of gas actually consumed by the transaction execution, and the second and third match the values in <code>get_gaslimits(tx)</code></li> <li>Refund <code>sum(vector_mul(fees_per_gas, vector_sub(tx_gaslimits, tx_gas_consumed)))</code> to the <code>tx.origin</code> account (in practice, only the first term will be nonzero for now)</li> <li>Set <code>gas_used_so_far = vector_add(gas_used_so_far, tx_gas_consumed)</code></li> </ul> <p><strong>At the end of processing a block</strong>:</p> <ul> <li>Require <code>block.gas_used = gas_used_so_far</code></li> </ul> <p>The <code>block.gas_used</code> field will be defined in the section below.</p> <h3 id="block-structure">Block structure:</h3> <p>We update <code>BlockHeader</code> field, to remove the <code>blob_gas_used</code>, <code>gas_used</code>, <code>base_fee_per_gas</code>, <code>gas_limit</code> and <code>excess_blob_gas</code> fields, and we add new fields, all of the <code>[int, int, int]</code> type: <code>gas_limits</code>, <code>gas_used</code>, <code>excess_gas</code>. The resulting RLP encoding becomes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>rlp([</span></span> <span class="giallo-l"><span> parent_hash,</span></span> <span class="giallo-l"><span> 0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347, # ommers hash</span></span> <span class="giallo-l"><span> coinbase,</span></span> <span class="giallo-l"><span> state_root,</span></span> <span class="giallo-l"><span> txs_root,</span></span> <span class="giallo-l"><span> receipts_root,</span></span> <span class="giallo-l"><span> logs_bloom,</span></span> <span class="giallo-l"><span> 0, # difficulty</span></span> <span class="giallo-l"><span> number,</span></span> <span class="giallo-l"><span> timestamp,</span></span> <span class="giallo-l"><span> extradata,</span></span> <span class="giallo-l"><span> prev_randao,</span></span> <span class="giallo-l"><span> 0x0000000000000000, # nonce</span></span> <span class="giallo-l"><span> withdrawals_root,</span></span> <span class="giallo-l"><span> gas_limits,</span></span> <span class="giallo-l"><span> gas_used,</span></span> <span class="giallo-l"><span> excess_gas</span></span> <span class="giallo-l"><span>])</span></span></code></pre> <p>We define:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>get_block_gas_targets(parent: Header) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> return [limit // target_ratio for limit, target_ratio in zip(parent.gas_limits, LIMIT_TARGET_RATIOS)]</span></span></code></pre> <p>We calculate the required <code>excess_gas</code> values as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def calc_excess_gas(parent: Header) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> return vector_subtract_clamp_at_zero(vector_add(parent_excess, parent_used), get_block_gas_targets(parent))</span></span></code></pre> <p>We calculate the required <code>gas_limits</code> as follows:</p> <ul> <li><code>gas_limits[0]</code> must follow the existing adjustment formula</li> <li><code>gas_limits[1]</code> must equal <code>MAX_BLOB_GAS_PER_BLOCK</code></li> <li><code>gas_limits[2]</code> must equal <code>gas_limits[0] // CALLDATA_GAS_LIMIT_RATIO</code></li> </ul> <p>Now, we define <code>get_block_basefees</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_block_basefees(parent: Header) -&gt; [int, int, int]:</span></span> <span class="giallo-l"><span> return [</span></span> <span class="giallo-l"><span> fake_exponential(</span></span> <span class="giallo-l"><span> MIN_BASE_FEE_PER_GAS,</span></span> <span class="giallo-l"><span> excess_gas,</span></span> <span class="giallo-l"><span> target * BASE_FEE_UPDATE_FRACTION</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> for (excess_gas, target) in zip(parent.excess_gas, get_block_gas_targets(parent))</span></span> <span class="giallo-l"><span> ]</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="conversion-of-all-gas-related-mechanics-into-vectors">Conversion of all gas-related mechanics into vectors</h3> <p>This allows the same logic that is used for handling gas to handle all three types of gas. As a result, it's arguably a net simplification of protocol gas handling logic, despite the fact that the total number of gas types increases from 2 to 3</p> <h3 id="target-ratios">Target ratios</h3> <p>The target ratios for execution gas and blobs are set to 2; the target ratio for calldata is set to 4. This greatly decreases the number of scenarios in which calldata actually hits the limit, which mitigates economic impact of the EIP, because analysis of EIP-1559-style fee markets is much simpler in "under-the-limit" conditions than in "at-the-limit" conditions. Additionally, it reduces the risk that applications requiring large calldata will outright stop working.</p> <p>The current parameters set the target calldata per block to 187,500 bytes, about 2x the current average. Using basic supply-and-demand reasoning, this implies that calldata is likely to become significantly cheaper as a result of this EIP.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Previous transaction types set the calldata basefee and priority fee to equal each other. The calldata gas costs were intentionally set to be identical to today, and the gas target similar to present-day usage, so that setting the two fees to be equal each other is a reasonable approximation to optimal behavior. In practice, the new transaction type would be superior, so we expect users to switch to it over time. However, the loss suffered by old-style transaction users would not be that high, because priority fees are generally small compared to basefees, and the amount that a user pays is proportional to the basefee.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Optimal block building behavior becomes more complex as a result of this EIP, particularly under the boundary conditions when blocks are full of one or both types of gas. We argue that the effects of this are not too large, because in practice over 90% of blocks are under-full, and naive "greedy algorithms" can get a close-enough-to-optimal outcome. The centralization risks of proprietary block-building algorithms are thus likely to be much smaller than other existing risks with eg. MEV extraction.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-05-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ben Adamshttps://github.com/benaadams Oleg Iakushkinhttps://github.com/OlegJakushkin https://wg-eips.ritovision.com/7707/

This EIP proposes updating gas cost parameters for access lists to incentivise their use and improve transaction execution efficiency.

<h2 id="abstract">Abstract</h2> <p>This EIP reduces the gas cost of access list data, incentivizing the inclusion of complete and valid access lists in transactions to improve data load efficiency for execution layer clients.</p> <h2 id="motivation">Motivation</h2> <p>While <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> introduced <code>accessLists</code> as a mechanism for <code>SLOAD</code> pre-warming to reduce gas costs by informing the EVM upfront about which storage slots a transaction will access, the practical use is limited and uncommon due to the savings versus penalties involved. In order to break even for each address included <code>24 storage keys</code> are required per address, and there is a <code>100 gas</code> saving per key at <code>25+</code>; in contrast the penalty for including an unused key is <code>1900 gas</code>, so break-even where one key is unused is <code>43 keys</code>.</p> <p>This situation makes the break-even and risk-reward ratio of <code>accessLists</code> rarely appealing in practice for regular transactions, where a prior transaction could lead to a different branch being taken and a slightly different set of storage slots being accessed. Furthermore, a very high number of SLOADs is required to start breaking even.</p> <p>For some clients, data loading takes <code>&gt;70%</code> of block execution time. This happens in part due to sequential transaction execution and iterative search of effectively random access data.</p> <p>While NVMe drives have massive throughput and IOPS; this is their concurrent throughput operated through multiple queues and they do not have this performance if data is accessed completely sequentially with one request waiting for the prior to complete i.e. stacking individual IOPS latency end to end will not give anything close to maximal throughput that these drives can deliver (which is different from the HDD world where heads needed to seek to different physical locations for each read). This is a similar situation with network attached storage or cloud data disks; however the latency here is even more amplified than a local direct CPU attached NVMe drive (i.e. via network card).</p> <p>If nodes had a somewhat clearer picture of what data to pre-load for the block's execution; that can be done in parallel, hiding much of the latency from accessing that data when discovered from executing the transaction. Very much in a similar way to instruction pipelining on a CPU hiding memory access latencies; the data access for transactions could be pipelined. This can lead to faster/cheaper block execution and would facilitate data dependency hints for parallel Tx execution in the future, like on other emerging chains that were developed with more modern hardware in mind.</p> <h2 id="specification">Specification</h2> <p>We shall update <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> parameters:</p> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>ACCESS_LIST_STORAGE_KEY_COST</code></td><td>320</td></tr> <tr><td><code>ACCESS_LIST_ADDRESS_COST</code></td><td>512</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>As stated in the introduction the gas cost benefit analysis does not encourage the users of the chain to provide accessList hints, even though the mechanism is already in protocol (and a call to <code>eth_createAccessList</code> will give them, or a wallet the correct list to include). So we propose a reduction in the pricing of those data access lists to make them more inline with calldata.</p> <p>Levelling the playing field between small <code>call_data</code> and <code>access_lists</code> costs, (and incentivise <code>access_lists</code> provisioning from transaction senders as they are needed for transaction execution in a faster manner), the price model updates would look as follows:</p> <p>Use <code>STANDARD_TOKEN_COST * tokens_in_access_lists</code>, where <code>tokens_in_access_lists = bytes_in_access_lists * 4</code>, making it as expensive to send as plain small call data. So we will get:</p> <ul> <li> <p><code>32*4*4 = 512</code> for addresses (instead of 2400, 4.6 times less)</p> </li> <li> <p><code>20*4*4 = 320</code> for storage keys (instead of 1900, 5.9 times less)</p> </li> </ul> <p>This means users pay for on-chain data inclusion as usual <code>call_data</code>. It changes the original <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> logic of "covering the bandwidth costs", which was not described in detail and is potentially outdated.</p> <p>It should be noted that this is not the first time <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> additions have been proposed. In <a href="https://wg-eips.ritovision.com/3521/">EIP-3521</a>, a reduction was already proposed, but it focused only on <code>ACCESS_LIST_ADDRESS_COST</code>.</p> <h3 id="examples">Examples</h3> <p>Current</p> <table><thead><tr><th>Inst</th><th>Type</th><th>Access List</th><th>Keys for address</th><th>OP Price</th><th>AccessList Key Price</th><th>AccessList Address Price</th><th>Total gas per OP</th></tr></thead><tbody> <tr><td><code>SLOAD</code></td><td>Cold</td><td>Not included</td><td>-</td><td>2100</td><td>0</td><td>0</td><td>2100</td></tr> <tr><td><code>SLOAD</code></td><td>Warm</td><td>Not included</td><td>-</td><td>100</td><td>0</td><td>0</td><td>100</td></tr> <tr><td><code>SLOAD</code></td><td>Warm</td><td>Included</td><td>-</td><td>100</td><td>-</td><td>-</td><td>100</td></tr> <tr><td><code>SLOAD</code></td><td>Cold</td><td>Included</td><td>1</td><td>100</td><td>1900</td><td>2400</td><td>4400</td></tr> <tr><td><code>SLOAD</code></td><td>None</td><td>Included</td><td>1</td><td>0</td><td>1900</td><td>2400</td><td>4300</td></tr> <tr><td><code>SLOAD</code></td><td>Cold</td><td>Included</td><td>10</td><td>100</td><td>1900</td><td>240</td><td>2240</td></tr> <tr><td><code>SLOAD</code></td><td>None</td><td>Included</td><td>10</td><td>0</td><td>1900</td><td>240</td><td>2140</td></tr> <tr><td><code>SLOAD</code></td><td>Cold</td><td>Included</td><td>50</td><td>100</td><td>1900</td><td>48</td><td>2048</td></tr> <tr><td><code>SLOAD</code></td><td>None</td><td>Included</td><td>50</td><td>0</td><td>1900</td><td>48</td><td>1948</td></tr> </tbody></table> <p>Proposed</p> <table><thead><tr><th>Inst</th><th>Type</th><th>Access List</th><th>Keys for address</th><th>OP Price</th><th>AccessList Key Price</th><th>AccessList Address Price</th><th>Total gas per OP</th></tr></thead><tbody> <tr><td><code>SLOAD</code></td><td>Cold</td><td>Not included</td><td>-</td><td>2100</td><td>0</td><td>0</td><td>2100</td></tr> <tr><td><code>SLOAD</code></td><td>Warm</td><td>Not included</td><td>-</td><td>100</td><td>0</td><td>0</td><td>100</td></tr> <tr><td><code>SLOAD</code></td><td>Warm</td><td>Included</td><td>-</td><td>100</td><td>-</td><td>-</td><td>100</td></tr> <tr><td><code>SLOAD</code></td><td>Cold</td><td>Included</td><td>1</td><td>100</td><td>320</td><td>512</td><td>932</td></tr> <tr><td><code>SLOAD</code></td><td>None</td><td>Included</td><td>1</td><td>0</td><td>320</td><td>512</td><td>832</td></tr> <tr><td><code>SLOAD</code></td><td>Cold</td><td>Included</td><td>10</td><td>100</td><td>320</td><td>51.2</td><td>471</td></tr> <tr><td><code>SLOAD</code></td><td>None</td><td>Included</td><td>10</td><td>0</td><td>320</td><td>51.2</td><td>371</td></tr> <tr><td><code>SLOAD</code></td><td>Cold</td><td>Included</td><td>50</td><td>100</td><td>320</td><td>10.24</td><td>430</td></tr> <tr><td><code>SLOAD</code></td><td>None</td><td>Included</td><td>50</td><td>0</td><td>320</td><td>10.24</td><td>330</td></tr> </tbody></table> <ul> <li>Already paid on making warm</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP makes a minor update to <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> with respect to modern execution challenges and capabilities.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Same as per <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a></p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-05-09T00:00:00+00:00 2026-02-11T14:49:27+00:00 Charles Cooperhttps://github.com/charles-cooper https://wg-eips.ritovision.com/7705/

Opcodes to mark a contract as nonreentrant

<h2 id="abstract">Abstract</h2> <p>Add two opcodes, <code>NONREENTRANT</code> and <code>REENTRANT</code>, which set and clear a contract's reentrancy status. After invoking <code>NONREENTRANT</code>, a contract cannot be <code>CALL</code>ed (or <code>STATICCALL</code>ed, or <code>DELEGATECALL</code>ed) until <code>REENTRANT</code> is invoked.</p> <h2 id="motivation">Motivation</h2> <p>Reentrancy attacks account for a substantial portion of user funds stolen on EVM chains, including the famous "DAO hack". However, due to the cost of preventing reentrancy attacks in application code, developers often opt-out of reentrancy protection. This cost has come down with the advent of transient storage (<a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a>), but it is still not cheap enough where it is a "no-brainer" to use it by default. This EIP proposes opcodes which make it cheaper to protect against reentrancy in application code.</p> <h2 id="specification">Specification</h2> <p>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>Two new opcodes are introduced, <code>NONREENTRANT</code> (0xF6) and <code>REENTRANT</code> (0xF7), which set and clear a contract's nonreentrancy flag. The effect of invoking <code>NONREENTRANT</code> is that a contract can no longer have execution context transferred to it (via any of the <code>*CALL</code> opcodes), until <code>REENTRANT</code> is invoked. <code>CALL</code>ing a contract which has the nonreentrancy flag set is equivalent to executing a single <code>REVERT</code> opcode.</p> <p>Both <code>NONREENTRANT</code> and <code>REENTRANT</code> are idempotent; that is, invoking <code>NONREENTRANT</code> when a contract already has nonreentrant status is a no-op, and likewise for <code>REENTRANT</code>.</p> <p>The scope of the nonreentrant flag is limited to the current transaction. That is, nonreentrant flags are cleared at the end of every transaction. In the presence of reversion (<code>REVERT</code> or exceptional halt), the contract's nonreentrancy flag reverts to whatever its value was before the call.</p> <p>The cost of <code>NONREENTRANT</code> and <code>REENTRANT</code> are both set at 5 (<code>G_mid</code>).</p> <h2 id="rationale">Rationale</h2> <p>The computational cost of pushing the current value to the call stack (for handling reverts) is accounted for in the overhead cost of the <code>*CALL</code> opcodes.</p> <p>An alternative design could be considered which only introduces one opcode. This opcode, <code>NONREENTRANT</code>, would take a single stack item and set the nonreentrancy flag based on its value. This alternative design can be considered based on feedback.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <h2 id="reference-implementation">Reference Implementation</h2> <h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-05-07T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/7703/

Increase calldata cost to decrease the maximum block size

<h2 id="abstract">Abstract</h2> <p>An adjustment in the Ethereum calldata cost which reduces the maximum possible block size and allows a higher block gas limit.</p> <h2 id="motivation">Motivation</h2> <p>Larger blocks take longer to propagate through the network. In this way, the maximum potential block size is constraining the block gas limit. Therefore, in order to safely increase the block gas limit, the calldata gas must be increased.</p> <h2 id="specification">Specification</h2> <ul> <li>Increase <code>G_CALLDATAZERO</code> from 4 to 12.</li> <li>Increase <code>G_CALLDATANONZERO</code> from 16 to 48.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Tripling the gas cost of calldata reduces the maximum possible block size by a factor of three.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Activation can cause some transactions to revert due to the increased gas costs. Ahead of activation, <code>eth_estimateGas</code> could be calculated using the new parameters in order to provide results viable for activation, avoiding out-of-gas reverts.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No security issues have been found.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-05-01T00:00:00+00:00 2026-02-11T14:49:28+00:00 Vitalik Buterinhttps://github.com/vbuterin Yoav Weisshttps://github.com/yoavw Alex Forshtathttps://github.com/forshtat Dror Tiroshhttps://github.com/drortirosh Shahaf Nacsonhttps://github.com/shahafn https://wg-eips.ritovision.com/7701/

Native Account Abstraction protocol, relying on a new transaction type and a family of opcodes

<h2 id="abstract">Abstract</h2> <p>We propose splitting the Ethereum transaction scope into multiple steps: validations, execution, and post-operation logic. Transaction validity is determined by the result of the validation steps of a transaction.</p> <p>We further separate transaction validation for the purposes of authorization and the gas fee payment, allowing one contract to pay gas for a transaction that will be executed from another contract.</p> <h2 id="motivation">Motivation</h2> <p>Native Account Abstraction allows custom validation logic of a transaction and custom gas payment logic, opening new use-cases and features for wallets and dApps.</p> <p>A more detailed motivation for this proposal can be found in the <a href="https://wg-eips.ritovision.com/7701/assets/README/">README document</a>.</p> <h2 id="specification">Specification</h2> <h3 id="constants">Constants</h3> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>AA_TX_TYPE</code></td><td>TBD</td></tr> <tr><td><code>AA_ENTRY_POINT</code></td><td><code>address(0x7701)</code></td></tr> <tr><td><code>AA_BASE_GAS_COST</code></td><td>15000</td></tr> <tr><td><code>ROLE_SENDER_DEPLOYMENT</code></td><td><code>0xA0</code></td></tr> <tr><td><code>ROLE_SENDER_VALIDATION</code></td><td><code>0xA1</code></td></tr> <tr><td><code>ROLE_PAYMASTER_VALIDATION</code></td><td><code>0xA2</code></td></tr> <tr><td><code>ROLE_SENDER_EXECUTION</code></td><td><code>0xA3</code></td></tr> <tr><td><code>ROLE_PAYMASTER_POST_OP</code></td><td><code>0xA4</code></td></tr> </tbody></table> <h3 id="new-transaction-type">New Transaction Type</h3> <p>A new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction with type <code>AA_TX_TYPE</code> is introduced. Transactions of this type are referred to as "AA transactions".</p> <p>Their payload should be interpreted as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>AA_TX_TYPE || rlp([</span></span> <span class="giallo-l"><span> chain_id,</span></span> <span class="giallo-l"><span> nonce,</span></span> <span class="giallo-l"><span> sender, sender_validation_data,</span></span> <span class="giallo-l"><span> deployer, deployer_data,</span></span> <span class="giallo-l"><span> paymaster, paymaster_data,</span></span> <span class="giallo-l"><span> sender_execution_data,</span></span> <span class="giallo-l"><span> max_priority_fee_per_gas, max_fee_per_gas,</span></span> <span class="giallo-l"><span> sender_validation_gas, paymaster_validation_gas,</span></span> <span class="giallo-l"><span> sender_execution_gas, paymaster_post_op_gas,</span></span> <span class="giallo-l"><span> access_list,</span></span> <span class="giallo-l"><span> authorization_list</span></span> <span class="giallo-l"><span>])</span></span> <span class="giallo-l"></span></code></pre><h3 id="current-role-and-accept-role-opcodes"><code>CURRENT_ROLE</code> and <code>ACCEPT_ROLE</code> opcodes</h3> <p><code>current_context_role</code> is a context variable set by the AA transaction to the current role. During AA transactions, it is set to the current role in the transaction's lifecycle for each top level call. During non-AA transactions it is always set to <code>ROLE_SENDER_EXECUTION</code>. It remains unchanged on <code>DELEGATECALL</code> but is reset to <code>ROLE_SENDER_EXECUTION</code> on <code>CALL</code> / <code>STATICCALL</code> / <code>CALLCODE</code>. This behavior resembles <code>msg.sender</code>.</p> <p>The <code>CURRENT_ROLE</code> opcode returns the <code>current_context_role</code> value.</p> <p>The <code>ACCEPT_ROLE</code> opcode is equivalent to <code>RETURN</code> in the sense that it copies a memory slice, ends execution, and pastes the memory slice onto parent returndata, with a single modification:</p> <ul> <li>It accepts the <code>frame_role</code> as the additional input parameter, and reverts if it differs from the <code>current_context_role</code></li> </ul> <p>For each <code>role</code> in the transaction's lifecycle, a successful <code>ACCEPT_ROLE</code> is expected with the <code>frame_role == role</code>. If any validation frame failed to perform an <code>ACCEPT_ROLE</code> matching its role, the transaction fails the validity checks and cannot be included.</p> <h3 id="txparam-opcodes"><code>TXPARAM*</code> opcodes</h3> <p>The <code>TXPARAMDLOAD</code>, <code>TXPARAMSIZE</code>, <code>TXPARAMCOPY</code> opcodes follow the pattern of <code>CALLDATA*</code> / <code>RETURNDATA*</code> opcode families.</p> <p>Each <code>TXPARAM*</code> opcode takes an extra stack input value as a first input compared to its <code>CALLDATA*</code> equivalent. The values of this input are as follows:</p> <table><thead><tr><th><code>n</code></th><th>Return value</th><th>Data size</th><th>Default</th><th>Comment</th></tr></thead><tbody> <tr><td>0x00</td><td>current transaction type</td><td>32</td><td></td><td></td></tr> <tr><td>0x01</td><td><code>nonce</code></td><td>32</td><td></td><td></td></tr> <tr><td>0x02</td><td><code>sender</code></td><td>32</td><td></td><td></td></tr> <tr><td>0x03</td><td><code>sender_validation_data</code></td><td>dynamic</td><td></td><td></td></tr> <tr><td>0x04</td><td><code>deployer</code></td><td>0 or 32</td><td><code>address(0)</code></td><td></td></tr> <tr><td>0x05</td><td><code>deployer_data</code></td><td>dynamic</td><td>empty array</td><td></td></tr> <tr><td>0x06</td><td><code>paymaster</code></td><td>0 or 32</td><td><code>address(0)</code></td><td></td></tr> <tr><td>0x07</td><td><code>paymaster_data</code></td><td>dynamic</td><td>empty array</td><td></td></tr> <tr><td>0x08</td><td><code>sender_execution_data</code></td><td>dynamic</td><td></td><td></td></tr> <tr><td>0x0B</td><td><code>max_priority_fee_per_gas</code></td><td>32</td><td></td><td></td></tr> <tr><td>0x0C</td><td><code>max_fee_per_gas</code></td><td>32</td><td></td><td></td></tr> <tr><td>0x0D</td><td><code>sender_validation_gas</code></td><td>32</td><td></td><td></td></tr> <tr><td>0x0E</td><td><code>paymaster_validation_gas</code></td><td>32</td><td><code>0</code></td><td></td></tr> <tr><td>0x0F</td><td><code>sender_execution_gas</code></td><td>32</td><td></td><td></td></tr> <tr><td>0x10</td><td><code>paymaster_post_op_gas</code></td><td>32</td><td><code>0</code></td><td></td></tr> <tr><td>0x11</td><td><code>access_list</code> hash</td><td>32</td><td></td><td></td></tr> <tr><td>0x12</td><td><code>authorization_list</code> hash</td><td>32</td><td></td><td></td></tr> <tr><td>0xf1</td><td><code>execution_status</code></td><td>32</td><td></td><td>See transaction scoped vars in <a href="https://wg-eips.ritovision.com/7701/#aa-transaction-processing-flow">processing flow</a></td></tr> <tr><td>0xf2</td><td><code>execution_gas_used</code></td><td>32</td><td></td><td>See transaction scoped vars in <a href="https://wg-eips.ritovision.com/7701/#aa-transaction-processing-flow">processing flow</a></td></tr> <tr><td>0xff</td><td><code>tx_hash_for_signature</code></td><td>32</td><td></td><td>Hash of the transaction without the signature</td></tr> </tbody></table> <h3 id="affected-opcodes">Affected opcodes</h3> <p>In all top-level frames, the global variables have the following meaning:</p> <table><thead><tr><th>Opcode Name</th><th>Solidity Equivalent</th><th>Value</th></tr></thead><tbody> <tr><td><code>CALLER</code></td><td><code>msg.sender</code></td><td>The <code>AA_ENTRY_POINT</code> address</td></tr> <tr><td><code>ORIGIN</code></td><td><code>tx.origin</code></td><td>The transaction <code>sender</code> address</td></tr> <tr><td><code>CALLDATA*</code></td><td><code>msg.data</code></td><td>Empty for all call frames except for the sender execution frame, for which it is set to <code>sender_execution_data</code></td></tr> </tbody></table> <h3 id="costs-of-accessing-cold-addresses-for-sender-paymaster-and-deployer">Costs of accessing cold addresses for Sender, Paymaster, and Deployer</h3> <p>The Sender address is pre-warmed as part of the <code>AA_BASE_GAS_COST</code>.</p> <p>When a non-zero address that is not equal to the <code>Sender</code> address, is provided for a <code>Paymaster</code> or a <code>Deployer</code> contract, an additional <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> <code>ACCESS_LIST_ADDRESS_COST</code> cost of <strong>2400 gas</strong> is charged and the address is added to <code>accessed_addresses</code>.</p> <h3 id="aa-transaction-processing-flow">AA transaction processing flow</h3> <p>We define processing flow for an AA transaction as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def state_transition_function(tx, block, state):</span></span> <span class="giallo-l"><span> # Empty refunds, warm list, execution status and gas used (new), etc</span></span> <span class="giallo-l"><span> state.transaction_scoped_vars = {}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> max_gas = tx.sender_validation_gas + tx.paymaster_validation_gas + tx.sender_execution_gas + tx.paymaster_post_op_gas</span></span> <span class="giallo-l"><span> gas_price = min(tx.max_fee_per_gas, block.base_fee_per_gas + tx.max_priority_fee_per_gas)</span></span> <span class="giallo-l"><span> payer = tx.sender if tx.paymaster is None else tx.paymaster</span></span> <span class="giallo-l"><span> total_max_cost = max_gas * gas_price</span></span> <span class="giallo-l"><span> balances[payer] -= total_max_cost</span></span> <span class="giallo-l"><span> gas_used = 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if get_code(tx.sender) is None:</span></span> <span class="giallo-l"><span> deployer_result = call(tx.deployer, [], tx.sender_validation_gas_limit, ROLE_SENDER_DEPLOYMENT)</span></span> <span class="giallo-l"><span> assert deployer_result.accepted_role == ROLE_SENDER_DEPLOYMENT</span></span> <span class="giallo-l"><span> gas_used += deployer_result.gas_used</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> sender_result = call(tx.sender, [], tx.sender_validation_gas_limit - gas_used, ROLE_SENDER_VALIDATION)</span></span> <span class="giallo-l"><span> assert sender_result.accepted_role == ROLE_SENDER_VALIDATION</span></span> <span class="giallo-l"><span> gas_used += sender_result.gas_used</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if tx.paymaster:</span></span> <span class="giallo-l"><span> paymaster_result = call(tx.paymaster, [], tx.paymaster_validation_gas, ROLE_PAYMASTER_VALIDATION)</span></span> <span class="giallo-l"><span> assert paymaster_result.accepted_role == ROLE_PAYMASTER_VALIDATION</span></span> <span class="giallo-l"><span> gas_used += paymaster_result.gas_used</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> checkpoint = state.take_snapshot()</span></span> <span class="giallo-l"><span> sender_execution_result = call(tx.sender, [], tx.sender_execution_gas, ROLE_SENDER_EXECUTION)</span></span> <span class="giallo-l"><span> gas_used += sender_execution_result.gas_used</span></span> <span class="giallo-l"><span> state.transaction_scoped_vars[execution_status] = sender_execution_result.output_code</span></span> <span class="giallo-l"><span> state.transaction_scoped_vars[execution_gas_used] = gas_used</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if tx.paymaster:</span></span> <span class="giallo-l"><span> postop_result = call(tx.paymaster, [], tx.paymaster_post_op_gas, ROLE_PAYMASTER_POST_OP)</span></span> <span class="giallo-l"><span> gas_used += postop_result.gas_used</span></span> <span class="giallo-l"><span> if postop_result.accepted_role != ROLE_PAYMASTER_POST_OP:</span></span> <span class="giallo-l"><span> state.revert_snapshot(checkpoint)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> balances[payer] += gas_price * (max_gas - gas_used)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>A full list of rationales for the decisions made in this proposal can be found in the <a href="https://wg-eips.ritovision.com/7701/assets/README/">README document</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h2 id="security-considerations">Security Considerations</h2> <p>As the <code>ACCEPT_ROLE</code> opcode represent a generic way to authorize any action on behalf of the contract, correct and secure implementation of this code is critical. We expect that compilers targeting EVM will play a major role in enabling and ensuring Smart Contract Accounts' security.</p> <p>For smart contract security auditors and security-oriented developer tools it is crucial to ensure that contracts not meant to have roles in AA transactions do not have unexpected <code>ACCEPT_ROLE</code> opcode. Otherwise, these contracts may present an immediate security threat.</p> <p>As an example, block explorers should tag contracts as "user accounts" or "paymasters" if they have the <code>ACCEPT_ROLE</code> opcode used in their source code.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-04-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Piotr Dobaczewskihttps://github.com/pdobacz Andrei Maiborodahttps://github.com/gumb0 Paweł Bylicahttps://github.com/chfast Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/7698/

Deploy EOF contracts using creation transactions

<h2 id="abstract">Abstract</h2> <p>Creation transactions (i.e. the ones with empty <code>to</code>) can be used to deploy EOF contracts by providing EOF initcontainer concatenated with <code>calldata</code> for initcontainer execution in transaction's <code>data</code>. Initcontainer execution is similar to its execution during <code>EOFCREATE</code> instruction, ending with <code>RETURNCODE</code> instruction. New account address calculation is based on sender's address and nonce.</p> <h2 id="motivation">Motivation</h2> <p>Creation transaction is one of the three ways alongside creation instructions provided by legacy EVM to deploy new code. Given that legacy creation instructions (<code>CREATE</code> and <code>CREATE2</code>) are not allowed to deploy EOF code, supporting EOF in creation transactions is the only way to get the first EOF on-chain.</p> <p>The mechanism for providing constructor arguments to initcontainer is exactly the same as for deploying legacy code (just concatenating them with initcontainer), therefore existing deployment tooling can be used as is to deploy EOF.</p> <h2 id="specification">Specification</h2> <p>Wherever not explicitly listed, the rules of EOF contract creation should be identical or analogous to those of legacy creation transaction. This includes but is not limited to:</p> <ul> <li>behavior on <code>accessed_addresses</code> and address collision (<a href="https://wg-eips.ritovision.com/684/">EIP-684</a> and <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>)</li> <li>EVM execution frame created for the initcode - memory, account context etc.</li> <li>nonce bumping of the account of newly created contract <a href="https://wg-eips.ritovision.com/161/">EIP-161</a></li> <li>balance checking and transfer for the creation endowment</li> </ul> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>EOF_MAGIC</code></td><td>Defined as <code>0xEF00</code> in <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a></td></tr> <tr><td><code>MAX_CODE_SIZE</code></td><td>Defined as <code>24576</code> in <a href="https://wg-eips.ritovision.com/170/">EIP-170</a></td></tr> </tbody></table> <p>In case a creation transaction (transaction with empty <code>to</code>) has <code>data</code> starting with <code>EOF_MAGIC</code>, <code>data</code> is interpreted as a concatenation of EOF <code>initcontainer</code> and <code>calldata</code>. More specifically:</p> <ol> <li>Intrinsic gas cost rules and limits defined in <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a> for creation transactions apply. The entire <code>data</code> of the transaction is used for these calculations.</li> <li>Find the split of <code>data</code> into <code>initcontainer</code> and <code>calldata</code>: <ul> <li>Parse EOF header</li> <li>Find <code>intcontainer</code> size by reading all section sizes from the header and adding them up with the header size to get the full container size.</li> </ul> </li> <li>Validate the <code>initcontainer</code> and all its subcontainers recursively. <ul> <li>Unlike in general validation, <code>initcontainer</code> is additionally required to have <code>data_size</code> declared in the header equal to actual <code>data_section</code> size.</li> <li>Validation includes checking that the <code>initcontainer</code> does not contain <code>RETURN</code> or <code>STOP</code></li> </ul> </li> <li>If EOF header parsing or full container validation fails, transaction is considered valid and failing. Gas for initcode execution is not consumed, only intrinsic creation transaction costs are charged.</li> <li><code>calldata</code> part of transaction <code>data</code> that follows <code>initcontainer</code> is treated as calldata to pass into the execution frame.</li> <li>Execute the container and deduct gas for execution. <ol> <li>Calculate <code>new_address</code> as <code>keccak256(sender || sender_nonce)[12:]</code></li> <li>A successful execution ends with initcode executing <code>RETURNCODE{deploy_container_index}(aux_data_offset, aux_data_size)</code> instruction. After that: <ul> <li>load deploy-contract from EOF subcontainer at <code>deploy_container_index</code> in the container from which <code>RETURNCODE</code> is executed,</li> <li>concatenate data section with <code>(aux_data_offset, aux_data_offset + aux_data_size)</code> memory segment and update data size in the header,</li> <li>let <code>deployed_code_size</code> be updated deploy container size,</li> <li>if <code>deployed_code_size &gt; MAX_CODE_SIZE</code> instruction exceptionally aborts,</li> <li>set <code>state[new_address].code</code> to the updated deploy container (rules of <a href="https://wg-eips.ritovision.com/3541/">EIP-3541</a>, prohibiting deployment of <code>code</code> starting with <code>EF</code> from creation transactions, do not apply in this case).</li> </ul> </li> </ol> </li> <li>Deduct <code>200 * deployed_code_size</code> gas.</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="irregular-state-change-to-deploy-creator-contract">Irregular state change to deploy Creator Contract</h3> <p>Originally it was proposed to deploy the first EOF contract via irregular state change. This contract would execute <code>TXCREATE</code> instruction and could be used then as an entry point to deploy any other EOF code. This would also require an introduction of <code>InitcodeTransaction</code>, required by <code>TXCREATE</code>. It was decided against this variant for the benefit of reduced scope of changes.</p> <h3 id="constructor-arguments-outside-of-initcontainer-vs-in-data-section">Constructor arguments outside of initcontainer vs in data section</h3> <p>Alternative mechanism for providing constructor arguments to initcontainer execution was considered, where they are concatenated with data section of the initcontainer and are accessed via <code>DATA*</code> instructions instead of <code>CALLDATA*</code>. This has a benefit of not requiring the step finding the split of <code>transaction.data</code> into <code>initcontainer</code> and <code>calldata</code>, as entire <code>transaction.data</code> is an EOF container. However it was rejected for the following reasons:</p> <ul> <li>Existing tooling could not be used for deploying EOF without modification. To construct EOF creation transaction, the tooling would need to append constructor arguments to the container, as well as update data section size in the EOF header. Compiler could predict the size of constructor arguments to put the anticipated data size in the header, but it would not be possible for variadic length constructor arguments.</li> <li>In case a specialized EOF creation transaction is introduced in a later upgrade (such as the <code>InitcodeTransaction</code>), it would have a dedicated field for initcontainer execution input (<code>calldata</code>), and it will be accessed with <code>CALLDATA*</code> instructions in initcode. It is better to avoid the situation where compilers would need to generate initcontainer code differently depending on which context it will be used in.</li> <li>As a general argument, data section can be seen to contain the data that execution considers validated and being closely coupled with the code definition, whereas calldata is an input from the outside that may be arbitrary and not validated.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Creation transactions deploying legacy code are not affected, because any such transaction starting with <code>EF</code> byte previously would fail on executing invalid instruction.</p> <h2 id="security-considerations">Security Considerations</h2> <p>TBA</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-04-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast Andrei Maiborodahttps://github.com/gumb0 Piotr Dobaczewskihttps://github.com/pdobacz Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/7692/

List of EIPs belonging to the EOFv1 proposal

<h2 id="abstract">Abstract</h2> <p>This Meta EIP lists the EIPs which belong to the EVM Object Format (EOF) proposal, in its first version (EOFv1), also known as the "Mega EOF".</p> <h2 id="specification">Specification</h2> <h3 id="eips-included">EIPs Included</h3> <p>Introduced in eof-devnet-0</p> <ul> <li><a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>: EOF - EVM Object Format v1</li> <li><a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a>: EOF - Code Validation</li> <li><a href="https://wg-eips.ritovision.com/4200/">EIP-4200</a>: EOF - Static relative jumps</li> <li><a href="https://wg-eips.ritovision.com/4750/">EIP-4750</a>: EOF - Functions</li> <li><a href="https://wg-eips.ritovision.com/5450/">EIP-5450</a>: EOF - Stack Validation</li> <li><a href="https://wg-eips.ritovision.com/6206/">EIP-6206</a>: EOF - JUMPF and non-returning functions</li> <li><a href="https://wg-eips.ritovision.com/7480/">EIP-7480</a>: EOF - Data section access instructions</li> <li><a href="https://wg-eips.ritovision.com/663/">EIP-663</a>: SWAPN, DUPN and EXCHANGE instructions</li> <li><a href="https://wg-eips.ritovision.com/7069/">EIP-7069</a>: Revamped CALL instructions</li> <li><a href="https://wg-eips.ritovision.com/7620/">EIP-7620</a>: EOF Contract Creation</li> <li><a href="https://wg-eips.ritovision.com/7698/">EIP-7698</a>: EOF - Creation transaction</li> </ul> <p>Introduced in eof-devnet-1</p> <ul> <li><a href="https://wg-eips.ritovision.com/7873/">EIP-7873</a>: EOF - TXCREATE and InitcodeTransaction type</li> </ul> <p>Removed from eof-devnet-1</p> <ul> <li><a href="https://wg-eips.ritovision.com/7698/">EIP-7698</a>: EOF - Creation transaction</li> </ul> <p>Introduced in eof-devnet-2</p> <ul> <li><a href="https://wg-eips.ritovision.com/7834/">EIP-7834</a>: Separate Metadata Section for EOF</li> <li><a href="https://wg-eips.ritovision.com/7761/">EIP-7761</a>: EXTCODETYPE instruction</li> <li><a href="https://wg-eips.ritovision.com/7880/">EIP-7880</a>: EOF - EXTCODEADDRESS instruction</li> <li><a href="https://wg-eips.ritovision.com/5920/">EIP-5920</a>: PAY opcode</li> </ul> <h2 id="rationale">Rationale</h2> <p>Refer to the individual EIPs.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Discussed in the individual EIPs.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-04-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7686/

Adjust memory limits and gas limits of sub-calls to create a clear linear bound on how much total memory an EVM execution can consume

<h2 id="abstract">Abstract</h2> <p>Add a hard memory limit equal to the gas limit of the current context. Make the maximum gas cost of a sub-call depend on the memory used in the current context. The two rules together ensure that a transaction with N gas can use at most N bytes of memory.</p> <h2 id="motivation">Motivation</h2> <p>Today, memory pricing rules are complicated: we have the quadratic cost for expanding memory as well as the 63/64 rule for how much gas can go into a child call. This also makes it extremely hard to calculate a maximum possible amount of memory required to process a given EVM execution.</p> <p>The rules in this post simplify these rules, and add a new hard limit: an EVM execution with N gas can require at most N total bytes of memory to process. This limit is tight: there are easy ways for an N-gas call to use <code>N - O(1)</code> bytes of memory.</p> <h2 id="specification">Specification</h2> <p>Change <code>memory_cost</code> from:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>memory_size_word</span><span class="z-keyword"> =</span><span> (</span><span>memory_byte_size</span><span class="z-keyword"> +</span><span class="z-constant"> 31</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 32</span></span> <span class="giallo-l"><span>memory_cost</span><span class="z-keyword"> =</span><span> (</span><span>memory_size_word</span><span class="z-keyword"> **</span><span class="z-constant"> 2</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 512</span><span class="z-keyword"> +</span><span> (</span><span class="z-constant">3</span><span class="z-keyword"> *</span><span> memory_size_word</span><span>)</span></span></code></pre> <p>To:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>memory_size_word</span><span class="z-keyword"> =</span><span> (</span><span>memory_byte_size</span><span class="z-keyword"> +</span><span class="z-constant"> 31</span><span>)</span><span class="z-keyword"> /</span><span class="z-constant"> 32</span></span> <span class="giallo-l"><span>memory_cost</span><span class="z-keyword"> =</span><span class="z-constant"> 3</span><span class="z-keyword"> *</span><span> memory_size_word</span></span></code></pre> <p>Additionally, if a memory expansion would lead to <code>memory_byte_size</code> strictly exceeding the current call's initial gas limit, revert with an error.</p> <p>When making any type of call, change the maximum gas limit from the current <a href="https://wg-eips.ritovision.com/150/">EIP-150</a> definition:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> max_call_gas</span><span>(</span><span class="z-variable z-parameter z-function">gas</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> gas</span><span class="z-keyword"> -</span><span> (</span><span>gas</span><span class="z-keyword"> //</span><span class="z-constant"> 64</span><span>)</span></span></code></pre> <p>To:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> max_call_gas</span><span>(</span><span class="z-variable z-parameter z-function">gas</span><span>,</span><span class="z-variable z-parameter z-function"> memory_byte_size</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> gas</span><span class="z-keyword"> -</span><span class="z-support"> max</span><span>(</span><span>gas</span><span class="z-keyword"> //</span><span class="z-constant"> 64</span><span>,</span><span> memory_byte_size</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>With this EIP, there is a simple EVM implementation that can process an N-gas call using an N-byte bytearray as memory: allocate all bytes to the current context, when doing a child call use the remaining memory starting from the position <code>memory_byte_size</code> for the child call's memory, and so on recursively.</p> <p>Having this clean invariant is useful for EVM implementations, especially EVM implementations in constrained environments (eg. ZK-SNARK provers).</p> <p>The 3 gas per word memory expansion cost is retained because it is equivalent to MCOPY, and so the operation of clearing memory at the end of a child call (cheap in regular machines, but more expensive in ZK-SNARKs and other unusual contexts) can be implemented with the same logic as that used to implement the MCOPY opcode itself.</p> <p>The 63/64 rule is maintained in order to maintain the current de-facto call stack depth limit of roughly <code>1 + log((gaslimit + 6300) / 6400) / log(64/63) = 537</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>It is theoretically possible for EVM code that works today to fail to work under this new EIP, if that code accesses a high index in memory but is called with a low gas limit. However, almost all EVM execution consumes far more code than it uses bytes of memory. For example, for a call to cause even a single state change, it must have at least 5000 gas. This would allow it 5000 bytes of memory, which is greater than that used by almost all applications. More complex applications would have even higher limits.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No security concerns were raised.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-04-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 Lionhttps://github.com/dapplion https://wg-eips.ritovision.com/7684/

Automatically withdraw deposits for existing validator records but with distinct execution withdrawal credentials

<h2 id="abstract">Abstract</h2> <p>Automatically withdraw deposits for existing validator records, but where the deposit includes a distinct execution withdrawal credential.</p> <h2 id="motivation">Motivation</h2> <p>Some staking operations feature two distinct entities, one operating the validating key, and one funding the deposit. The funding entity delegates control of the stake operation but must retain ultimate control of funds. If the funding entity naively submits a single deposit with the full stake amount and the other entity's validating key, it is subject to a front-run attack. The validating entity can front-run the bigger deposit with a second deposit with its own set of withdrawal credentials. The full stake amount deposit becomes a top-up, in control of the validating entity.</p> <p>There exist workarounds to the front-run attack. Using some distributed key generation protocol between the funding and validating entity, such that a deposit must be made with the consent of both entities. Submit a 1 ETH deposit first wait for its inclusion then send the full stake amount as a top-up, to bind the maximum loss under the attack to 1 ETH. While these workarounds, work; they difficult the operation of trustless autonomous staking protocols.</p> <p>This specification reduces the total loss on a naive deposit submission from the full deposit amount to <code>RETURN_DEPOSIT_PENALTY</code>.</p> <h2 id="specification">Specification</h2> <h3 id="consensus-layer">Consensus Layer</h3> <p>The configuration values and mechanics of the specification can be found in the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/2360756c8c19c0f7b0e91135f5bbcddecdf0a835/specs/_features/eip9999/beacon_chain.md">Consensus Layer specs</a>.</p> <p>A sketch of the resulting changes to the consensus layer is included below.</p> <ul> <li>Modify <code>apply_deposit</code> to queue for withdrawal deposits with distinct execution withdrawal credentials</li> <li>Modify <code>get_expected_withdrawals</code> to return pending withdrawals first</li> <li>Modify <code>process_withdrawals</code> to clear the pending withdrawals queue</li> </ul> <h3 id="execution-layer">Execution Layer</h3> <p>This specification does not require any changes to the Execution Layer.</p> <h2 id="rationale">Rationale</h2> <h3 id="persist-pending-withdrawals">Persist pending withdrawals</h3> <p>Rejected deposits from block at slot N can not be withdrawn in block N due to a cyclic dependency. An execution client must know the full list of withdrawals before constructing a payload for slot N. After <a href="https://wg-eips.ritovision.com/6110/">EIP-6110</a>, a consensus client must know the full execution payload for slot N before constructing the beacon block for slot N. Therefore, rejected deposits must be withdrawn in some future slot. All pending withdrawals are processed at once in the very next slot for simplicity but could be queued and processed progressively if there are DOS concerns.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backward incompatible change to the Consensus Layer of Ethereum and must be scheduled with a hard fork.</p> <p>There are no forwards / backwards compatibility issues with the Execution Layer</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are work-in-progress within the standard Consensus Layer tests.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The worst-case number of withdrawals is raised from a fixed 16 to 1,271 under current gas rules and a 30M gas block. Citing <a href="https://wg-eips.ritovision.com/6110/">EIP-6110</a>, future gas efficiencies can increase the number to 1,916 withdrawals in a 30M gas block. Each withdrawal results in a single address balance change. There is no explicit pricing for such an operation, but under the worst case, it results in a notable increase in the total block gas (30% assuming 6,900 gas per withdrawal and current gas rules).</p> <p><code>RETURN_DEPOSIT_PENALTY</code> disincentivizes rejected deposits, and imposes a gas cost of 144,927 Gwei / gas, assuming 6,900 gas per withdrawal.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-04-03T00:00:00+00:00 2026-02-11T14:49:28+00:00 Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/7676/

Update EOF opcodes so addresses are not trimmed during execution

<h2 id="abstract">Abstract</h2> <p>Operations in the Legacy EVM trim off the top 12 bytes of an address operand before evaluation. This EIP changes the handling of those opcodes within EOF so that no trimming occurs and the top twelve bytes need to be zero or an exceptional halt is raised.</p> <h2 id="motivation">Motivation</h2> <p>There have been proposals to extend Ethereum Addresses from 160 bits to 256, such as one that would use the extra bits for state expiry (such as the ethereum magicians forum topic "Increasing the address size from 20 to 32 bytes"). One issue ground the work to a halt: EVM opcodes that accept addresses trim all but the lowest 20 bytes out from the operand before processing. EVM Reference tests verify this behavior in the 'stBadOpcode/invalidAddr.json' tests.</p> <p>The EVM Object Format presents an opportunity to remove this address masking in a backwards compatible way, by baking it into the format definition from the start.</p> <p>Most of the work is already in place. The following 5 operations have already been banned from EOF: <code>EXTCODESIZE</code>, <code>EXTCODECOPY</code>, <code>EXTCODEHASH</code>, <code>CALLCODE</code>, and <code>SELFDESTRUCT</code>. Three call operations, <code>CALL</code>, <code>DELEGATECALL</code>, and <code>STATICCALL</code> are being revamped in <a href="https://wg-eips.ritovision.com/7069/">EIP-7069</a>. That leaves only one operation, <code>BALANCE</code>, with issues.</p> <p>When future uses of address space extension are specified it is expected that the exceptional halt behavior will be modified.</p> <h2 id="specification">Specification</h2> <p>We introduce one new instruction:</p> <ul> <li><code>EXTBALANCE</code> (<code>tbd</code>) with arguments <code>(target_address)</code>, returning <code>balance</code></li> </ul> <p><code>EXTBALANCE</code> will pop one stack item off of the stack, the address of another account or contract. The balance of that account or contract will be pushed onto the stack.</p> <p>If <code>EXTBALANCE</code> is invoked with any of the high 12 bytes in <code>target_address</code> set to a non-zero value the operation will cause an exceptional halt. All gas in the current frame will be consumed on failure, no gas schedule change is needed.</p> <p>The gas cost of <code>EXTBALANCE</code> will be costed according to the gas schedule for the <code>BALANCE</code> operation specified in <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>. This means if the account is not in <code>accessed_addresses</code> then it is charged 2600 gas and added to <code>accessed_addresses</code>. If the account is in <code>accessed_addresses</code> then 100 gas is charged. The <code>accessed_addresses</code> is shared with all other operands described in <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>.</p> <p>Also, for the <code>EXTCALL</code>, <code>EXTDELEGATECALL</code>, and <code>EXTSTATICCALL</code> operations a new step is added just before the memory expansion check: halt with exceptional failure if any of the high 96 bits of the <code>target_address</code> are set.</p> <p>It is anticipated that future EIPs will alter the behavior in a way that will not result in an exceptional halt. Contract implementors should not depend on the exceptional halt.</p> <h2 id="rationale">Rationale</h2> <h3 id="new-opcode">New Opcode</h3> <p>There is no need to ban the <code>BALANCE</code> opcode as it does not cause any problems that would require banning it within an EOF container. Adding a new opcode also allows the existing opcode to behave the same in EOF and legacy code, reducing potential friction points for end user confusion and bugs.</p> <h3 id="revert-on-invalid-address">Revert on invalid address</h3> <p>There are two alternative ways to handle accounts with high bits set. The specification calls for an exceptional halt, but the alternative was to treat the account as empty. The reason the "empty account" approach was rejected is twofold:</p> <ul> <li>The <code>accessed_addresses</code> list could be required to track 256 bit accounts when an invalid address is accessed.</li> <li>The <code>EXTCALL</code> series instructions could still send balance to those addresses and such accounts would then hold an (inaccessible) balance that would need to be reflected in the merkle trie.</li> </ul> <h3 id="no-change-in-gas-costing">No change in gas costing</h3> <p>Because the BALANCE operation already needs to check <code>accessed_addresses</code> there is already a good amount of processing that must go into the operation. Hence, no changes to the gas schedule are needed to prevent abuse of the failures. Such incremental costs will be dominated by costs related to reverts and address checking for valid accounts.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Preparing for Address Space Expansion is explicitly done inside the scope of EOF with the intent that it will not require changes in old contracts, but with the caveat that old contracts may not be able to use addresses in the expanded space.</p> <p>Future EIPs should be mindful when adding new operation with an address operand or parameter to how it interacts with EOF and legacy contracts. Authors should ensure that such additions remain in harmony with this EIP.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases similar to <code>invalidAddr.json</code> tests in the standard reference tests will need to be written for the EOF tests, except they would check for halts on invalid addresses.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>TBD <!-- TODO --></p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP only defines a revert behavior for previously stripped addresses. Compilers will need to be aware of the need to mask addresses coming in from call data. Some of this is already present in existing Solidity ABI standards, but more care should be taken in examining the flow around <code>EXTBALANCE</code> and code for <code>EXTCALL</code> operations to ensure that compiled code strips the high bytes.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-03-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7666/

Remove the identity precompile, and put into place a piece of EVM code that has equivalent functionality

<h2 id="abstract">Abstract</h2> <p>Remove the identity precompile at 0x04. At the start of executing the block in which this change activates, put into that contract a short piece of EVM code that has the same functionality.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum today has a large number of precompiles. Nearly half of these precompiles are not seeing significant use, and are contributing to ongoing maintenance cost and risk of consensus bugs, as well as increased development effort for new Ethereum client implementations, including ZK-EVMs and implementations in formal-verification-friendly languages.</p> <p>This EIP proposes a path for the Ethereum ecosystem to gracefully abandon these precompiles, and takes a first step by applying this procedure to the simplest precompile of all: the identity precompile (which outputs returndata equal to the input calldata). The identity precompile was originally introduced because memory copying is a common operation, and there was no opcode available to do it directly. Since then, norms around what is acceptable for an opcode have changed, and we have introduced the MCOPY opcode with <a href="https://wg-eips.ritovision.com/5656/">EIP-5656</a>. And so we can remove the identity precompile, and replace it with an ultra-minimal piece of EVM code that replicates its functionality.</p> <p>In the future, this technique can be applied to other more complex precompiles, such as little-used hash functions and MODEXP.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>IDENTITY_PRECOMPILE_ADDRESS</code></td><td><code>0x0000....0004</code></td></tr> <tr><td><code>EVM_CODE</code></td><td><code>0x365f5f37365ff3</code></td></tr> </tbody></table> <p>At the start of the block in which this fork activates, set the code of <code>IDENTITY_PRECOMPILE_ADDRESS</code> to <code>EVM_CODE</code>. Starting from and including that block, <code>IDENTITY_PRECOMPILE_ADDRESS</code> should no longer be treated as a precompile.</p> <h2 id="rationale">Rationale</h2> <p>The given <code>EVM_CODE</code> corresponds to</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>CALLDATASIZE PUSH0 PUSH0 CALLDATACOPY CALLDATASIZE PUSH0 RETURN</span></span></code></pre> <p>Which copies calldata into memory, and then returns the same memory slice. This is thus a minimally disruptive change to Ethereum that preserves functionality, and accomplishes the goal of reducing the number of precompiles by 1.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The functionality of the given <code>EVM_CODE</code> is the same as the identity precompile. Gas costs are slightly different, though gas repricings have been done in the Ethereum ecosystem several times before and their effects are well understood.</p> <h2 id="security-considerations">Security Considerations</h2> <p>As no new functionality is introduced or made cheaper, no security concerns are raised.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-03-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7667/

Raise the gas costs of hash function opcodes and precompiles, to match prover expenses in ZK-EVMs

<h2 id="abstract">Abstract</h2> <p>Raise the gas costs of opcodes and precompiles that involve hash functions.</p> <h2 id="motivation">Motivation</h2> <p>Gas costs for hash function opcodes and precompiles were originally set based on the time that it takes to execute them on a regular CPU. Since then, however, there has emerged another equally important execution substrate that the EVM is executed on: zero knowledge proof (ZK-SNARK) systems. By that standard, these opcodes and precompiles are <em>very</em> underpriced relative to other operations.</p> <p>Blocks that are heavy with hash function executions take much longer to ZK-SNARK prove than average blocks. Today, many layer-2 protocols are using workarounds such as arbitrary limits and rules enforced by centralized sequencers to deal with this issue. These workarounds are often poorly designed and lead to unneeded security and centralization concerns.</p> <p>Additionally, there is a design goal of eventually using ZK-SNARKs to prove the correctness of layer-1 Ethereum blocks. To do this, we need to establish very tight bounds on how long it takes to generate a ZK-SNARK proof of an Ethereum execution block's correctness. Today, the difference between average-case proving time and worst-case proving time is large, and hash function executions are the largest reason why.</p> <p>Verkle trees solve the part of this problem that comes from Keccak hashing in the Merkle Patricia tree. Today, the theoretical worst case is a block with <code>30000000 / 2600 = 11538</code> account accesses (minus a small percent for EVM overhead), where proving each access would require proving <code>24000</code> bytes of code, plus a roughly <code>512 * log(500m) / log(16) = 3712</code> byte Merkle-Patricia proof: roughly <code>305 MB</code> of hashing spread between <code>83650</code> hash calls. Verkle trees solve this. However, using opcodes, a block execution can still require roughly the following amount of hashing:</p> <table><thead><tr><th>Hash</th><th>Cost per word</th><th>Maximum bytes from 30 million gas</th></tr></thead><tbody> <tr><td><code>KECCAK</code> (opcode)</td><td>6</td><td>160 million</td></tr> <tr><td><code>SHA256</code> (precompile)</td><td>12</td><td>80 million</td></tr> <tr><td><code>RIPEMD</code> (precompile)</td><td>120</td><td>8 million</td></tr> <tr><td><code>BLAKE2</code> (precompile)</td><td>3 (12 per 128 bytes)</td><td>320 million</td></tr> <tr><td><code>LOG*</code> (hashing data)</td><td>256 (8 per byte)</td><td>3.75 million</td></tr> </tbody></table> <p>These hash functions have been optimized for rapid CPU computation, so CPUs can compute them quickly: for example, this author's laptop can compute a 160-million byte keccak in less than half a second. In ZK-SNARKs, however, these operations are <em>very</em> time-consuming and inefficient. This is mitigated in newer proof systems based on small fields, but hashes remain underpriced.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Previous value</th><th>New value</th></tr></thead><tbody> <tr><td><code>KECCAK_BASE_COST</code></td><td>30</td><td>300</td></tr> <tr><td><code>KECCAK_WORD_COST</code></td><td>6</td><td>60</td></tr> <tr><td><code>SHA256_BASE_COST</code></td><td>60</td><td>300</td></tr> <tr><td><code>SHA256_WORD_COST</code></td><td>12</td><td>60</td></tr> <tr><td><code>RIPEMD_BASE_COST</code></td><td>600</td><td>600</td></tr> <tr><td><code>RIPEMD_WORD_COST</code></td><td>120</td><td>120</td></tr> <tr><td><code>BLAKE2_GFROUND</code></td><td>1</td><td>10</td></tr> <tr><td><code>GLOGBYTE</code></td><td>8</td><td>10</td></tr> </tbody></table> <p>Change the above parameters to their new values.</p> <h2 id="rationale">Rationale</h2> <p>The above increases the gas costs of all opcodes and precompiles that can be used to require large amounts of hashing in the EVM. All hashing costs are increased to 300 per hash plus 60 per word (or kept the same if they are already higher than this). '" A possible alternative to this approach is to implement either multidimensional gas pricing (ie. a separate floating basefee and per-block target and limit for hashes) or a "total gas cost floor" similar to what <a href="https://wg-eips.ritovision.com/7623/">EIP-7623</a> does for calldata. However, this approach is much harder to implement for in-EVM gas costs such as hashes than it is for calldata and blobs, because EVM gas limits are set not just by users, for whom new transaction types that specify newly required limits, max-basefees and priority fees can easily be added, but also by contracts making sub-calls to other contracts.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>For most applications, a reasonable upper bound is that data that is getting hashed in the EVM is getting brought in as calldata. If the hashing being done is binary Merkle proof verification, every 32 bytes of data corresponds to a 64-byte (2-word) hash. A word of costs 512 gas. Under the new costs, the hashing per word in that situation would be <code>300 + 60 * 2 = 420</code> gas. Hence, this will increase gas consumption for that component of the application by less than 2x.</p> <p>Concretely, a length-20 Keccak-based binary Merkle proof gas cost would increase from <code>(512 + 42) * 20 = 11080</code> to <code>(512 + 420) * 20 = 18640</code>. This is a small increase, especially taking into account other costs associated with such an application.</p> <h2 id="security-considerations">Security Considerations</h2> <p>As no new operations are introduced or made cheaper, no security concerns were raised.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-03-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/7668/

Remove bloom filters from the execution block

<h2 id="abstract">Abstract</h2> <p>Require the bloom filters in an execution block, including at the top level and in the receipt object, to be empty.</p> <h2 id="motivation">Motivation</h2> <p>Logs were originally introduced to give applications a way to record information about onchain events, which decentralized applications (dapps) would be able to easily query. Using bloom filters, dapps would be able to quickly go through the history, identify the few blocks that contained logs relative to their application, and then quickly identify which individual transactions have the logs that they need.</p> <p>In practice, this mechanism is far too slow. Almost all dapps that access history end up doing so not through RPC calls to an Ethereum node (even a remote-hosted one), but through centralized extra-protocol services.</p> <p>This EIP proposes recognizing that reality, and removing bloom filters from the protocol. Applications that need history querying would be encouraged to develop and use decentralized protocols that create provable log indexes using eg. ZK-SNARKs and incrementally-verifiable computation.</p> <h2 id="specification">Specification</h2> <p>The logs bloom of an execution block is now required to be empty (ie. 0 bytes long). The logs bloom of a transaction receipt is now required to be empty (ie. 0 bytes long).</p> <h2 id="rationale">Rationale</h2> <p>This is a minimally disruptive way to remove the need to handle blooms from clients. A future EIP can later clean up by removing this field entirely, along with other fields that have been deprecated.</p> <p>Gas costs of LOG are not reduced, because while the externality of polluting the bloom filter no longer needs to be accounted for, the costs of hashing have increased due to the needs of ZK-SNARK EVM implementations.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Applications that depend on bloom filters to read events will cease to work. Very few applications depend on this feature today, because at current gas limits the false positive rate is so high and processing the logs in a long history query is so slow, especially for light clients (whom this feature was primarily intended to benefit).</p> <h2 id="security-considerations">Security Considerations</h2> <p>As no new features are introduced or made cheaper, no security concerns are raised.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-03-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status https://wg-eips.ritovision.com/7657/

Slashing condition for malicious sync committee messages

<h2 id="abstract">Abstract</h2> <p>This EIP defines a slashing condition for malicious <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/altair/validator.md#containers">sync committee messages</a>.</p> <h2 id="motivation">Motivation</h2> <p>A dishonest supermajority of sync committee members is able to convince applications relying on Ethereum's <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/altair/light-client/sync-protocol.md">light client sync protocol</a> to assume a non-canonical finalized header, and to potentially take over the sync authority for future <code>SyncCommitteePeriod</code>. By signing a malicious beacon block root, a malicious (but valid!) <code>LightClientUpdate</code> message can be formed and subsequently used to, for example, exploit a trust-minimized bridge contract based on the light client sync protocol.</p> <p>An additional type of slashing is introduced to deter against signing non-canonical beacon block roots as a sync committee member. As is the case with <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/phase0/beacon-chain.md#proposerslashing"><code>ProposerSlashing</code></a> and <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/b3e83f6691c61e5b35136000146015653b22ed38/specs/phase0/beacon-chain.md#attesterslashing"><code>AttesterSlashing</code></a>, only malicious behaviour is slashable. This includes simultaneous contradictory participation across multiple chain branches, but a validator that is simply tricked into syncing to an incorrect checkpoint should not be slashable even though it is participating on a non-canonical chain. Note that a slashing must be verifiable even without access to history, e.g., by a checkpoint synced beacon node.</p> <p>Note that regardless of the slashing mechanism, a slashing can only be applied retroactively after an attack has already occurred. Use cases that secure a larger amount than <code>SYNC_COMMITTEE_SIZE * MAX_EFFECTIVE_BALANCE</code> = <code>512 * 32 ETH</code> = <code>16384 ETH</code> (on mainnet) should combine the light client sync protocol with other established methods such as a multisig, or may want to require posting additional collateral to be eligible for submitting updates. Other methods are out of scope for this EIP.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="state-transition-checks">State transition checks</h3> <p>Note: This still allows having contradictions between attestations/proposals and sync committee messages. This also, by design, allows a validator to not participate at all in honest sync committee messages but solely participate in dishonest sync committee messages.</p> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>BLOCK_STATE_ROOT_INDEX</code></td><td><code>get_generalized_index(BeaconBlock, 'state_root')</code> (= 11)</td></tr> <tr><td><code>STATE_BLOCK_ROOTS_INDEX</code></td><td><code>get_generalized_index(BeaconState, 'block_roots')</code> (= 37)</td></tr> <tr><td><code>STATE_HISTORICAL_ROOTS_INDEX</code></td><td><code>get_generalized_index(BeaconState, 'historical_roots')</code> (= 39)</td></tr> <tr><td><code>HISTORICAL_BATCH_BLOCK_ROOTS_INDEX</code></td><td><code>get_generalized_index(HistoricalBatch, 'block_roots')</code> (= 2)</td></tr> </tbody></table> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> SyncCommitteeSlashingEvidence</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> attested_header</span><span>:</span><span> BeaconBlockHeader</span></span> <span class="giallo-l"><span> next_sync_committee</span><span>:</span><span> SyncCommittee</span></span> <span class="giallo-l"><span> next_sync_committee_branch</span><span>:</span><span> Vector</span><span>[</span><span>Root</span><span>,</span><span> floorlog2</span><span>(</span><span class="z-constant">NEXT_SYNC_COMMITTEE_INDEX</span><span>)</span><span>]</span></span> <span class="giallo-l"><span> finalized_header</span><span>:</span><span> BeaconBlockHeader</span></span> <span class="giallo-l"><span> finality_branch</span><span>:</span><span> Vector</span><span>[</span><span>Root</span><span>,</span><span> floorlog2</span><span>(</span><span class="z-constant">FINALIZED_ROOT_INDEX</span><span>)</span><span>]</span></span> <span class="giallo-l"><span> sync_aggregate</span><span>:</span><span> SyncAggregate</span></span> <span class="giallo-l"><span> signature_slot</span><span>:</span><span> Slot</span></span> <span class="giallo-l"><span> sync_committee_pubkeys</span><span>:</span><span> Vector</span><span>[</span><span>BLSPubkey</span><span>,</span><span class="z-constant"> SYNC_COMMITTEE_SIZE</span><span>]</span></span> <span class="giallo-l"><span> actual_finalized_block_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> actual_finalized_branch</span><span>:</span><span> List</span><span>[</span><span>Root</span><span>,</span><span> (</span></span> <span class="giallo-l"><span> floorlog2</span><span>(</span><span class="z-constant">BLOCK_STATE_ROOT_INDEX</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> floorlog2</span><span>(</span><span class="z-constant">STATE_HISTORICAL_ROOTS_INDEX</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span class="z-keyword"> +</span><span> floorlog2</span><span>(</span><span class="z-constant">HISTORICAL_ROOTS_LIMIT</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span> floorlog2</span><span>(</span><span class="z-constant">HISTORICAL_BATCH_BLOCK_ROOTS_INDEX</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span class="z-keyword"> +</span><span> floorlog2</span><span>(</span><span class="z-constant">SLOTS_PER_HISTORICAL_ROOT</span><span>)</span><span>)</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> SyncCommitteeSlashing</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> slashable_validators</span><span>:</span><span> List</span><span>[</span><span>ValidatorIndex</span><span>,</span><span class="z-constant"> SYNC_COMMITTEE_SIZE</span><span>]</span></span> <span class="giallo-l"><span> evidence_1</span><span>:</span><span> SyncCommitteeSlashingEvidence</span></span> <span class="giallo-l"><span> evidence_2</span><span>:</span><span> SyncCommitteeSlashingEvidence</span></span> <span class="giallo-l"><span> recent_finalized_block_root</span><span>:</span><span> Root</span></span> <span class="giallo-l"><span> recent_finalized_slot</span><span>:</span><span> Slot</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> sync_committee_slashing_evidence_has_sync_committee</span><span>(</span><span class="z-variable z-parameter z-function">evidence</span><span>:</span><span> SyncCommitteeSlashingEvidence</span><span>)</span><span> -&gt;</span><span class="z-support"> bool</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> evidence</span><span>.</span><span>next_sync_committee_branch</span><span class="z-keyword"> !=</span><span> [</span><span>Root</span><span>(</span><span>)</span><span class="z-keyword"> for</span><span> _</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>floorlog2</span><span>(</span><span class="z-constant">NEXT_SYNC_COMMITTEE_INDEX</span><span>)</span><span>)</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> sync_committee_slashing_evidence_has_finality</span><span>(</span><span class="z-variable z-parameter z-function">evidence</span><span>:</span><span> SyncCommitteeSlashingEvidence</span><span>)</span><span> -&gt;</span><span class="z-support"> bool</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> evidence</span><span>.</span><span>finality_branch</span><span class="z-keyword"> !=</span><span> [</span><span>Root</span><span>(</span><span>)</span><span class="z-keyword"> for</span><span> _</span><span class="z-keyword"> in</span><span class="z-support"> range</span><span>(</span><span>floorlog2</span><span>(</span><span class="z-constant">FINALIZED_ROOT_INDEX</span><span>)</span><span>)</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> is_valid_sync_committee_slashing_evidence</span><span>(</span><span class="z-variable z-parameter z-function">evidence</span><span>:</span><span> SyncCommitteeSlashingEvidence</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> recent_finalized_block_root</span><span>:</span><span> Root</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> recent_finalized_slot</span><span>:</span><span> Slot</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> genesis_validators_root</span><span>:</span><span> Root</span><span>)</span><span> -&gt;</span><span class="z-support"> bool</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify sync committee has sufficient participants</span></span> <span class="giallo-l"><span> sync_aggregate</span><span class="z-keyword"> =</span><span> evidence</span><span>.</span><span>sync_aggregate</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> sum</span><span>(</span><span>sync_aggregate</span><span>.</span><span>sync_committee_bits</span><span>)</span><span class="z-keyword"> &lt;</span><span class="z-constant"> MIN_SYNC_COMMITTEE_PARTICIPANTS</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify that the `finality_branch`, if present, confirms `finalized_header`</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> to match the finalized checkpoint root saved in the state of `attested_header`.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Note that the genesis finalized checkpoint root is represented as a zero hash.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> sync_committee_slashing_evidence_has_finality</span><span>(</span><span>evidence</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence</span><span>.</span><span>actual_finalized_block_root</span><span class="z-keyword"> !=</span><span> Root</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence</span><span>.</span><span>finalized_header</span><span class="z-keyword"> !=</span><span> BeaconBlockHeader</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span><span class="z-keyword"> ==</span><span class="z-constant"> GENESIS_SLOT</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence</span><span>.</span><span>actual_finalized_block_root</span><span class="z-keyword"> !=</span><span> Root</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence</span><span>.</span><span>finalized_header</span><span class="z-keyword"> !=</span><span> BeaconBlockHeader</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span> finalized_root</span><span class="z-keyword"> =</span><span> Root</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> finalized_root</span><span class="z-keyword"> =</span><span> hash_tree_root</span><span>(</span><span>evidence</span><span>.</span><span>finalized_header</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_valid_merkle_branch</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> leaf</span><span class="z-keyword">=</span><span>finalized_root</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> branch</span><span class="z-keyword">=</span><span>evidence</span><span>.</span><span>finality_branch</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> depth</span><span class="z-keyword">=</span><span>floorlog2</span><span>(</span><span class="z-constant">FINALIZED_ROOT_INDEX</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> index</span><span class="z-keyword">=</span><span>get_subtree_index</span><span>(</span><span class="z-constant">FINALIZED_ROOT_INDEX</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> root</span><span class="z-keyword">=</span><span>evidence</span><span>.</span><span>attested_header</span><span>.</span><span>state_root</span><span>,</span></span> <span class="giallo-l"><span> )</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify that the `next_sync_committee`, if present, actually is the next sync committee saved in the</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> state of the `attested_header`</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> sync_committee_slashing_evidence_has_sync_committee</span><span>(</span><span>evidence</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence</span><span>.</span><span>next_sync_committee</span><span class="z-keyword"> !=</span><span> SyncCommittee</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_valid_merkle_branch</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> leaf</span><span class="z-keyword">=</span><span>hash_tree_root</span><span>(</span><span>evidence</span><span>.</span><span>next_sync_committee</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> branch</span><span class="z-keyword">=</span><span>evidence</span><span>.</span><span>next_sync_committee_branch</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> depth</span><span class="z-keyword">=</span><span>floorlog2</span><span>(</span><span class="z-constant">NEXT_SYNC_COMMITTEE_INDEX</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> index</span><span class="z-keyword">=</span><span>get_subtree_index</span><span>(</span><span class="z-constant">NEXT_SYNC_COMMITTEE_INDEX</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> root</span><span class="z-keyword">=</span><span>evidence</span><span>.</span><span>attested_header</span><span>.</span><span>state_root</span><span>,</span></span> <span class="giallo-l"><span> )</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify that the `actual_finalized_block_root`, if present, is confirmed by `actual_finalized_branch`</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> to be the block root at slot `finalized_header.slot` relative to `recent_finalized_block_root`</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> recent_finalized_block_root</span><span class="z-keyword"> ==</span><span> Root</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence</span><span>.</span><span>actual_finalized_block_root</span><span class="z-keyword"> !=</span><span> Root</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence</span><span>.</span><span>actual_finalized_block_root</span><span class="z-keyword"> ==</span><span> Root</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>evidence</span><span>.</span><span>actual_finalized_branch</span><span>)</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> finalized_slot</span><span class="z-keyword"> =</span><span> evidence</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> recent_finalized_slot</span><span class="z-keyword"> &lt;</span><span> finalized_slot</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span> distance</span><span class="z-keyword"> =</span><span> recent_finalized_slot</span><span class="z-keyword"> -</span><span> finalized_slot</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> distance</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> gindex</span><span class="z-keyword"> =</span><span> GeneralizedIndex</span><span>(</span><span class="z-constant">1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> gindex</span><span class="z-keyword"> =</span><span class="z-constant"> BLOCK_STATE_ROOT_INDEX</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> distance</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> SLOTS_PER_HISTORICAL_ROOT</span><span>:</span></span> <span class="giallo-l"><span> gindex</span><span class="z-keyword"> =</span><span> (</span><span>gindex</span><span class="z-keyword"> &lt;&lt;</span><span> floorlog2</span><span>(</span><span class="z-constant">STATE_BLOCK_ROOTS_INDEX</span><span>)</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> STATE_BLOCK_ROOTS_INDEX</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> gindex</span><span class="z-keyword"> =</span><span> (</span><span>gindex</span><span class="z-keyword"> &lt;&lt;</span><span> floorlog2</span><span>(</span><span class="z-constant">STATE_HISTORICAL_ROOTS_INDEX</span><span>)</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> STATE_HISTORICAL_ROOTS_INDEX</span></span> <span class="giallo-l"><span> gindex</span><span class="z-keyword"> =</span><span> (</span><span>gindex</span><span class="z-keyword"> &lt;&lt;</span><span> uint64</span><span>(</span><span class="z-constant">1</span><span>)</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 0</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> `mix_in_length`</span></span> <span class="giallo-l"><span> historical_batch_index</span><span class="z-keyword"> =</span><span> finalized_slot</span><span class="z-keyword"> //</span><span class="z-constant"> SLOTS_PER_HISTORICAL_ROOT</span></span> <span class="giallo-l"><span> gindex</span><span class="z-keyword"> =</span><span> (</span><span>gindex</span><span class="z-keyword"> &lt;&lt;</span><span> floorlog2</span><span>(</span><span class="z-constant">HISTORICAL_ROOTS_LIMIT</span><span>)</span><span>)</span><span class="z-keyword"> +</span><span> historical_batch_index</span></span> <span class="giallo-l"><span> gindex</span><span class="z-keyword"> =</span><span> (</span><span>gindex</span><span class="z-keyword"> &lt;&lt;</span><span> floorlog2</span><span>(</span><span class="z-constant">HISTORICAL_BATCH_BLOCK_ROOTS_INDEX</span><span>)</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> HISTORICAL_BATCH_BLOCK_ROOTS_INDEX</span></span> <span class="giallo-l"><span> gindex</span><span class="z-keyword"> =</span><span> (</span><span>gindex</span><span class="z-keyword"> &lt;&lt;</span><span> uint64</span><span>(</span><span class="z-constant">1</span><span>)</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 0</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> `mix_in_length`</span></span> <span class="giallo-l"><span> block_root_index</span><span class="z-keyword"> =</span><span> finalized_slot</span><span class="z-keyword"> %</span><span class="z-constant"> SLOTS_PER_HISTORICAL_ROOT</span></span> <span class="giallo-l"><span> gindex</span><span class="z-keyword"> =</span><span> (</span><span>gindex</span><span class="z-keyword"> &lt;&lt;</span><span> floorlog2</span><span>(</span><span class="z-constant">SLOTS_PER_HISTORICAL_ROOT</span><span>)</span><span>)</span><span class="z-keyword"> +</span><span> block_root_index</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-support"> len</span><span>(</span><span>evidence</span><span>.</span><span>actual_finalized_branch</span><span>)</span><span class="z-keyword"> !=</span><span> floorlog2</span><span>(</span><span>gindex</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_valid_merkle_branch</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> leaf</span><span class="z-keyword">=</span><span>evidence</span><span>.</span><span>actual_finalized_block_root</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> branch</span><span class="z-keyword">=</span><span>evidence</span><span>.</span><span>actual_finalized_branch</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> depth</span><span class="z-keyword">=</span><span>floorlog2</span><span>(</span><span>gindex</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> index</span><span class="z-keyword">=</span><span>get_subtree_index</span><span>(</span><span>gindex</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> root</span><span class="z-keyword">=</span><span>recent_finalized_block_root</span><span>,</span></span> <span class="giallo-l"><span> )</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Verify sync committee aggregate signature</span></span> <span class="giallo-l"><span> sync_committee_pubkeys</span><span class="z-keyword"> =</span><span> evidence</span><span>.</span><span>sync_committee_pubkeys</span></span> <span class="giallo-l"><span> participant_pubkeys</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span> pubkey</span><span class="z-keyword"> for</span><span> (</span><span>bit</span><span>,</span><span> pubkey</span><span>)</span><span class="z-keyword"> in</span><span class="z-support"> zip</span><span>(</span><span>sync_aggregate</span><span>.</span><span>sync_committee_bits</span><span>,</span><span> sync_committee_pubkeys</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> bit</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> fork_version</span><span class="z-keyword"> =</span><span> compute_fork_version</span><span>(</span><span>compute_epoch_at_slot</span><span>(</span><span>evidence</span><span>.</span><span>signature_slot</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> domain</span><span class="z-keyword"> =</span><span> compute_domain</span><span>(</span><span class="z-constant">DOMAIN_SYNC_COMMITTEE</span><span>,</span><span> fork_version</span><span>,</span><span> genesis_validators_root</span><span>)</span></span> <span class="giallo-l"><span> signing_root</span><span class="z-keyword"> =</span><span> compute_signing_root</span><span>(</span><span>evidence</span><span>.</span><span>attested_header</span><span>,</span><span> domain</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> bls</span><span>.</span><span>FastAggregateVerify</span><span>(</span><span>participant_pubkeys</span><span>,</span><span> signing_root</span><span>,</span><span> sync_aggregate</span><span>.</span><span>sync_committee_signature</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> process_sync_committee_slashing</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> BeaconState</span><span>,</span><span class="z-variable z-parameter z-function"> sync_committee_slashing</span><span>:</span><span> SyncCommitteeSlashing</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> is_slashable</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check that evidence is ordered descending by `attested_header.slot` and is not from the future</span></span> <span class="giallo-l"><span> evidence_1</span><span class="z-keyword"> =</span><span> sync_committee_slashing</span><span>.</span><span>evidence_1</span></span> <span class="giallo-l"><span> evidence_2</span><span class="z-keyword"> =</span><span> sync_committee_slashing</span><span>.</span><span>evidence_2</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> state</span><span>.</span><span>slot</span><span class="z-keyword"> &gt;=</span><span> evidence_1</span><span>.</span><span>signature_slot</span><span class="z-keyword"> &gt;</span><span> evidence_1</span><span>.</span><span>attested_header</span><span>.</span><span>slot</span><span class="z-keyword"> &gt;=</span><span> evidence_1</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> state</span><span>.</span><span>slot</span><span class="z-keyword"> &gt;=</span><span> evidence_2</span><span>.</span><span>signature_slot</span><span class="z-keyword"> &gt;</span><span> evidence_2</span><span>.</span><span>attested_header</span><span>.</span><span>slot</span><span class="z-keyword"> &gt;=</span><span> evidence_2</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> evidence_1</span><span>.</span><span>attested_header</span><span>.</span><span>slot</span><span class="z-keyword"> &gt;=</span><span> evidence_2</span><span>.</span><span>attested_header</span><span>.</span><span>slot</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Only conflicting data among the current and previous sync committee period is slashable;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> on new periods, the sync committee initially signs blocks in a previous sync committee period.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This allows a validator synced to a malicious checkpoint to contribute again in a future period</span></span> <span class="giallo-l"><span> evidence_1_attested_period</span><span class="z-keyword"> =</span><span> compute_sync_committee_period_at_slot</span><span>(</span><span>evidence_1</span><span>.</span><span>attested_header</span><span>.</span><span>slot</span><span>)</span></span> <span class="giallo-l"><span> evidence_2_attested_period</span><span class="z-keyword"> =</span><span> compute_sync_committee_period_at_slot</span><span>(</span><span>evidence_2</span><span>.</span><span>attested_header</span><span>.</span><span>slot</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> evidence_1_attested_period</span><span class="z-keyword"> &lt;=</span><span> evidence_2_attested_period</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> It is not allowed to sign conflicting `attested_header` for a given slot</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence_1</span><span>.</span><span>attested_header</span><span>.</span><span>slot</span><span class="z-keyword"> ==</span><span> evidence_2</span><span>.</span><span>attested_header</span><span>.</span><span>slot</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence_1</span><span>.</span><span>attested_header</span><span class="z-keyword"> !=</span><span> evidence_2</span><span>.</span><span>attested_header</span><span>:</span></span> <span class="giallo-l"><span> is_slashable</span><span class="z-keyword"> =</span><span class="z-constant"> True</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> It is not allowed to sign conflicting finalized `next_sync_committee`</span></span> <span class="giallo-l"><span> evidence_1_finalized_period</span><span class="z-keyword"> =</span><span> compute_sync_committee_period_at_slot</span><span>(</span><span>evidence_1</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span><span>)</span></span> <span class="giallo-l"><span> evidence_2_finalized_period</span><span class="z-keyword"> =</span><span> compute_sync_committee_period_at_slot</span><span>(</span><span>evidence_2</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span> evidence_1_attested_period</span><span class="z-keyword"> ==</span><span> evidence_2_attested_period</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> evidence_1_finalized_period</span><span class="z-keyword"> ==</span><span> evidence_1_attested_period</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> evidence_2_finalized_period</span><span class="z-keyword"> ==</span><span> evidence_2_attested_period</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> sync_committee_slashing_evidence_has_finality</span><span>(</span><span>evidence_1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> sync_committee_slashing_evidence_has_finality</span><span>(</span><span>evidence_2</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> sync_committee_slashing_evidence_has_sync_committee</span><span>(</span><span>evidence_1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> sync_committee_slashing_evidence_has_sync_committee</span><span>(</span><span>evidence_2</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> evidence_1</span><span>.</span><span>next_sync_committee</span><span class="z-keyword"> !=</span><span> evidence_2</span><span>.</span><span>next_sync_committee</span><span>:</span></span> <span class="giallo-l"><span> is_slashable</span><span class="z-keyword"> =</span><span class="z-constant"> True</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> It is not allowed to sign a non-linear finalized history</span></span> <span class="giallo-l"><span> recent_finalized_slot</span><span class="z-keyword"> =</span><span> sync_committee_slashing</span><span>.</span><span>recent_finalized_slot</span></span> <span class="giallo-l"><span> recent_finalized_block_root</span><span class="z-keyword"> =</span><span> sync_committee_slashing</span><span>.</span><span>recent_finalized_block_root</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span class="z-keyword"> not</span><span> sync_committee_slashing_evidence_has_finality</span><span>(</span><span>evidence_1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> or</span><span class="z-keyword"> not</span><span> sync_committee_slashing_evidence_has_finality</span><span>(</span><span>evidence_2</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> recent_finalized_block_root</span><span class="z-keyword"> ==</span><span> Root</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> recent_finalized_block_root</span><span class="z-keyword"> ==</span><span> Root</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> recent_finalized_slot</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Merkle proofs may be included to indicate that `finalized_header` does not match</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> the `actual_finalized_block_root` relative to a given `recent_finalized_block_root`.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The finalized history is linear. Therefore, a mismatch indicates signing on an unrelated chain.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Note that it is not slashable to sign solely an alternate history, as long as it is consistent.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> This allows a validator synced to a malicious checkpoint to contribute again in a future period</span></span> <span class="giallo-l"><span> linear_1</span><span class="z-keyword"> =</span><span> (</span><span>evidence_1</span><span>.</span><span>actual_finalized_block_root</span><span class="z-keyword"> ==</span><span> hash_tree_root</span><span>(</span><span>evidence_1</span><span>.</span><span>finalized_header</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> linear_2</span><span class="z-keyword"> =</span><span> (</span><span>evidence_2</span><span>.</span><span>actual_finalized_block_root</span><span class="z-keyword"> ==</span><span> hash_tree_root</span><span>(</span><span>evidence_2</span><span>.</span><span>finalized_header</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-keyword"> not</span><span> linear_1</span><span class="z-keyword"> or</span><span class="z-keyword"> not</span><span> linear_2</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> linear_1</span><span class="z-keyword"> or</span><span> linear_2</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Do not slash on signing solely an alternate history</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> `actual_finalized_branch` may be rooted in the provided `finalized_header` with highest slot</span></span> <span class="giallo-l"><span> rooted_in_evidence_1</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> evidence_1</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span><span class="z-keyword"> &gt;=</span><span> evidence_2</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> recent_finalized_slot</span><span class="z-keyword"> ==</span><span> evidence_1</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> recent_finalized_block_root</span><span class="z-keyword"> ==</span><span> evidence_1</span><span>.</span><span>actual_finalized_block_root</span><span class="z-keyword"> and</span><span> linear_1</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> rooted_in_evidence_2</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> evidence_2</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span><span class="z-keyword"> &gt;=</span><span> evidence_1</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> recent_finalized_slot</span><span class="z-keyword"> ==</span><span> evidence_2</span><span>.</span><span>finalized_header</span><span>.</span><span>slot</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> recent_finalized_block_root</span><span class="z-keyword"> ==</span><span> evidence_2</span><span>.</span><span>actual_finalized_block_root</span><span class="z-keyword"> and</span><span> linear_2</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Alternatively, if evidence about non-linearity cannot be obtained directly from an attack,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> it can be proven that one of the `finalized_header` is part of the canonical finalized chain</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> that our beacon node is synced to, while the other `finalized_header` is unrelated.</span></span> <span class="giallo-l"><span> rooted_in_canonical</span><span class="z-keyword"> =</span><span> (</span></span> <span class="giallo-l"><span> recent_finalized_slot</span><span class="z-keyword"> &lt;</span><span> state</span><span>.</span><span>slot</span><span class="z-keyword"> &lt;=</span><span> recent_finalized_slot</span><span class="z-keyword"> +</span><span class="z-constant"> SLOTS_PER_HISTORICAL_ROOT</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> recent_finalized_slot</span><span class="z-keyword"> &lt;=</span><span> compute_start_slot_at_epoch</span><span>(</span><span>state</span><span>.</span><span>finalized_checkpoint</span><span>.</span><span>epoch</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> recent_finalized_block_root</span><span class="z-keyword"> ==</span><span> state</span><span>.</span><span>block_roots</span><span>[</span><span>recent_finalized_slot</span><span class="z-keyword"> %</span><span class="z-constant"> SLOTS_PER_HISTORICAL_ROOT</span><span>]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> rooted_in_evidence_1</span><span class="z-keyword"> or</span><span> rooted_in_evidence_2</span><span class="z-keyword"> or</span><span> rooted_in_canonical</span></span> <span class="giallo-l"><span> is_slashable</span><span class="z-keyword"> =</span><span class="z-constant"> True</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> is_slashable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check that slashable validators are sorted, known, and participated in both signatures</span></span> <span class="giallo-l"><span> will_slash_any</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span> sync_aggregate_1</span><span class="z-keyword"> =</span><span> evidence_1</span><span>.</span><span>sync_aggregate</span></span> <span class="giallo-l"><span> sync_aggregate_2</span><span class="z-keyword"> =</span><span> evidence_2</span><span>.</span><span>sync_aggregate</span></span> <span class="giallo-l"><span> sync_committee_pubkeys_1</span><span class="z-keyword"> =</span><span> evidence_1</span><span>.</span><span>sync_committee_pubkeys</span></span> <span class="giallo-l"><span> sync_committee_pubkeys_2</span><span class="z-keyword"> =</span><span> evidence_2</span><span>.</span><span>sync_committee_pubkeys</span></span> <span class="giallo-l"><span> participant_pubkeys_1</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span> pubkey</span><span class="z-keyword"> for</span><span> (</span><span>bit</span><span>,</span><span> pubkey</span><span>)</span><span class="z-keyword"> in</span><span class="z-support"> zip</span><span>(</span><span>sync_aggregate_1</span><span>.</span><span>sync_committee_bits</span><span>,</span><span> sync_committee_pubkeys_1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> bit</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> participant_pubkeys_2</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span> pubkey</span><span class="z-keyword"> for</span><span> (</span><span>bit</span><span>,</span><span> pubkey</span><span>)</span><span class="z-keyword"> in</span><span class="z-support"> zip</span><span>(</span><span>sync_aggregate_2</span><span>.</span><span>sync_committee_bits</span><span>,</span><span> sync_committee_pubkeys_2</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> bit</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> slashable_validators</span><span class="z-keyword"> =</span><span> sync_committee_slashing</span><span>.</span><span>slashable_validators</span></span> <span class="giallo-l"><span> num_validators</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>state</span><span>.</span><span>validators</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> i</span><span>,</span><span> index</span><span class="z-keyword"> in</span><span class="z-support"> enumerate</span><span>(</span><span>slashable_validators</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> (</span></span> <span class="giallo-l"><span> index</span><span class="z-keyword"> &lt;</span><span> num_validators</span></span> <span class="giallo-l"><span class="z-keyword"> and</span><span> (</span><span>i</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span class="z-keyword"> or</span><span> index</span><span class="z-keyword"> &gt;</span><span> slashable_validators</span><span>[</span><span>i</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>index</span><span>]</span><span>.</span><span>pubkey</span><span class="z-keyword"> in</span><span> participant_pubkeys_1</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> state</span><span>.</span><span>validators</span><span>[</span><span>index</span><span>]</span><span>.</span><span>pubkey</span><span class="z-keyword"> in</span><span> participant_pubkeys_2</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> is_slashable_validator</span><span>(</span><span>state</span><span>.</span><span>validators</span><span>[</span><span>index</span><span>]</span><span>,</span><span> get_current_epoch</span><span>(</span><span>state</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> will_slash_any</span><span class="z-keyword"> =</span><span class="z-constant"> True</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> will_slash_any</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Validate evidence, including signatures</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> is_valid_sync_committee_slashing_evidence</span><span>(</span></span> <span class="giallo-l"><span> evidence_1</span><span>,</span></span> <span class="giallo-l"><span> recent_finalized_block_root</span><span>,</span></span> <span class="giallo-l"><span> recent_finalized_slot</span><span>,</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>genesis_validators_root</span><span>,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span> is_valid_sync_committee_slashing_evidence</span><span>(</span></span> <span class="giallo-l"><span> evidence_2</span><span>,</span></span> <span class="giallo-l"><span> recent_finalized_block_root</span><span>,</span></span> <span class="giallo-l"><span> recent_finalized_slot</span><span>,</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>genesis_validators_root</span><span>,</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Perform slashing</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> index</span><span class="z-keyword"> in</span><span> slashable_validators</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> is_slashable_validator</span><span>(</span><span>state</span><span>.</span><span>validators</span><span>[</span><span>index</span><span>]</span><span>,</span><span> get_current_epoch</span><span>(</span><span>state</span><span>)</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> slash_validator</span><span>(</span><span>state</span><span>,</span><span> index</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="what-s-the-use-case">What's the use case?</h3> <p>Without a slashing, the light client sync protocol is somewhat limited. While wallet applications may benefit from it (the risk being, that incorrect data is displayed) and new beacon nodes may use it for accelerating chain synchronization, other interesting use cases such as bridges, token distributions or other systems requiring proofs depend on the mechanism providing higher security guarantees.</p> <p>By making attacks by sync committee members slashable, a sufficiently high deterrent could be provided. A majority of the sync committee would have to be bribed to succeed in an attack even in the most simple cases, representing a sizable slashable balance.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork as it introduces new consensus validation rules.</p> <p>Supporting infrastructure may be introduced separately once the consensus validation rules are in place, including but not limited to:</p> <ul> <li>Slashing protection DB updates, to guarantee that honest validators cannot be slashed on reorgs</li> <li>Validator client / remote signer APIs, to pass along information related to slashing protection</li> <li>libp2p meshes for exchanging slashing evidence between beacon nodes</li> <li>Slasher, to monitor potential targets and construct slashing evidence</li> <li>Beacon APIs, to submit and monitor slashing evidence</li> </ul> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-03-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status https://wg-eips.ritovision.com/7658/

Mechanism for beacon nodes for syncing historical light client data

<h2 id="abstract">Abstract</h2> <p>This EIP defines a mechanism for syncing <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/altair/light-client/full-node.md">light client data</a> between beacon nodes.</p> <h2 id="motivation">Motivation</h2> <p><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/altair/light-client/full-node.md">Light client data</a> is collected by beacon nodes to assist <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/altair/light-client/light-client.md">light clients</a> to sync with the network. The <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/altair/light-client/sync-protocol.md">sync protocol</a> defines a mechanism to sync forward in time. However, it cannot be used to sync backward.</p> <p>Collecting light client data is challenging because beacon nodes need to have access to the corresponding <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/phase0/beacon-chain.md#beaconstate"><code>BeaconState</code></a> and <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/phase0/beacon-chain.md#signedbeaconblock"><code>SignedBeaconBlock</code></a>. <code>BeaconState</code> objects are not available before the initially synced checkpoint state, and <code>SignedBeaconBlock</code> objects have a limited retention period on libp2p.</p> <p>Furthermore, each <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/altair/beacon-chain.md#get_next_sync_committee">sync committee period</a> consists of <code>EPOCHS_PER_SYNC_COMMITTEE_PERIOD * SLOTS_PER_EPOCH</code> slots. To support archive services such as Portal network to provide a consistent view regardless of backend, it is necessary to choose a single canonical slot for which to derive the representative light client data for that period. Such data should be verifiable to be canonical and optimal in a decentralized and independent manner.</p> <p>To support light client data backfill, this EIP proposes to track the canonical and optimal <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/altair/beacon-chain.md#syncaggregate"><code>SyncAggregate</code></a> in the <code>BeaconState</code>. This minimal addition allows proving that derived <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/altair/light-client/sync-protocol.md#lightclientupdate"><code>LightClientUpdate</code></a> and <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/altair/light-client/sync-protocol.md#lightclientbootstrap"><code>LightClientBootstrap</code></a> are also canonical and optimal.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="containers">Containers</h3> <h4 id="new-containers">New containers</h4> <h5 id="syncdata"><code>SyncData</code></h5> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> SyncData</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Sync committee aggregate signature</span></span> <span class="giallo-l"><span> sync_aggregate</span><span>:</span><span> SyncAggregate</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Slot at which the aggregate signature was created</span></span> <span class="giallo-l"><span> signature_slot</span><span>:</span><span> Slot</span></span></code></pre><h4 id="extended-containers">Extended containers</h4> <h5 id="beaconstate"><code>BeaconState</code></h5> <p>New fields are added to the end of <code>BeaconState</code> from the activating fork onward to track the current and previous sync committee period's best sync data.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> BeaconState</span><span>(</span><span class="z-entity">Container</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Sync history</span></span> <span class="giallo-l"><span> previous_best_sync_data</span><span>:</span><span> SyncData</span></span> <span class="giallo-l"><span> current_best_sync_data</span><span>:</span><span> SyncData</span></span> <span class="giallo-l"><span> parent_block_has_sync_committee_finality</span><span>:</span><span class="z-support"> bool</span></span></code></pre><h3 id="helper-functions">Helper functions</h3> <h4 id="default-sync-data"><code>default_sync_data</code></h4> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> default_sync_data</span><span>(</span><span>)</span><span> -&gt;</span><span> SyncData</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> SyncData</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> sync_aggregate</span><span class="z-keyword">=</span><span>SyncAggregate</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> sync_committee_bits</span><span class="z-keyword">=</span><span>Bitvector</span><span>[</span><span class="z-constant">SYNC_COMMITTEE_SIZE</span><span>]</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> sync_committee_signature</span><span class="z-keyword">=</span><span class="z-constant">G2_POINT_AT_INFINITY</span><span>,</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> signature_slot</span><span class="z-keyword">=</span><span class="z-constant">GENESIS_SLOT</span><span>,</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h3 id="beacon-chain-state-transition-function">Beacon chain state transition function</h3> <h4 id="epoch-processing">Epoch processing</h4> <h5 id="modified-process-sync-committee-updates">Modified <code>process_sync_committee_updates</code></h5> <p>On sync committee boundaries, current period data is moved to previous period. This allows proving that light client data for the previous period is canonical.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> process_sync_committee_updates</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> BeaconState</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> next_epoch</span><span class="z-keyword"> =</span><span> get_current_epoch</span><span>(</span><span>state</span><span>)</span><span class="z-keyword"> +</span><span> Epoch</span><span>(</span><span class="z-constant">1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> next_epoch</span><span class="z-keyword"> %</span><span class="z-constant"> EPOCHS_PER_SYNC_COMMITTEE_PERIOD</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>previous_best_sync_data</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>current_best_sync_data</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>current_best_sync_data</span><span class="z-keyword"> =</span><span> default_sync_data</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>parent_block_has_sync_committee_finality</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span></code></pre><h4 id="block-processing">Block processing</h4> <p>Block processing is extended to track the optimal light client data for the current period. Due to the possibility for empty slots this must be tracked before the block header is overwritten; this allows tracking the exact block after which <code>next_sync_committee</code> becomes finalized.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> process_block</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> BeaconState</span><span>,</span><span class="z-variable z-parameter z-function"> block</span><span>:</span><span> BeaconBlock</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> process_best_sync_data</span><span>(</span><span>state</span><span>,</span><span> block</span><span>)</span></span> <span class="giallo-l"><span> process_block_header</span><span>(</span><span>state</span><span>,</span><span> block</span><span>)</span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><h5 id="new-process-best-sync-data">New <code>process_best_sync_data</code></h5> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> process_best_sync_data</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> BeaconState</span><span>,</span><span class="z-variable z-parameter z-function"> block</span><span>:</span><span> BeaconBlock</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> signature_period</span><span class="z-keyword"> =</span><span> compute_sync_committee_period_at_slot</span><span>(</span><span>block</span><span>.</span><span>slot</span><span>)</span></span> <span class="giallo-l"><span> attested_period</span><span class="z-keyword"> =</span><span> compute_sync_committee_period_at_slot</span><span>(</span><span>state</span><span>.</span><span>latest_block_header</span><span>.</span><span>slot</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Track sync committee finality</span></span> <span class="giallo-l"><span> old_has_sync_committee_finality</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>parent_block_has_sync_committee_finality</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> state</span><span>.</span><span>parent_block_has_sync_committee_finality</span><span>:</span></span> <span class="giallo-l"><span> new_has_sync_committee_finality</span><span class="z-keyword"> =</span><span class="z-constant"> True</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> state</span><span>.</span><span>finalized_checkpoint</span><span>.</span><span>epoch</span><span class="z-keyword"> &lt;</span><span class="z-constant"> ALTAIR_FORK_EPOCH</span><span>:</span></span> <span class="giallo-l"><span> new_has_sync_committee_finality</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> finalized_period</span><span class="z-keyword"> =</span><span> compute_sync_committee_period</span><span>(</span><span>state</span><span>.</span><span>finalized_checkpoint</span><span>.</span><span>epoch</span><span>)</span></span> <span class="giallo-l"><span> new_has_sync_committee_finality</span><span class="z-keyword"> =</span><span> (</span><span>finalized_period</span><span class="z-keyword"> ==</span><span> attested_period</span><span>)</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>parent_block_has_sync_committee_finality</span><span class="z-keyword"> =</span><span> new_has_sync_committee_finality</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Track best sync data</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> attested_period</span><span class="z-keyword"> ==</span><span> signature_period</span><span>:</span></span> <span class="giallo-l"><span> max_active_participants</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>block</span><span>.</span><span>body</span><span>.</span><span>sync_aggregate</span><span>.</span><span>sync_committee_bits</span><span>)</span></span> <span class="giallo-l"><span> new_num_active_participants</span><span class="z-keyword"> =</span><span class="z-support"> sum</span><span>(</span><span>block</span><span>.</span><span>body</span><span>.</span><span>sync_aggregate</span><span>.</span><span>sync_committee_bits</span><span>)</span></span> <span class="giallo-l"><span> old_num_active_participants</span><span class="z-keyword"> =</span><span class="z-support"> sum</span><span>(</span><span>state</span><span>.</span><span>current_best_sync_data</span><span>.</span><span>sync_aggregate</span><span>.</span><span>sync_committee_bits</span><span>)</span></span> <span class="giallo-l"><span> new_has_supermajority</span><span class="z-keyword"> =</span><span> new_num_active_participants</span><span class="z-keyword"> *</span><span class="z-constant"> 3</span><span class="z-keyword"> &gt;=</span><span> max_active_participants</span><span class="z-keyword"> *</span><span class="z-constant"> 2</span></span> <span class="giallo-l"><span> old_has_supermajority</span><span class="z-keyword"> =</span><span> old_num_active_participants</span><span class="z-keyword"> *</span><span class="z-constant"> 3</span><span class="z-keyword"> &gt;=</span><span> max_active_participants</span><span class="z-keyword"> *</span><span class="z-constant"> 2</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> new_has_supermajority</span><span class="z-keyword"> !=</span><span> old_has_supermajority</span><span>:</span></span> <span class="giallo-l"><span> is_better_sync_data</span><span class="z-keyword"> =</span><span> new_has_supermajority</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span class="z-keyword"> not</span><span> new_has_supermajority</span><span class="z-keyword"> and</span><span> new_num_active_participants</span><span class="z-keyword"> !=</span><span> old_num_active_participants</span><span>:</span></span> <span class="giallo-l"><span> is_better_sync_data</span><span class="z-keyword"> =</span><span> new_num_active_participants</span><span class="z-keyword"> &gt;</span><span> old_num_active_participants</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> new_has_sync_committee_finality</span><span class="z-keyword"> !=</span><span> old_has_sync_committee_finality</span><span>:</span></span> <span class="giallo-l"><span> is_better_sync_data</span><span class="z-keyword"> =</span><span> new_has_sync_committee_finality</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> new_num_active_participants</span><span class="z-keyword"> !=</span><span> old_num_active_participants</span><span>:</span></span> <span class="giallo-l"><span> is_better_sync_data</span><span class="z-keyword"> =</span><span> new_num_active_participants</span><span class="z-keyword"> &gt;</span><span> old_num_active_participants</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> is_better_sync_data</span><span class="z-keyword"> =</span><span> block</span><span>.</span><span>slot</span><span class="z-keyword"> &lt;</span><span> state</span><span>.</span><span>current_best_sync_data</span><span>.</span><span>signature_slot</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> is_better_sync_data</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>current_best_sync_data</span><span class="z-keyword"> =</span><span> SyncData</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> sync_aggregate</span><span class="z-keyword">=</span><span>block</span><span>.</span><span>body</span><span>.</span><span>sync_aggregate</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> signature_slot</span><span class="z-keyword">=</span><span>block</span><span>.</span><span>slot</span><span>,</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="how-to-rank-syncaggregate">How to rank <code>SyncAggregate</code>?</h3> <p>The EIP reuses the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/4afe39822c9ad9747e0f5635cca117c18441ec1b/specs/altair/light-client/sync-protocol.md#is_better_update"><code>is_better_update</code></a> function from existing specs.</p> <p>To ensure deterministic selection when participation and finality are equal, implementations MUST break ties by preferring the lower <code>signature_slot</code>; if equal, the existing selection SHOULD be retained.</p> <h3 id="how-could-a-backfill-protocol-use-this">How could a backfill protocol use this?</h3> <p>Once the data is available in the <code>BeaconState</code>, a light client data backfill protocol could be defined that serves, for past periods:</p> <ol> <li>A <code>LightClientUpdate</code> from requested <code>period</code> + 1 that proves that the entirety of <code>period</code> is finalized.</li> <li><code>BeaconState.historical_summaries[period].block_summary_root</code> at (1)'s <code>attested_header.beacon.state_root</code> + Merkle proof.</li> <li>For each epoch's slot 0 block within requested <code>period</code>, the corresponding <code>LightClientHeader</code> + Merkle multi-proof for the block's inclusion into (2)'s <code>block_summary_root</code>.</li> <li>For each of the entries from (3) with <code>beacon.slot</code> within <code>period</code>, the <code>current_sync_committee_branch</code> + Merkle proof for constructing <code>LightClientBootstrap</code>.</li> <li>If (4) is not empty, the requested <code>period</code>'s <code>current_sync_committee</code>.</li> <li>The best <code>LightClientUpdate</code> from <code>period</code>, if one exists, + Merkle proof that its <code>sync_aggregate</code> + <code>signature_slot</code> is selected as the canonical best one in (1)'s <code>attested_header.beacon.state_root</code>.</li> </ol> <p>Only the proof in (6) depends on <code>BeaconState</code> tracking the best light client data. This modification would enshrine the logic of a subset of <code>is_better_update</code>, but does not require adding any <code>LightClientXyz</code> data structures to the <code>BeaconState</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork as it introduces new consensus validation rules.</p> <p>Only light client data following the hard fork can be proven to be canonical and optimal. However, after finalization of the fork transition block, earlier light client data can no longer change and could be locked in using a hash.</p> <h2 id="security-considerations">Security Considerations</h2> <p>None</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-03-10T00:00:00+00:00 2026-02-11T14:49:28+00:00 Qi Zhouhttps://github.com/qizhou Zhiqiang Xuhttps://github.com/zhiqiangxu https://wg-eips.ritovision.com/7650/

Add a precompiled contract that add access lists programmatically

<h2 id="abstract">Abstract</h2> <p>We introduce a new precompiled contract named <code>prefetch</code>, which accepts an <code>accessList</code>.</p> <p>The <code>accessList</code> specifies a list of addresses and local storage keys; these addresses and local storage keys are added into the <code>accessed_addresses</code> and <code>accessed_storage_keys</code> global sets (introduced in <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>). Similar to <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a>, prefetching data through this precompile incurs a gas charge, albeit at a reduced rate compared to accesses made outside of this list.</p> <h2 id="motivation">Motivation</h2> <p>The primary goal of this EIP is to enhance EIP-2930 by enabling contracts to add access lists programmatically. The advantage of implementing this precompile within a contract is the sustained reduction in gas costs for data access operations, leveraging the concurrent computing and IOs that most nodes have.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLOCK_NUMBER</code></td><td><code>TBD</code></td></tr> <tr><td><code>PREFETCH_PRECOMPILE_ADDRESS</code></td><td><code>TBD</code></td></tr> <tr><td><code>CONCURRENCY</code></td><td><code>TBD</code></td></tr> </tbody></table> <p>As of <code>FORK_BLOCK_NUMBER</code>, a new precompile is deployed at <code>PREFETCH_PRECOMPILE_ADDRESS</code>. The encoding of the precompile input is the following:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[32 bytes for local storage key length n][n * 32 bytes local storage keys][32 bytes for address length m][m * 32 bytes addresses]</span></span></code></pre> <p>At the beginning of the call, we will charge <code>2100 * (N + CONCURRENCY - 1) // CONCURRENCY + 2600 * (M + CONCURRENCY - 1) // CONCURRENCY</code>, where <code>//</code> is the integer division operator, <code>N</code> is the number of local storage keys not in <code>accessed_storage_keys</code> global set, and <code>M</code> is the number of addresses not in <code>accessed_addresses</code> global set. The client should concurrently read the keys and addresses and put the keys and addresses into the <code>accessed_addresses</code> and <code>accessed_storage_keys</code> global sets. The following read cost of the storage keys and addresses obeys <code>WARM_STORAGE_READ_COST</code> as defined in <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>.</p> <h3 id="examples">Examples</h3> <p>Using UniswapV2 <code>swap()</code> function as an example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> // this low-level function should be called from a contract which performs important safety checks</span></span> <span class="giallo-l"><span> function swap(uint amount0Out, uint amount1Out, address to, bytes calldata data) external lock {</span></span> <span class="giallo-l"><span> prefetch {</span></span> <span class="giallo-l"><span> token0.slot,</span></span> <span class="giallo-l"><span> token1.slot,</span></span> <span class="giallo-l"><span> reserve0.slot,</span></span> <span class="giallo-l"><span> price0CumulativeLast.slot,</span></span> <span class="giallo-l"><span> price1CumulativeLast.slot,</span></span> <span class="giallo-l"><span> } // add the storage keys `accessed_storage_keys`</span></span> <span class="giallo-l"><span> prefetch {</span></span> <span class="giallo-l"><span> token0,</span></span> <span class="giallo-l"><span> token1,</span></span> <span class="giallo-l"><span> } // add the contracts of token0 and token1 to `accessed_addresses`</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="charging-less-for-accesses-in-the-access-list">Charging less for accesses in the access list</h3> <p>Similar to EIP-2930, we encourage contract developers to use the <code>prefetch</code> precompile as much as possible, especially assuming the nodes have some decent concurrent capabilities (e.g., some cores and IO bandwidth).</p> <h3 id="allowing-duplicates">Allowing duplicates</h3> <p>Similar to EIP-2930, we allow duplicates in the list to maximize simplicity.</p> <h3 id="no-storage-keys-for-external-contract">No storage keys for external contract</h3> <p>Unlike EIP-2930, the <code>prefetch</code> precompile only accepts local storage keys and addresses. Prefetching the data of the storage keys of external contracts assumes that the contract knows the storage layout of an external contract, which may not be a good practice. To better employ the concurrency of a node, the precompile may accept a list of static calls of external contracts together with the calldata. This work may be done in the future EIP.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>If the EIP is not yet implemented, a contract calling the precompile should result in no operation.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No security considerations were found.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-03-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Cyrus Adkissonhttps://github.com/cyrusadkisson Eirik Ulversøyhttps://github.com/EirikUlversoy https://wg-eips.ritovision.com/7645/

Eliminate ORIGIN tech debt to lay groundwork for account abstraction and close security holes

<h2 id="abstract">Abstract</h2> <p>This EIP proposes aliasing the ORIGIN opcode to the SENDER opcode within the Ethereum Virtual Machine (EVM). The purpose of this change is to move Ethereum closer to enabling account abstraction by harmonizing the treatment of externally owned accounts (EOAs) and smart contracts and to address the security concerns associated with the use of ORIGIN that have and will continue to surface in all or most account abstraction proposals.</p> <h2 id="motivation">Motivation</h2> <p>The ORIGIN opcode in Ethereum returns the address of the account that started the transaction chain, differing from the SENDER (or CALLER) opcode, which returns the address of the direct caller. The use of ORIGIN has been discouraged and deemed deprecated since mid-2016 due to the security problems it introduces, such as susceptibility to phishing attacks and other vulnerabilities where the distinction between the original sender and the immediate sender can be exploited.</p> <p>For instance, if an <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> bundler has tokens or other authority in a smart contract determined by ORIGIN, any of the transactions it bundles can hijack this authority since ORIGIN remains the bundler address throughout each child transaction.</p> <p>More apropos in the current context of EVM evolution, the differentiation between the ORIGIN and SENDER opcodes presents a challenge for all account abstraction efforts, such as those outlined in <a href="https://wg-eips.ritovision.com/7377/">EIP-7377</a> and <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a>, because any move towards account abstraction must address the ORIGIN opcode's role, either by modifying or completely bypassing it. Without addressing this, the ORIGIN opcode stands as a barrier to the evolution of Ethereum's account model towards greater flexibility and functionality.</p> <h2 id="specification">Specification</h2> <p>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>This EIP proposes the alteration of the behavior of the ORIGIN opcode within the Ethereum Virtual Machine (EVM). Currently, the ORIGIN opcode returns the address of the original transaction initiator. Under this EIP, the ORIGIN opcode would, instead, return the same value as the SENDER opcode, which is the address of the immediate sender of the message or transaction.</p> <p>Definition Change: The ORIGIN opcode (0x32) MUST, in all contexts of execution, return the same value as that returned by the SENDER (also known as CALLER) opcode (0x33).</p> <p>EVM Implementation: All Ethereum clients MUST implement the following change to the EVM: Whenever the ORIGIN opcode is called, the value to be pushed onto the stack is the current call's sender address, as if the SENDER opcode was executed instead.</p> <p>Transaction Validation: Transactions MUST be validated as before, with no changes to the transaction structure or processing logic beyond the EVM opcode behavior specified above.</p> <p>Compatibility: Smart contracts relying on the ORIGIN opcode for obtaining the transaction initiator's address MUST be reviewed to ensure they function correctly under the new definition and worked-around or avoided if this EIP introduces breaking changes.</p> <p>Implementers are encouraged to provide feedback on this specification and report any potential issues encountered during the implementation or testing phases.</p> <h2 id="rationale">Rationale</h2> <p>The rationale behind aliasing ORIGIN to SENDER is to:</p> <p>Facilitate Account Abstraction: Elegantly nullify a universal barrier to account abstraction, enabling more flexible and powerful account models in Ethereum.</p> <p>Enhance Security: Eliminate the security vulnerabilities associated with differentiating between the original transaction initiator and the immediate caller.</p> <p>Clean up tech debt and simplify the EVM Model: Reduce the complexity of the EVM's transaction and execution model by removing an outdated and deprecated feature, making future changes easier and safer.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not fully backwards compatible. Contracts relying on the distinction between ORIGIN and SENDER for logic or security will be affected. However, given the longstanding discouragement of ORIGIN's use, the minimal impact of the change, the widespread desire for a future account abstraction solution in the EVM, and the reality that any AA solution will ultimately have to deal with ORIGIN one way or the other, this incompatibility is considered a necessary step forward for Ethereum's development.</p> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>For each CALL, STATICCALL, DELEGATECALL, CALLCODE:</p> <p>Direct - Ensure that, at the target smart contract, ORIGIN and SENDER produce the same value. (For simple no-hop EOA-to-EOA/SCA transactions, this is already the case today.)</p> <p>Multi-hop - Ensure that, at each frame in a multi-hop transaction, ORIGIN and SENDER produce the same value.</p> <h2 id="security-considerations">Security Considerations</h2> <p>By aliasing ORIGIN to SENDER, the specific security vulnerabilities associated with the ORIGIN opcode are addressed and eliminated. Outside the scope of this EIP, it may be wise to ban all use of ORIGIN to eliminate further misunderstanding or misuse. This can be done via tooling changes outside the EVM or, inside the EVM, reverting smart contract deployments that use ORIGIN.</p> <p>For existing misuse of ORIGIN affected negatively by this aliasing to SENDER (of yet a clear example has yet to be identified), it may be necessary to educate users to avoid this problematic legacy code.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-02-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 lightclienthttps://github.com/lightclient kdemehttps://github.com/kdeme https://wg-eips.ritovision.com/7643/

Commit to a single root for all block data before the merge.

<h2 id="abstract">Abstract</h2> <p>Defines an SSZ object for accumulating all pre-PoS data and commit to the historical hashes accumulator's root <code>0xec8e040fd6c557b41ca8ddd38f7e9d58a9281918dc92bdb72342a38fb085e701</code>.</p> <h2 id="motivation">Motivation</h2> <p>There are two main uses we consider for the historical hashes accumulator:</p> <ul> <li>for users who wish to download the pre-PoS data for the execution chain and verify it without executing each block, they may simply compute each block hash, accumulate the epoch records, and then compare the local accumulator root with the expected value.</li> <li>additionally, the accumulator root allows for <code>O(log(n))</code> sized proofs to any pre-PoS block, whereas today to achieve something similar, one must recursively verify the header chain.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="historical-hashes-accumulator">Historical Hashes Accumulator</h3> <p>The historical hashes accumulator commits to the set of pre-merge headers and their associated total difficulty. The format for this data is defined as:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">EPOCH_SIZE</span><span class="z-keyword"> =</span><span class="z-constant"> 8192</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> blocks</span></span> <span class="giallo-l"><span class="z-constant">MAX_HISTORICAL_EPOCHS</span><span class="z-keyword"> =</span><span class="z-constant"> 2048</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> An individual record for a historical header.</span></span> <span class="giallo-l"><span>HeaderRecord</span><span class="z-keyword"> =</span><span> Container</span><span>[</span><span>block_hash</span><span>:</span><span> bytes32</span><span>,</span><span> total_difficulty</span><span>:</span><span> uint256</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> The records of the headers from within a single epoch</span></span> <span class="giallo-l"><span>EpochRecord</span><span class="z-keyword"> =</span><span> List</span><span>[</span><span>HeaderRecord</span><span>,</span><span> max_length</span><span>=</span><span class="z-constant">EPOCH_SIZE</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>HistoricalHashesAccumulator</span><span class="z-keyword"> =</span><span> Container</span><span>[</span></span> <span class="giallo-l"><span> historical_epochs</span><span>:</span><span> List</span><span>[</span><span>bytes32</span><span>,</span><span> max_length</span><span>=</span><span class="z-constant">MAX_HISTORICAL_EPOCHS</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> current_epoch</span><span>:</span><span> EpochRecord</span><span>,</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h3 id="pre-pos-root">Pre-PoS Root</h3> <p>The hash tree root of <code>HistoricalHashesAccumulator</code> for data before block 15537394 is <code>0xec8e040fd6c557b41ca8ddd38f7e9d58a9281918dc92bdb72342a38fb085e701</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="inclusion-of-total-difficulty">Inclusion of total difficulty</h3> <p>The total difficulty allowed so that clients may return the value for specific JSON-RPC methods which support it. It is also useful for verifying the TTD of the final proof-of-work block.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>n/a</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="csv"><span class="giallo-l"><span>epoch,</span><span class="z-keyword">root</span></span> <span class="giallo-l"><span>00000,</span><span class="z-keyword">0x5ec1ffb8c3b146f42606c74ced973dc16ec5a107c0345858c343fc94780b4218</span></span> <span class="giallo-l"><span>00001,</span><span class="z-keyword">0xa5364e9a9bc513c4601f0d62e6b46dbdedf3200bbfae54d6350f46f2c7a01938</span></span> <span class="giallo-l"><span>00002,</span><span class="z-keyword">0x98cbd8a95ae7dc9c1ed823156d0eab9aaffa869f6852cab18ff0083063f27d26</span></span> <span class="giallo-l"><span>00003,</span><span class="z-keyword">0xd8b8a40b8cf6818e1bac871d882e772be0b28d1baaf72374946506d9e6fa7d75</span></span> <span class="giallo-l"><span>00004,</span><span class="z-keyword">0x6e3baba7e324b99ed72d98f0255d25ce66832736550f8b971c12280eac2a0bb8</span></span> <span class="giallo-l"><span>00005,</span><span class="z-keyword">0x5cff5a4b7284b1a4a6cebfcc80d876ab0418f71254d03f91d46a9a1fab49fa09</span></span> <span class="giallo-l"><span>00006,</span><span class="z-keyword">0x678fb79306f84e9d0a4749323dc29934ca59b852fbc7c8d2890eabe8a0cde282</span></span> <span class="giallo-l"><span>00007,</span><span class="z-keyword">0xd9bc682bc5bc63b20a8344407ae12cb17e2085d448f438efa6aa5d522b913a20</span></span> <span class="giallo-l"><span>00008,</span><span class="z-keyword">0x12c9605f2d8d4738f9aa04fbecdbbbc8b77135ebfaa9db399135c14e1ef10bee</span></span> <span class="giallo-l"><span>00009,</span><span class="z-keyword">0xf9e4e8905b214c97bb4ed1f69178d6ecc769e21352885147fce5b671215db2a8</span></span> <span class="giallo-l"><span>00010,</span><span class="z-keyword">0x5f5d4516b7a38929b47ea7334b62b53829b9665d37f752d96c33fad0f7f78583</span></span> <span class="giallo-l"><span>00011,</span><span class="z-keyword">0x30f04eb968efe4079356b873e37f1657984717e60af612ecca95c98226528d54</span></span> <span class="giallo-l"><span>00012,</span><span class="z-keyword">0x5ecb9bf9e193da08c7e7f22abcd50d1b4d3c2b909f980ac1315856cb48ca49cc</span></span> <span class="giallo-l"><span>00013,</span><span class="z-keyword">0xd0175c1ed6e694180c4c161ac7f06a913784daba14dc1d2e926f72def4f7f65d</span></span> <span class="giallo-l"><span>00014,</span><span class="z-keyword">0x4f92d78141b7fa8d6fcef45f9dbc611f858447629eeac2d63bb43d07e6bd1aca</span></span> <span class="giallo-l"><span>00015,</span><span class="z-keyword">0xa47cb8eb7157d56f718a6896c2ee1843a44e3de81b9127e64b78fc38ee382310</span></span> <span class="giallo-l"><span>00016,</span><span class="z-keyword">0x9344d8b785c0e619d0b1b83e5d7b3849d667f1ec0d0d6390d26fa33dd4cb31af</span></span> <span class="giallo-l"><span>00017,</span><span class="z-keyword">0x43963724de4a8917d16d8c6a663c38fcdcf3ce5b89a51bc766dcd0ffd1d5aa32</span></span> <span class="giallo-l"><span>00018,</span><span class="z-keyword">0xefce27b480c92a0e7fec472fe38e87ed9a1c91c3d07324cc2f262de3916a38f6</span></span> <span class="giallo-l"><span>00019,</span><span class="z-keyword">0xf5434352253a7f35d909fb2c383e7cdad65761c509eec24741197b869ebcc212</span></span> <span class="giallo-l"><span>00020,</span><span class="z-keyword">0x0c405203cb7b2e54b910e5d953b5378ff4f0c3bcebef92e7e3a1f240dd6703ee</span></span> <span class="giallo-l"><span>00021,</span><span class="z-keyword">0x20d8f1af038c2777dea9f86fe9e33f14af9e4270ee20adb32e0dddedc4b85236</span></span> <span class="giallo-l"><span>00022,</span><span class="z-keyword">0xb694d8955851f744e44c68fba193f6bc41d1159036531c5f55fac9ce91883695</span></span> <span class="giallo-l"><span>00023,</span><span class="z-keyword">0x11beacba76e467dda23253f104d064b00ab75672ab33cff6097be1c3e8ce7053</span></span> <span class="giallo-l"><span>00024,</span><span class="z-keyword">0xf216a28afb2212269b634b9b44ff327a4a79f261640ff967f7e3283e3a184c70</span></span> <span class="giallo-l"><span>00025,</span><span class="z-keyword">0x987cb6206e5bae4b68ce0eeb6c05ae090d02b7331e47d1705a2a515ac88475aa</span></span> <span class="giallo-l"><span>00026,</span><span class="z-keyword">0x3afd50ff0edf3cae577c42bfc39871f0f0ffe7bdd5ee0b96f7b2e879c9b29994</span></span> <span class="giallo-l"><span>00027,</span><span class="z-keyword">0x28083285c935c0c169ea1406f9830701ff20fde3d0b2a5b83efc1cd13139dccf</span></span> <span class="giallo-l"><span>00028,</span><span class="z-keyword">0x362fc97cbcfa6ab609f1a3f8ca2f8a6e0ac6061c33e84a285a14713cfd73f203</span></span> <span class="giallo-l"><span>00029,</span><span class="z-keyword">0xa0cb99e26e896f5d115914910c4c66fc112ae240bc827acdd564785e738ff29c</span></span> <span class="giallo-l"><span>00030,</span><span class="z-keyword">0x78fc5e8e58e6dd726499295eea1f7f52a31979c6a003d48d4e027d95285e851c</span></span> <span class="giallo-l"><span>00031,</span><span class="z-keyword">0x52306cf9ed840bea9d8c3466bfbed5ffecdfd51107f33d013a487c3b653b3646</span></span> <span class="giallo-l"><span>00032,</span><span class="z-keyword">0xcb4d0c3a2384b890a8acd698da6b9ae6267c5365fcc516391829f7adbae838ee</span></span> <span class="giallo-l"><span>00033,</span><span class="z-keyword">0x0c3781bbc07124e29ff67754bdcf556b20ac4f4ef19ddb004837ec50193ce0bc</span></span> <span class="giallo-l"><span>00034,</span><span class="z-keyword">0xfac9315aa442073b647e71716a7acf1c170e5a0092b69edc2a5634813716592f</span></span> <span class="giallo-l"><span>00035,</span><span class="z-keyword">0x737e07578f0dd5eeebd8313e58cdb59ac705c0ba07d842feace53fa2922c6508</span></span> <span class="giallo-l"><span>00036,</span><span class="z-keyword">0x84c7c1e7c4a8949247953858992012799d323ebcd0fc6cdecf8002f20f2ea7e1</span></span> <span class="giallo-l"><span>00037,</span><span class="z-keyword">0x34d067652cbea843a01e70ba75566b6f174218969dc453c285e59b4f309faee8</span></span> <span class="giallo-l"><span>00038,</span><span class="z-keyword">0x38aaf94c653d619b1a08e7cf9fac72ecc57715bc19ba236c942d400742bc3f16</span></span> <span class="giallo-l"><span>00039,</span><span class="z-keyword">0x4ad4940c51be350c9d8c69f424f01a9e87e42fe6b312afae3f8f7267c62512e5</span></span> <span class="giallo-l"><span>00040,</span><span class="z-keyword">0x4707f60dffab08b6837078ae91316ebe04a275aa19892462521cb6125913d3d7</span></span> <span class="giallo-l"><span>00041,</span><span class="z-keyword">0xa6a87a9e797af923887645fc57602d60f7cd684357ae837a6270936eb6e5ebd5</span></span> <span class="giallo-l"><span>00042,</span><span class="z-keyword">0x5c8dca3c7c7842995372aed15fae7b9bada264b56082bec19c870bd4c7562b97</span></span> <span class="giallo-l"><span>00043,</span><span class="z-keyword">0xcb513d912a6ee576a33cf3683d596354b57484cfb4d7e382f64326eef5bec32b</span></span> <span class="giallo-l"><span>00044,</span><span class="z-keyword">0x1c72a3909e56831cea647e4c67faeb91db49b5be8c61832082041c16b2072e87</span></span> <span class="giallo-l"><span>00045,</span><span class="z-keyword">0xa87afdc1e1d225e6826d8f18c15c0415c7d13ba2a3933dc35816491bbc64501c</span></span> <span class="giallo-l"><span>00046,</span><span class="z-keyword">0x22b3f78d1437187866a86fc05463d5afa558903def2357a05ffd32663d5b7896</span></span> <span class="giallo-l"><span>00047,</span><span class="z-keyword">0x92d8437253506251ea652d6242ced9f3941906d4ffaa78edcb396a6c5fcad7d7</span></span> <span class="giallo-l"><span>00048,</span><span class="z-keyword">0x78ae53ed63f208b18448b40e3c31476eb2cd6627d6c65ba7dbc96d3e1051dcca</span></span> <span class="giallo-l"><span>00049,</span><span class="z-keyword">0x3934e9608386c1bab748cf80199b6b6341e581a163c64f6c0bfc55d36d41cc64</span></span> <span class="giallo-l"><span>00050,</span><span class="z-keyword">0x71698ebf74b826ce701bdda7c804c2b9d0aa3616bc1ccfbb62d4455cc2b0bec6</span></span> <span class="giallo-l"><span>00051,</span><span class="z-keyword">0x2c1c77788b22e42409b9e068fc98a28310af7cb451dbdc2601d29771bb117c47</span></span> <span class="giallo-l"><span>00052,</span><span class="z-keyword">0x3a047d9aba82db1eac26733dcc652c0aed663250b25781360ba9596db48ebe01</span></span> <span class="giallo-l"><span>00053,</span><span class="z-keyword">0x161ee1b5102e9c6300c04d4885dda180e50f3e5078ca8d2bc1f3d0af0a9d8287</span></span> <span class="giallo-l"><span>00054,</span><span class="z-keyword">0x14074ce7acc2ad4e4d60966d9717d8f2e6f7d28cffa1fccede05d4ab7269b772</span></span> <span class="giallo-l"><span>00055,</span><span class="z-keyword">0xae639ad86664191274136f85177a515b7524be9d089571f5e24c13bff9f91a38</span></span> <span class="giallo-l"><span>00056,</span><span class="z-keyword">0xd92c394c57df45119161e4ffecf8445e3af06c79c90987db86db649f2cbf7840</span></span> <span class="giallo-l"><span>00057,</span><span class="z-keyword">0x4bbe776e7229c9583ccc6da7d82451b56ef1fc015c802c27b2d364ffff7c6e7d</span></span> <span class="giallo-l"><span>00058,</span><span class="z-keyword">0x9ac60ed891eb7490ae1a5fa1d9c14ef66b01bf5fdc6f31a419a28c2946e0c3bc</span></span> <span class="giallo-l"><span>00059,</span><span class="z-keyword">0x246c1b33d8b91d3fad3c3b88d6aa04cd872bdf0608aafcd1f11a53c437418eec</span></span> <span class="giallo-l"><span>00060,</span><span class="z-keyword">0x4533d0c5d211593355e4bf1e07564fc04bc158e75437f33eb97ec9066322b3dd</span></span> <span class="giallo-l"><span>00061,</span><span class="z-keyword">0x122db1c231fee4e86b938a432ae95eae69a3ea733b82b15c2d784c70be3f9b89</span></span> <span class="giallo-l"><span>00062,</span><span class="z-keyword">0x65505079e3493c2fb572db2d1d9e455ef3e48be78c18f760fa6724fe1326f5ff</span></span> <span class="giallo-l"><span>00063,</span><span class="z-keyword">0x39b219117b1d306e0e9ac0a8f969d47f1cc375d7593e2c8e0996fbb80822f293</span></span> <span class="giallo-l"><span>00064,</span><span class="z-keyword">0xdb26a83cc55bf6f8c6ff63525fafd2c8dca1a0cd99828afcdbc5d3146da18dde</span></span> <span class="giallo-l"><span>00065,</span><span class="z-keyword">0x1df3a40f96ae6291f081fcf9dab9ebe03382d958cde909a4cb7cdc76201fe006</span></span> <span class="giallo-l"><span>00066,</span><span class="z-keyword">0x07bde22d34d4cd3a29214dd2bd1c35a49190a3df40505ddddde8e3622c6e7cab</span></span> <span class="giallo-l"><span>00067,</span><span class="z-keyword">0x751bac833356761ab2a1794fed46b04afcbc60d23e608a707db5b897e5d042d2</span></span> <span class="giallo-l"><span>00068,</span><span class="z-keyword">0x546a10c136f0cb0c85bf58b69e04424ffcf1b00b4afffd3f33c5ee253899367b</span></span> <span class="giallo-l"><span>00069,</span><span class="z-keyword">0x55c236ed7566681663e88a71b9597a48970297cbc0ee8b23b1d302dfe69f61f6</span></span> <span class="giallo-l"><span>00070,</span><span class="z-keyword">0x0ac3ebb18ec9ee6c921f36d5053d9343ad81218f797c39376d9e4f4352c768c7</span></span> <span class="giallo-l"><span>00071,</span><span class="z-keyword">0x2fb03713d78b7fba05408f872267c4877ed8db5e1bd1b9f1e57d872c5cc08adf</span></span> <span class="giallo-l"><span>00072,</span><span class="z-keyword">0x2f9a4a75044a49046297e71c578329b8326352fd49bd01158f42c73ea6948454</span></span> <span class="giallo-l"><span>00073,</span><span class="z-keyword">0x32871a4303777114e0f17126567013d94bb2884ea22bf0a103d45fef47c4b005</span></span> <span class="giallo-l"><span>00074,</span><span class="z-keyword">0x8aacdeeec1021158c05056e5aa2ea4cc4994aa2372f5d37d22272ed065f7493d</span></span> <span class="giallo-l"><span>00075,</span><span class="z-keyword">0x368ce2b13e74f99ef231825ba5df588d654ccaea62e0ff46d012b879608454d5</span></span> <span class="giallo-l"><span>00076,</span><span class="z-keyword">0x290a4131608502c9423b9ec4fdbb4cfdfa245ec92a571053702cb431d6d661ab</span></span> <span class="giallo-l"><span>00077,</span><span class="z-keyword">0x5d736b0aecc493c6160872dbcc216816071483a4c4518a2284bbaad9a9c592c9</span></span> <span class="giallo-l"><span>00078,</span><span class="z-keyword">0x98ac3e9dfdd27556bf5d5e037d10de525ad1142c1e954de9cc3b7e2287dc9ca9</span></span> <span class="giallo-l"><span>00079,</span><span class="z-keyword">0x95e0734eb17b4182d2458e6f5268abbc75c44e743b5abeb775d99bfdb1d1f6a2</span></span> <span class="giallo-l"><span>00080,</span><span class="z-keyword">0xd778ae86ee6b3ed9f3f3dc83a5ece367faa9ea230daa21c07c54e073af83f2fe</span></span> <span class="giallo-l"><span>00081,</span><span class="z-keyword">0x2089ffc8e635baaf3e1673f9ca3ed6d64b1dd02dd73aa5c2beb692af5363a1a1</span></span> <span class="giallo-l"><span>00082,</span><span class="z-keyword">0x382ac3bc7f5de4df286366863351ae1d3655fe5df7aa195e3f955e5cb4988bed</span></span> <span class="giallo-l"><span>00083,</span><span class="z-keyword">0x5ab1cca211eb959107d5541a30d1b9f3e8a6fcf9935643acabd4f2dff8f3d212</span></span> <span class="giallo-l"><span>00084,</span><span class="z-keyword">0x9ec0497d2130e92ea521793e98774962fe83ebd994fcac4963cede93950efaaf</span></span> <span class="giallo-l"><span>00085,</span><span class="z-keyword">0xf847bef9c0f4876906d74c0955d362175cc4d9bb83f134d60dad7bf3df6d0b3b</span></span> <span class="giallo-l"><span>00086,</span><span class="z-keyword">0x0dd5eb92d78e345af8ac60db208207fe3f4621e5ea09f195da8c977418c358fb</span></span> <span class="giallo-l"><span>00087,</span><span class="z-keyword">0xc0612d68f34fc28c18a095b0062d5762cf56d5c6554d94a0e97315ef262a4dd7</span></span> <span class="giallo-l"><span>00088,</span><span class="z-keyword">0x3f433e6334fa2b3d05edd615d92926aaec56b355f9375e3ea4b91ca0dd7c654d</span></span> <span class="giallo-l"><span>00089,</span><span class="z-keyword">0x0432ee13cd0aab4c445219c8edcbf80bd502d11170a2724cabad19f55d8f2ad1</span></span> <span class="giallo-l"><span>00090,</span><span class="z-keyword">0xcf23b0c8c31f2368dc982efbf1220f64439b107d691450a3eb15dca1180f5854</span></span> <span class="giallo-l"><span>00091,</span><span class="z-keyword">0x9fbb0197fb4b50008c5feea2810b0336d38dba1958fafdb3482036e6ad269895</span></span> <span class="giallo-l"><span>00092,</span><span class="z-keyword">0xf88ab15fc925643c8adc5b3485f19240e4afc53dc777f0c9bf9ab5c6c6f3338b</span></span> <span class="giallo-l"><span>00093,</span><span class="z-keyword">0xb7499b8c5bdb76c9a892b9e0d09cde7813ed0c38740d25743d02910f337c3c6a</span></span> <span class="giallo-l"><span>00094,</span><span class="z-keyword">0x5c45bbb126771f6277dca461a28239b4efd388b55afe6ef1c6e595ea4ebd9509</span></span> <span class="giallo-l"><span>00095,</span><span class="z-keyword">0xa3dea11d2eef1db4c8855ae369918a0e12de5b99e0087e3af0105ceb1ed1e0a3</span></span> <span class="giallo-l"><span>00096,</span><span class="z-keyword">0x91ff33f7ed74652bdd22a154aeec0cf24542b29477122dc02704000ef15dd540</span></span> <span class="giallo-l"><span>00097,</span><span class="z-keyword">0x8e4ffd2bc8e767d8848b4d001c20a7dbf942fe73b20f6821a2abd586c8462334</span></span> <span class="giallo-l"><span>00098,</span><span class="z-keyword">0x4c5709afb1a85d25d9131fe5e441ad7f0d5d4608583c07836ff4cc2e3228a30d</span></span> <span class="giallo-l"><span>00099,</span><span class="z-keyword">0xd55b92c14fec40d8ccf4fee501efecf9f71ced6d787eb3faaa4cd7050f3a3e08</span></span> <span class="giallo-l"><span>00100,</span><span class="z-keyword">0xbb39d00a031359e390914a91d9c26c1b8dff1b6d8ca4a44ebb64d5946a5451c0</span></span> <span class="giallo-l"><span>00101,</span><span class="z-keyword">0xe6df19425c17f10ef876e9964f7561bf3f7bc41fdca9151c26797f38e4a064e4</span></span> <span class="giallo-l"><span>00102,</span><span class="z-keyword">0x2aac9e21e2134958f6ebebe21acaa65142ccab41a0ca386aad4eb4c383b69145</span></span> <span class="giallo-l"><span>00103,</span><span class="z-keyword">0x3fe56c2aa4b33540147f05427b757a5ecfb57a4301a84022a0a26c57bd1f5b4b</span></span> <span class="giallo-l"><span>00104,</span><span class="z-keyword">0xf3269b3047cc6b5dd1f38313ff3bcc717b44375148a8637e4ce41ec39a9adc57</span></span> <span class="giallo-l"><span>00105,</span><span class="z-keyword">0x6f2f86e801b6456e59b5f4c6d2587ca8e5cfd97fbf93dcbd11b7c3cf65b83170</span></span> <span class="giallo-l"><span>00106,</span><span class="z-keyword">0x621a252741c0cc84c5e7e3b01f90d30d86474348f44cc659ff48000093671bbd</span></span> <span class="giallo-l"><span>00107,</span><span class="z-keyword">0xc3e8f7cdf2b7fd8a0ac98834d4ab1374e8aec4644fc722a04db5abd57329405c</span></span> <span class="giallo-l"><span>00108,</span><span class="z-keyword">0xbe1a1635522e1529456595e0615c4d3c53905a0198ad65320c8ec1f7f3ec665b</span></span> <span class="giallo-l"><span>00109,</span><span class="z-keyword">0x49424c3e48cdef7a00003a3ea76da66ce8f833df83f74580faacfa7cbff5dd28</span></span> <span class="giallo-l"><span>00110,</span><span class="z-keyword">0xaf29e604357c6c3d6f8a23c69ab648b8b19c0bac3e7e8ffcfe3d23f62c585490</span></span> <span class="giallo-l"><span>00111,</span><span class="z-keyword">0x1738246f2b0b1ba4a084cbe299233f487f3730d8ebcac38bc6cb43e503992248</span></span> <span class="giallo-l"><span>00112,</span><span class="z-keyword">0x0074a32e1420b57f8f7c142a61d5d945fa0df577c3007b375dc4412c46e774a0</span></span> <span class="giallo-l"><span>00113,</span><span class="z-keyword">0x56e191304d05e3370a821bf16ef43a7528b63105a03b425fb2c408ec21807233</span></span> <span class="giallo-l"><span>00114,</span><span class="z-keyword">0x10c2a569cfef2c20fbce1953dcabaa463cae1daf08e83a38322091fb1da59db0</span></span> <span class="giallo-l"><span>00115,</span><span class="z-keyword">0x26efb6b7b8a822fcfb126451c09491efa88a986bf3ee4f0bcbc7ff5610f051c1</span></span> <span class="giallo-l"><span>00116,</span><span class="z-keyword">0xbdf3bc6e520513ff3ca5382abbcfad7f2bc857db708233a07f17149d57d66648</span></span> <span class="giallo-l"><span>00117,</span><span class="z-keyword">0xe68e5334db9c4e799fdd67843038b909e231e8f5d248af1cb212907554ccc352</span></span> <span class="giallo-l"><span>00118,</span><span class="z-keyword">0x1c9a243765a53509f7ac091504edfdb27fe9e22f9766a7cfa02e0f87ba6774b5</span></span> <span class="giallo-l"><span>00119,</span><span class="z-keyword">0x5fc6b689c399c8151792427fa1e9b44c6453f520ea15ca643ec14cf1860b3397</span></span> <span class="giallo-l"><span>00120,</span><span class="z-keyword">0xcfefc65fab88cf757198c581e272c0e02d6488f4447b87dea8c908cbd8b3fdc6</span></span> <span class="giallo-l"><span>00121,</span><span class="z-keyword">0x0e29b6cdd3b4816acfbd104ca56b2ed140958c37fd4f7d9dbe5d62e1e7444e61</span></span> <span class="giallo-l"><span>00122,</span><span class="z-keyword">0xcddbda3fd6f764602c06803ff083dbfc73f2bb396df17a31e5457329b9a0f38d</span></span> <span class="giallo-l"><span>00123,</span><span class="z-keyword">0x7717d3958ced7ec038af0b4d7daaaf2ab4da56290db865faaf96da59e9babf7b</span></span> <span class="giallo-l"><span>00124,</span><span class="z-keyword">0x2e66a66a8ff5e15178ee8c9e500475b7badb71cc65d26dd6074e8faad109b427</span></span> <span class="giallo-l"><span>00125,</span><span class="z-keyword">0x82fdaab150f1a25c78a2a0253018fc5a83c420bfed8ec727f6c98e1571b39b6c</span></span> <span class="giallo-l"><span>00126,</span><span class="z-keyword">0x427637ff154cc2036316442348c319c019515af54dd5a2c702527b87f6ea4611</span></span> <span class="giallo-l"><span>00127,</span><span class="z-keyword">0x65e302f1d26bca3ceb600bcc6c19190d2a5e9723a47a99e0710f4ea1fdf9a2f7</span></span> <span class="giallo-l"><span>00128,</span><span class="z-keyword">0x6fdc1fedc9d9454ed6b7f1067da89f57ee4c4e298767cebcf549b37c38b463e3</span></span> <span class="giallo-l"><span>00129,</span><span class="z-keyword">0xc8705b6e734dc09bff141a739eddafc9a3016ca7e7078a09439db7785fb4e688</span></span> <span class="giallo-l"><span>00130,</span><span class="z-keyword">0x650f1d51006a9afa156973b7080774340dbff7334f6d4941729ed1fd39f4bbd2</span></span> <span class="giallo-l"><span>00131,</span><span class="z-keyword">0x7b4435cab2538749da96316d2068854b40a8cc5eb4810155954acb70ab8eefec</span></span> <span class="giallo-l"><span>00132,</span><span class="z-keyword">0x23bd760353974c8a41e410bb24b6aee32d19eb703692420d375da68ed5b8b4a9</span></span> <span class="giallo-l"><span>00133,</span><span class="z-keyword">0xc0faccfc19b41bb694cb86c86b88760dddc771125caff85b33ee5cf935f5106b</span></span> <span class="giallo-l"><span>00134,</span><span class="z-keyword">0xec9cf3ec39f1bb33d363eda9d803fd63de89a5b4afeed17c9bb5185b784d4cc2</span></span> <span class="giallo-l"><span>00135,</span><span class="z-keyword">0x66f5486b3e5c79a9d9d10d4ac5581bf89b4068376bf05ced98455b7d50b08844</span></span> <span class="giallo-l"><span>00136,</span><span class="z-keyword">0xdc4ebb94b5007edaa6be31715620430cab85927af56ff7efcd8e5c4df5b2912d</span></span> <span class="giallo-l"><span>00137,</span><span class="z-keyword">0x022982006526d25c7ee022373f4832c10fe42c7aa25b26044ee3f317b812c221</span></span> <span class="giallo-l"><span>00138,</span><span class="z-keyword">0x3d2314001a3de949f8cf44018b245fe6522bfe212ecae7b8e1676505d05c9905</span></span> <span class="giallo-l"><span>00139,</span><span class="z-keyword">0x5f31661180c2ee22f0f7209e38c1c2aea2fc03384aa0ea1f9d8b98cb0747ca5d</span></span> <span class="giallo-l"><span>00140,</span><span class="z-keyword">0xf13c9fc08dd8e3fd03250091f66d0cebcad41cfb4330d6e68bf447863d2f8201</span></span> <span class="giallo-l"><span>00141,</span><span class="z-keyword">0x17dbb0e39329cd8b2bf6839de0722241211c8a602c233f48302e50d7e6aa6361</span></span> <span class="giallo-l"><span>00142,</span><span class="z-keyword">0xe42539c839845c3033143db80f7bd316ab323114554cca363c2f3ead3ed6a68d</span></span> <span class="giallo-l"><span>00143,</span><span class="z-keyword">0x5594a813aaa2752040681086954b21e457ddc5a8f1d816b45925eb85ee7528ee</span></span> <span class="giallo-l"><span>00144,</span><span class="z-keyword">0x5ac2296fd274fd53197c615a25b4fb6f4303b17a977954775f73e036981eb4f0</span></span> <span class="giallo-l"><span>00145,</span><span class="z-keyword">0x9244d418b8875cb5a463decd0f8cee235755222f2e72ad97810635975f6ffff8</span></span> <span class="giallo-l"><span>00146,</span><span class="z-keyword">0xaf9e7a53390b2fe7c833e937cdbf627a8ecb39da70260eda50ad0af37b4a2d1f</span></span> <span class="giallo-l"><span>00147,</span><span class="z-keyword">0x1b6fa332dd5f6b04e3fb1a027b63f2513b4159035d3294b0212899649b61da2a</span></span> <span class="giallo-l"><span>00148,</span><span class="z-keyword">0x39f0b0575eec3daa97f64b9bc538f841242003a72256fed04e015e78f72bb92d</span></span> <span class="giallo-l"><span>00149,</span><span class="z-keyword">0x586c4a913ddb47e0cd4847637cccd2b458a09e35e10b29451febc5ce8f19f696</span></span> <span class="giallo-l"><span>00150,</span><span class="z-keyword">0x3ff89a4a288f9325e315b394c991680a5843acde1412d0539412363b08ee7c4d</span></span> <span class="giallo-l"><span>00151,</span><span class="z-keyword">0xe322efe1b787fb583eed8d19ef06ac5660c014e566ba2541c160251273f8eaf5</span></span> <span class="giallo-l"><span>00152,</span><span class="z-keyword">0x4d9d0d1c39a4d03a8e4def8892d713c4c9c84df804bd2da90e20e596c99ff6f1</span></span> <span class="giallo-l"><span>00153,</span><span class="z-keyword">0x6b5702b39f5bde08d74649594e48ef49faf24a19c5d7ec75d8cf490157f4f201</span></span> <span class="giallo-l"><span>00154,</span><span class="z-keyword">0x13608c120fd377b160206bd5f9afe2ed660ecd8a121210faeaec26c9b6010975</span></span> <span class="giallo-l"><span>00155,</span><span class="z-keyword">0xd0bf6ce2d1f149196b41e2379831cd9e07d215a9da2be8a2b772be32a10b3f64</span></span> <span class="giallo-l"><span>00156,</span><span class="z-keyword">0xb8c3629c89fbf5c93a481688d05e108af37f4ca1152e2c1ce66de366db58e934</span></span> <span class="giallo-l"><span>00157,</span><span class="z-keyword">0x97351a9d18fe2307ffc128e294f580eb5c9c9f48fba6a5f4f25a0aa98d97fac8</span></span> <span class="giallo-l"><span>00158,</span><span class="z-keyword">0x5cee8f8c5f208a9d23dc367deb3c47e1b3e186bbdd94f2812ac27b40825de041</span></span> <span class="giallo-l"><span>00159,</span><span class="z-keyword">0xb92f84e91d955459a2de86bc28544a82ffaf23c6175f657f767303d63cf8b842</span></span> <span class="giallo-l"><span>00160,</span><span class="z-keyword">0x3e41d9f5b9538accaac888b49abc201aa3d71f5aa6c516a97e69314886989788</span></span> <span class="giallo-l"><span>00161,</span><span class="z-keyword">0x0736b99a2882a562bfd35db27b128a498711834107fd2c0356063b406ed8c804</span></span> <span class="giallo-l"><span>00162,</span><span class="z-keyword">0x0a1530daf01f3cddb2af69fc527b5f7635aab2d02adc46e5a21f8344eed9f7b3</span></span> <span class="giallo-l"><span>00163,</span><span class="z-keyword">0x43212d3b60bfcccb6b12bf765fd072f8785a7d41dca097e37ea14b7c8faf6d85</span></span> <span class="giallo-l"><span>00164,</span><span class="z-keyword">0x3744a01c5c7968e2230ec9d29de8a370db7f43763ef8f22f58cbbdf13f27eb1e</span></span> <span class="giallo-l"><span>00165,</span><span class="z-keyword">0x3d14fc84c9f2dafa748275285205ae2b29df613c8f982d1f334d661b1511f8e2</span></span> <span class="giallo-l"><span>00166,</span><span class="z-keyword">0x97c2592527a83d1c2c514f447e8ae6fdb1481c0dc9c4a3f7212049c5eeae578d</span></span> <span class="giallo-l"><span>00167,</span><span class="z-keyword">0x1148500252c17babbed0e2df0e3913dc380f7c0a06e680d4ba101748620660b4</span></span> <span class="giallo-l"><span>00168,</span><span class="z-keyword">0x88a365fabc60615ca56960314ae6006f61df6fe729a40341c12bb3c98045a4dc</span></span> <span class="giallo-l"><span>00169,</span><span class="z-keyword">0xf18242e71a0c97722f01fbe9c462e0fe857d93a43f1d683fff9e36e4d3ad59df</span></span> <span class="giallo-l"><span>00170,</span><span class="z-keyword">0xf03ea8ee5343e37601df81cc61173e6276516b1f69225a8c1a94fb079545957f</span></span> <span class="giallo-l"><span>00171,</span><span class="z-keyword">0xbec8ccd9a6e13443a8e61a931138f3cf6218a2b477d11ef59a082f898796c439</span></span> <span class="giallo-l"><span>00172,</span><span class="z-keyword">0x34a4c5d21fc33c31b415829b9e46c63588db2327e3ee13682d52233108a2af25</span></span> <span class="giallo-l"><span>00173,</span><span class="z-keyword">0xe1ae6c812dc2ca1cb0613ab42e6c81721f96e771b13c79d284dacbb30c65e5aa</span></span> <span class="giallo-l"><span>00174,</span><span class="z-keyword">0x727d10b81b790e7f5f608c35126fafc3523c7e991bfdb8ef018edbdd207b4c24</span></span> <span class="giallo-l"><span>00175,</span><span class="z-keyword">0x1bf21dcc47b8d4ed6511e49dfc4bc14c1f40f2c21464d52aba8b4a50c60e3b1f</span></span> <span class="giallo-l"><span>00176,</span><span class="z-keyword">0xecc872aa4aa1c53bdc3c22687ed31f1373db111f1c1219286f857b157f6990b0</span></span> <span class="giallo-l"><span>00177,</span><span class="z-keyword">0x966bdbf23d2e86326afccf08377aac0067d485c6098d90c1c74a84b34b8eea3a</span></span> <span class="giallo-l"><span>00178,</span><span class="z-keyword">0xb412f22cecb0219921846638c68908fbc2d73f3d2c7d32d7d86795e9f48c5145</span></span> <span class="giallo-l"><span>00179,</span><span class="z-keyword">0x09e40d3b668d4808509a521703734da066da50c303525314712713c5dbc6a2f2</span></span> <span class="giallo-l"><span>00180,</span><span class="z-keyword">0x8ce22357ac0066d519294b9ab476c222a2edf3cbcc4e06a2df0504ad11f5c1ca</span></span> <span class="giallo-l"><span>00181,</span><span class="z-keyword">0xac1cf418529f5346213890d7f11ccf4a21e24023d40f2eaaa943606f8b7a1e6e</span></span> <span class="giallo-l"><span>00182,</span><span class="z-keyword">0xf770e12a39d1ebfe34919a211fcedb2098ff562689be021bbfb8636f756c4b95</span></span> <span class="giallo-l"><span>00183,</span><span class="z-keyword">0x798224ae95fa5281f29cdd3ac9eb753ca8e9ee44b9cb2c5747f97c8d71917b58</span></span> <span class="giallo-l"><span>00184,</span><span class="z-keyword">0x876fdbe53a7831817a5e123f1b043700f1f3d47f685b772dded35c953d629e5a</span></span> <span class="giallo-l"><span>00185,</span><span class="z-keyword">0x7b447a76548eb9c28145371f61831a2dc941acd907804808a7ab93f7c171d621</span></span> <span class="giallo-l"><span>00186,</span><span class="z-keyword">0xf1e11ac5a67e45142b1a1a13663c725f82a84d5e59ddf65f3b740dbd028b3d63</span></span> <span class="giallo-l"><span>00187,</span><span class="z-keyword">0xce8b009f996254d6df379dd2b3a5aba9dd1d3e0b64de28e5838b43f411f42e4b</span></span> <span class="giallo-l"><span>00188,</span><span class="z-keyword">0xc7bd816d6d55b71c0f6784b2925ff9e1daf65bfb238fc1bb4980274130b500c9</span></span> <span class="giallo-l"><span>00189,</span><span class="z-keyword">0x144cc97d4bfc31469fec6de2cc4ab5556af13aa4b00b96081692ea64092c592d</span></span> <span class="giallo-l"><span>00190,</span><span class="z-keyword">0xcbbcca518e96049a99aad9b53f2e579cf866d6c8fa3a69e407404a3508963394</span></span> <span class="giallo-l"><span>00191,</span><span class="z-keyword">0x3a7f648499e877f2451d3bb6f1e90e5e48ce653459849d52aef5b1f04bd7a9cb</span></span> <span class="giallo-l"><span>00192,</span><span class="z-keyword">0x8a4639c3f8df41e06f4af80ecd6227823708c39128cd6a791e9ce390d9bcc7c9</span></span> <span class="giallo-l"><span>00193,</span><span class="z-keyword">0x52629553fb11ce8b1f53ad71c3ec8fa911ff6e0424b7c0a015922311888079d3</span></span> <span class="giallo-l"><span>00194,</span><span class="z-keyword">0xc4828a4b7616281c5e82ba47e691de8a9975512f0d9033b098082cf027e90236</span></span> <span class="giallo-l"><span>00195,</span><span class="z-keyword">0xf50a165e20e68aa37f97ead770fd9710ccb7b4fdc80581b5982f1d7a219feae8</span></span> <span class="giallo-l"><span>00196,</span><span class="z-keyword">0x5c31919b4d982bee212e5d30e35fc2998d946a0c124e54e3e2c27fbf8d129494</span></span> <span class="giallo-l"><span>00197,</span><span class="z-keyword">0x9e2a709b9953cd0e76df8b6f36d2cee961b24aa19ed11c6def3f5a1744c1755b</span></span> <span class="giallo-l"><span>00198,</span><span class="z-keyword">0xc3e781bf3998d0fd70bdbdf8213e066bb31636039606d9763ab9449cf73ad5d1</span></span> <span class="giallo-l"><span>00199,</span><span class="z-keyword">0x20c05ee3e79b3ab76d806ae93d9cd01340ea68c007816dcedede0635df91850a</span></span> <span class="giallo-l"><span>00200,</span><span class="z-keyword">0xdc265ad95ef9c500cecb8bf2a5da52b3f29d171aa981c8bd9ccbd6ccb7696e69</span></span> <span class="giallo-l"><span>00201,</span><span class="z-keyword">0x1356f2dabf963afe35b149a0de796d3e48f87bc41d9a516d4924854af52dd709</span></span> <span class="giallo-l"><span>00202,</span><span class="z-keyword">0x84e861144a0bfc933935e47097d963e8591a0f321cdb7ad1d75d899ca501df1e</span></span> <span class="giallo-l"><span>00203,</span><span class="z-keyword">0xf2da7b50b32ed6bc786564ffc8e7b85ab250ec0eaa0096dea3faebfc9e07bdc7</span></span> <span class="giallo-l"><span>00204,</span><span class="z-keyword">0x7f42b43f0556b03846f18a12da581203682f8d2266fcd686b388970ea6229de5</span></span> <span class="giallo-l"><span>00205,</span><span class="z-keyword">0xafd08f8ec73d9a83ac8b099ba3202cda132e9e07e3dd18738dc4b5b1f0d98e93</span></span> <span class="giallo-l"><span>00206,</span><span class="z-keyword">0xcf4a2c657b1cf55f37167bf85a51ed104eac71967a98bd4c02a42dfc057c02a6</span></span> <span class="giallo-l"><span>00207,</span><span class="z-keyword">0x59a0e883c7a7087b9c330ae4703d0cf263eedd8d20466e313c894519235f5d44</span></span> <span class="giallo-l"><span>00208,</span><span class="z-keyword">0x3d0bbaf203bdf186daab82974347c617e1210a586751ec6c9818185d0a096e3f</span></span> <span class="giallo-l"><span>00209,</span><span class="z-keyword">0xc1041285ee311030789717024ad66718f6184a03a0d31a1ce4ccb0948fa17dc5</span></span> <span class="giallo-l"><span>00210,</span><span class="z-keyword">0x1eb673abfb14d61c67d81d48dad2b7f72080a90fe090b6846779fb78046402ff</span></span> <span class="giallo-l"><span>00211,</span><span class="z-keyword">0x01e5a4d0cf29ec996c00f168d445f55eb3552f213200a247c4efd60d4fceede4</span></span> <span class="giallo-l"><span>00212,</span><span class="z-keyword">0x83c3bb0ad1f3784c92a88909ab533c62dd5e7b3dcacbaf624ae95ee12022eb11</span></span> <span class="giallo-l"><span>00213,</span><span class="z-keyword">0x9a09fe68cd5dcdc15ea76f08eac7e2a679075e772064354c747b75e5ddca8d2f</span></span> <span class="giallo-l"><span>00214,</span><span class="z-keyword">0x9e78dc12bf0023bdf0c8c1b8e7f7c6e5a92d66b56475594bfa334c129df58735</span></span> <span class="giallo-l"><span>00215,</span><span class="z-keyword">0xb02bf96a7443e246b6733270453b35a70ff1fcf49375cedc97338614ac65ac51</span></span> <span class="giallo-l"><span>00216,</span><span class="z-keyword">0x209c8b324d31fd9d8c8c4cf26f6506657608e6816471fe522adb1425b5ebd04d</span></span> <span class="giallo-l"><span>00217,</span><span class="z-keyword">0x6c84f49aa1ae7943df31f340739b2b63df7476e87cf0ddf82862982456865c95</span></span> <span class="giallo-l"><span>00218,</span><span class="z-keyword">0xacb60f14bf4bdc96ce579f02f62f8bb35db16f03dde7329363bb50388c3c45b0</span></span> <span class="giallo-l"><span>00219,</span><span class="z-keyword">0x0a773645ba0627df6df44158e292f2f226ca74bbc90464ec4796ac2e9bf26578</span></span> <span class="giallo-l"><span>00220,</span><span class="z-keyword">0x76ed2324a565e51cf2a82bd0cdb025f255caf25d61396d4da19d708c40adcf92</span></span> <span class="giallo-l"><span>00221,</span><span class="z-keyword">0x76ddd2d829c12483b2ffec2c587557bc5972e08dc8866708a2d44a31575483d2</span></span> <span class="giallo-l"><span>00222,</span><span class="z-keyword">0x71e986b22213ce63d0e3df141581fca8fbfc41569f0bcd62c101c67cb00295b3</span></span> <span class="giallo-l"><span>00223,</span><span class="z-keyword">0xca2b5c289ff78be184a6cea0f072aa71cfe0977f18bbcca536b48938e5d64276</span></span> <span class="giallo-l"><span>00224,</span><span class="z-keyword">0xff571e13e54cdc9ca6facd7012051ee787bee1c52a555653fd969751bfaac7f2</span></span> <span class="giallo-l"><span>00225,</span><span class="z-keyword">0x1cfe32398c41e4ecdde6cff7b2df6f9f2651ee87aae1b52bc35e4d76f136c3a0</span></span> <span class="giallo-l"><span>00226,</span><span class="z-keyword">0xb0eb8f2f68728e48a4ded02891b9a682f7c925099e899c26143083850b3f2829</span></span> <span class="giallo-l"><span>00227,</span><span class="z-keyword">0x83556e9f3d0e05c0d4cd809cf1bcad1557bfeae027ac4de16e6956596e8309fc</span></span> <span class="giallo-l"><span>00228,</span><span class="z-keyword">0x7651e7fbd8326e549f9af9122585f517c4f59ab6e735cd958888fb6f80f29db3</span></span> <span class="giallo-l"><span>00229,</span><span class="z-keyword">0x238ed7884113c0356cf4e5ef35e05434d3e076428884b93bbb873ac30afef54d</span></span> <span class="giallo-l"><span>00230,</span><span class="z-keyword">0x3826affaf4ebf5817b453c54c937951770c19ddb7900c9a7742919c24242f6b0</span></span> <span class="giallo-l"><span>00231,</span><span class="z-keyword">0xb81f93c6179db089673e919d91660274e96f240a699a12a140185c69ac19b674</span></span> <span class="giallo-l"><span>00232,</span><span class="z-keyword">0x0cda2a75d5dd4059a2e5712ac7cb151f033b700995e93c0819f38cb01b7f005e</span></span> <span class="giallo-l"><span>00233,</span><span class="z-keyword">0xb183167b3a03238701597a198475ccec1308e2c55babbe5d5acb92fcd694fa21</span></span> <span class="giallo-l"><span>00234,</span><span class="z-keyword">0x4a88300d556d8a8d66669f2d2b395263ded44d9a86bd45b3b426a55f7da8eb22</span></span> <span class="giallo-l"><span>00235,</span><span class="z-keyword">0x05ef61436ee159233c382043f0a9e99d34ed88a0bf3c12244f546b7b861b9f5f</span></span> <span class="giallo-l"><span>00236,</span><span class="z-keyword">0x4164fdf451a7134e2faa3672aa40a0168e2a16895020c0cd5632322793fc96d1</span></span> <span class="giallo-l"><span>00237,</span><span class="z-keyword">0xd5c9eed4c1796793e8595d155187444376f4b5478ea5ff1804f1ba06bd328506</span></span> <span class="giallo-l"><span>00238,</span><span class="z-keyword">0xdb0d90c5045dec94b87c81a03fb985a6fb84e1debb372b56c2513f25d4a2d8f8</span></span> <span class="giallo-l"><span>00239,</span><span class="z-keyword">0xa0c972ed0270d34b19b803a74649470307f138ef0567df85ef53a862b383dbdd</span></span> <span class="giallo-l"><span>00240,</span><span class="z-keyword">0x9cc1a86a28230bad01981b644067885e0333588976edef464aac674744c9eed9</span></span> <span class="giallo-l"><span>00241,</span><span class="z-keyword">0x8ab5ad435e4c9a37815b47344d282c90a3f364d516374b4b2158cf16148d79de</span></span> <span class="giallo-l"><span>00242,</span><span class="z-keyword">0x491f232e15a8a44b1f045dc68552543672c6d3bff361a5fecd7c0a54c1f21d2f</span></span> <span class="giallo-l"><span>00243,</span><span class="z-keyword">0xf66eb348a6b9dd916baf6bbab3299c57b9d95e5bfb585893f2953209c2c451e8</span></span> <span class="giallo-l"><span>00244,</span><span class="z-keyword">0x7b141f131b2878edbef5e71682051e3082490e755502c0372e5ace9cb5ea3d5b</span></span> <span class="giallo-l"><span>00245,</span><span class="z-keyword">0xef5b96a583318ef2d24bde313396aa09dd5d102cbd270b95c036bc6db98349a5</span></span> <span class="giallo-l"><span>00246,</span><span class="z-keyword">0x32d63aa14065862ce43f33e578625a2892710dd11025a9299f8722421c625874</span></span> <span class="giallo-l"><span>00247,</span><span class="z-keyword">0x7b033a6c76470c8b7b953161d562fe30c90705672f950a176de70a6aa5f1b130</span></span> <span class="giallo-l"><span>00248,</span><span class="z-keyword">0x50916052436d167fa83998749a703038ddb08d7cc789c276099235f9af28a613</span></span> <span class="giallo-l"><span>00249,</span><span class="z-keyword">0x75e0db34d48e90e80705be01c100e3767aa3302d4269a00f4c944069ea451ccf</span></span> <span class="giallo-l"><span>00250,</span><span class="z-keyword">0x4781ac7f896d2a547f2a973fdd352d5e9efb019939bd10ab31f0f84887968831</span></span> <span class="giallo-l"><span>00251,</span><span class="z-keyword">0xc0f8b33bf4828ab6578b5312d922b37139bf9c1d0eddd973f5ee84b39af48a28</span></span> <span class="giallo-l"><span>00252,</span><span class="z-keyword">0xafa72ca222af4feacee96c6a64a4b05a1fe464f9ed48e93e13cdb096d0147d25</span></span> <span class="giallo-l"><span>00253,</span><span class="z-keyword">0x96c6ccb34878fb040117b6933c7d7f1ca4f534dc63ab86d2cc4914b06786331a</span></span> <span class="giallo-l"><span>00254,</span><span class="z-keyword">0x7b32050e8240cfbf7ab11e4b06647d363c83aafa32d78cf34460b335d0e55a3c</span></span> <span class="giallo-l"><span>00255,</span><span class="z-keyword">0x16317cf915089e0c7cc1afb35540a004fa2c79e75f4410dbd89e6d9fdb2b89e1</span></span> <span class="giallo-l"><span>00256,</span><span class="z-keyword">0xb4ccb50be9c8f0759450e6dd9d05cb16778cc2852c0f8aaaeaa118a45267891b</span></span> <span class="giallo-l"><span>00257,</span><span class="z-keyword">0x98808d165ea3e628d92a93cfb1081e68254c4e2a48eea8c1cb3771772ee0fa74</span></span> <span class="giallo-l"><span>00258,</span><span class="z-keyword">0x3cf61b1ca697e63092bcbaafad3cf25608f47a9b6563bf8dc1720eb2a7fbe384</span></span> <span class="giallo-l"><span>00259,</span><span class="z-keyword">0x051764d24d14c62f71e8df8e9eda01d4edba8a9a52cf50ed50dce0d06f33bbeb</span></span> <span class="giallo-l"><span>00260,</span><span class="z-keyword">0x3b0545e8512ad0ef40623a237e1461577102fb2d6aa820dc0a9420d62f1a5942</span></span> <span class="giallo-l"><span>00261,</span><span class="z-keyword">0xa6f4bfcafda2d4cfc8bc900a5f844d60a50822aff332f7aadec3157b12a8d1ba</span></span> <span class="giallo-l"><span>00262,</span><span class="z-keyword">0x1a75662f7da5af8abe9f73deddfdbc4fa23772f28a2968eb44dab1e413238841</span></span> <span class="giallo-l"><span>00263,</span><span class="z-keyword">0x21bf7eeeff2979facb0c0a59ebfe07e4f110c9f7417217a341039ae2deb4c6d7</span></span> <span class="giallo-l"><span>00264,</span><span class="z-keyword">0xd41eb83d2e64d9928f6c18e95060bca40c3226b4982f91dc97a518201aac8fb2</span></span> <span class="giallo-l"><span>00265,</span><span class="z-keyword">0xe7a1956113e4b4c440a7ca46855ad2d2705ee3c018770e3fa8f8a3b3a6b6d6a9</span></span> <span class="giallo-l"><span>00266,</span><span class="z-keyword">0x4f172aab43c6bec97adf68392b12e82b4512ebc52df0298ce3253672fe59135b</span></span> <span class="giallo-l"><span>00267,</span><span class="z-keyword">0x7c0e1bcfc2aaa6ae002a1bc3fe0ed288598013b4c0dbce889d4b41cc8f1c792b</span></span> <span class="giallo-l"><span>00268,</span><span class="z-keyword">0xc839e6d47fa99f7bab58ca9eea51d6306873f67fd286ddeca8348a09c773cc42</span></span> <span class="giallo-l"><span>00269,</span><span class="z-keyword">0x9ec52dfb6facec401f848cee38bd6eda4e3429291939754a4985eb8ae969787d</span></span> <span class="giallo-l"><span>00270,</span><span class="z-keyword">0x4e8bc7277defdbc8c904f780c9b6f82c214816b5379e95490c7f0052a7295465</span></span> <span class="giallo-l"><span>00271,</span><span class="z-keyword">0x5294c75dc9cdf4c43f683b6c02c9078852607faf9dec990339b74476e0c0108b</span></span> <span class="giallo-l"><span>00272,</span><span class="z-keyword">0x02a11db25d807b03efafe32a0ee0647b35d47506a7fac186bb51e3c3a77a5655</span></span> <span class="giallo-l"><span>00273,</span><span class="z-keyword">0xd81a2c4138adf6e8b1af325a9a0b08ce6a0b3b72a79b367118294bafb4b832e9</span></span> <span class="giallo-l"><span>00274,</span><span class="z-keyword">0x9c4bd87dc1b25b83302973a9c4223cda44c1200ea2a83106463adf6317bdc605</span></span> <span class="giallo-l"><span>00275,</span><span class="z-keyword">0x85b9c67dc6b5b7c0014824f8b1909633459cd0b8e1584753064f85e1a1243c8a</span></span> <span class="giallo-l"><span>00276,</span><span class="z-keyword">0x38cc12366c2a7d559e4df0705bb822d8d0db59221de71477dfcab90e317b2e97</span></span> <span class="giallo-l"><span>00277,</span><span class="z-keyword">0x40c70f952d1ecfafbd064b1367045570b703fdbc7059cc7f9194ed34794d1db6</span></span> <span class="giallo-l"><span>00278,</span><span class="z-keyword">0xd9e0d7381580a9f3fa81e7a8f582967f09e1e87f0e4c5d08221edf0434053608</span></span> <span class="giallo-l"><span>00279,</span><span class="z-keyword">0xd20a7b7f9138afec7ab17bcc1fa4d77571d78f12bac193db64cbe046d0bcd1e6</span></span> <span class="giallo-l"><span>00280,</span><span class="z-keyword">0x54a85faaf00ddd99bf86faab4ddbd028b8d3f4e8f4492d1c7160aad9a03db638</span></span> <span class="giallo-l"><span>00281,</span><span class="z-keyword">0xf08b974956e8b7c14b335bf82add248bdf06a9626ecd6627ae0cc523359cad9f</span></span> <span class="giallo-l"><span>00282,</span><span class="z-keyword">0xa5912776593b35ee8dbca404e0c36497dc410062c0e5f4c6b40923232b17a8ab</span></span> <span class="giallo-l"><span>00283,</span><span class="z-keyword">0x8ee7ec35fab36575d9e5105303fa547ca8a03b6ecf731cbb64b9823250323d25</span></span> <span class="giallo-l"><span>00284,</span><span class="z-keyword">0x374996f2ff5de9c6262168bc93fe7548bc6cb94d45dd4dcce211a9be677ddcfd</span></span> <span class="giallo-l"><span>00285,</span><span class="z-keyword">0x9494258571f7dda74ed018ffed536e412f5272028442ce932677668613278035</span></span> <span class="giallo-l"><span>00286,</span><span class="z-keyword">0x6d47a23492f0ec9831f3536b4b542b1addaa041ab9f9cb6d2f6821a5f9ed6646</span></span> <span class="giallo-l"><span>00287,</span><span class="z-keyword">0xf9804151a4dbbe0c86e08b2109fc328a287ea4ac10abfbe01a9bcc866e7422b5</span></span> <span class="giallo-l"><span>00288,</span><span class="z-keyword">0x3724a8c948c728a89eb03af19c3be5e7e26abde6713e6e9ab5559dd21f8e095e</span></span> <span class="giallo-l"><span>00289,</span><span class="z-keyword">0x60d72bd902aef520fa3a0fd618cc230a50c8cd3951042f5a613b3d45f0b94c6d</span></span> <span class="giallo-l"><span>00290,</span><span class="z-keyword">0x64cca80b0eb18b315b2213ad5e2b53dfcbb1141ffa422ad46e7cb3586a200aeb</span></span> <span class="giallo-l"><span>00291,</span><span class="z-keyword">0x0dfa92f2d0ff334ed8306b33e6d3325720cc13aa0f046d53a2de144d89b9af92</span></span> <span class="giallo-l"><span>00292,</span><span class="z-keyword">0x9490598864a1e3ce2241136637de020cf275921f59545dbc4ecf4cf87f678b84</span></span> <span class="giallo-l"><span>00293,</span><span class="z-keyword">0x0d6c5812bd1b877d8715198580c66eab1ddaa78e1dc350e70eba0d59e633cf30</span></span> <span class="giallo-l"><span>00294,</span><span class="z-keyword">0xf6c5c94a2006aa624d007104ed8debbb32ec15423382e4759bc7a16a1357d5ed</span></span> <span class="giallo-l"><span>00295,</span><span class="z-keyword">0x4efa78d05a58e9b1e633443b058c9f8d447728e0ad64a50332f848199f8a4253</span></span> <span class="giallo-l"><span>00296,</span><span class="z-keyword">0x81c1446a12d42c3ce40f4a99326cf8e5a306ab72c773ac26f63a63cbe0a58064</span></span> <span class="giallo-l"><span>00297,</span><span class="z-keyword">0x08d13a3189fb2e18636d6beadbc137a79d03d9278c60f80829443348b8c560a4</span></span> <span class="giallo-l"><span>00298,</span><span class="z-keyword">0x3d1d6d89bcfb495fccee7bb0bd8f04715d84abe14f94fb36f870e5606c2cdf18</span></span> <span class="giallo-l"><span>00299,</span><span class="z-keyword">0x23728d43eeafdcff8f761c5a53e3f9373d25d17efb28347a91938484e03d07cf</span></span> <span class="giallo-l"><span>00300,</span><span class="z-keyword">0xde0332534e50154c9eac98068e56da4508d82ecf24ca3a275aeef3dee99b95e0</span></span> <span class="giallo-l"><span>00301,</span><span class="z-keyword">0x15a24df990de83affd9aa7cd9e67f4c558e1b3f306a6281385cc2e6409b9793a</span></span> <span class="giallo-l"><span>00302,</span><span class="z-keyword">0xba653536adb3464fdd46fe741d7daa1514a84f7555bf7ed91cb4d3bddc0a6f1b</span></span> <span class="giallo-l"><span>00303,</span><span class="z-keyword">0x35fde006dd9552f56250125ce80ad21476daf78f8727b432cdb370372c161a65</span></span> <span class="giallo-l"><span>00304,</span><span class="z-keyword">0x377bf395fc2a3ef98595766247a1c057a05d5fd3629bfd27d0bede0c6183a7f1</span></span> <span class="giallo-l"><span>00305,</span><span class="z-keyword">0x340a0b81056d5170e635ef43d952b8ec4ff7f3d5cf4ea1469750448d78f3e501</span></span> <span class="giallo-l"><span>00306,</span><span class="z-keyword">0x848e3d92711946156cd7c848947d2ba4ee4c0b39087ea30c90eb1e64f8aba773</span></span> <span class="giallo-l"><span>00307,</span><span class="z-keyword">0xa3ff791642f87c2bffb269a1da3d8e943a1828cafe10ea7a483a508f78ab54e6</span></span> <span class="giallo-l"><span>00308,</span><span class="z-keyword">0x48c7160cbf3a38ea7299edf971711e9d6875969dd38ce2086763389d9fac048c</span></span> <span class="giallo-l"><span>00309,</span><span class="z-keyword">0xe7948131b78ed9f05c0e18ff0497a192aaf8c5d3c1a56e1096570b3b45117253</span></span> <span class="giallo-l"><span>00310,</span><span class="z-keyword">0xdb22eaaf717a1a827a085d3960e2a477a2e9a73584bc4a293377ac50a492350f</span></span> <span class="giallo-l"><span>00311,</span><span class="z-keyword">0xf9e4fff98d04206dd4004f5ec146e676327dc8399dff7c7eb61d1d80f706d3ea</span></span> <span class="giallo-l"><span>00312,</span><span class="z-keyword">0xd95903d02e93dc935ce569153d9c88680972dd5e9156dc0a7f4da9a3435ff004</span></span> <span class="giallo-l"><span>00313,</span><span class="z-keyword">0x73f91876f19025335210705149eac61825673f8698bcf5aae285c00051fd6f6c</span></span> <span class="giallo-l"><span>00314,</span><span class="z-keyword">0x8e3397949f833d550ca3a268befa4c48c238f488572b2512f8cb5232d78dde24</span></span> <span class="giallo-l"><span>00315,</span><span class="z-keyword">0xe83123f07d6e146998f885c5c4f71988f472b9769e9c731d421327f3f4add351</span></span> <span class="giallo-l"><span>00316,</span><span class="z-keyword">0xe49c7af7a328992fb98e65057e28326f3684f84293a6b9825ef8297fb361a186</span></span> <span class="giallo-l"><span>00317,</span><span class="z-keyword">0xf3ae6a628ac464fc0f14f4654dedf31ab553c9750bbbc801e395ac858bbb619f</span></span> <span class="giallo-l"><span>00318,</span><span class="z-keyword">0x4bf5c84ae3ef17b5fb6455380d4708dba2da9c9224c4a31a0cb14ed4e8eb17f0</span></span> <span class="giallo-l"><span>00319,</span><span class="z-keyword">0x391837c44adbebf55ee138d56c65353612b31c66f1cc02663b7f088b80dde22f</span></span> <span class="giallo-l"><span>00320,</span><span class="z-keyword">0xbfd4677eb2bd0210ee172956700adfcf8b5164982b533a191907f62ac3f6ae1e</span></span> <span class="giallo-l"><span>00321,</span><span class="z-keyword">0x7189f4963254c00f349ebdb7f507638472c13e083cc525be744de2ce8374e1e9</span></span> <span class="giallo-l"><span>00322,</span><span class="z-keyword">0x344663aa7240ee9c312f31e5111dcb672451ef971ec1375fb8a298c676738c7f</span></span> <span class="giallo-l"><span>00323,</span><span class="z-keyword">0xe111bfc2e481e928c91b0d0a5868221c8699e22fbe87852b3bedb3124072659a</span></span> <span class="giallo-l"><span>00324,</span><span class="z-keyword">0xbe2b4b22f7c8c897ba0731eb6342e075c338b8feb2791c31be1d20c6c47f167d</span></span> <span class="giallo-l"><span>00325,</span><span class="z-keyword">0x441fdc4402e5b407058b634523f6318e2b6ac078414720bda9466129896e19c4</span></span> <span class="giallo-l"><span>00326,</span><span class="z-keyword">0x4297936031236c915aed0b391555294f1df7b346889ca02edd1313b8fbd73298</span></span> <span class="giallo-l"><span>00327,</span><span class="z-keyword">0x820afe74538d0b05b98e1d16604fb60bca79f04c56fa724e6d2af5532a5b45e1</span></span> <span class="giallo-l"><span>00328,</span><span class="z-keyword">0x08665862041221b6d297f4e7619b1044eadbdb92ec1415e916e9bc78558aafca</span></span> <span class="giallo-l"><span>00329,</span><span class="z-keyword">0xcc85d0d955b9068c848b56435b53e7eef8d2a1266cfd92c46544594a1b7c06fc</span></span> <span class="giallo-l"><span>00330,</span><span class="z-keyword">0x8ffabe96ffed7125caf2395331a37eeeaa016c1fbd0af6ddbaaeaa4ce3a75428</span></span> <span class="giallo-l"><span>00331,</span><span class="z-keyword">0x57c9aa448a060ee1cbe8a7b5236ef301c090d29baa0f644ccb23661b7933b4df</span></span> <span class="giallo-l"><span>00332,</span><span class="z-keyword">0x3135b7344e51ce37b6f82ad0e1ab5dde01a7cbf154ec76ae394c6e99fa866e68</span></span> <span class="giallo-l"><span>00333,</span><span class="z-keyword">0xef368f009534af83848b1ad36c874d1cd28cbf792663db122dd8f7f123506966</span></span> <span class="giallo-l"><span>00334,</span><span class="z-keyword">0x1c3457cf9b7bde27ad51086fb1ea494d78e82217cf2477f79ac8fc4cfa610f25</span></span> <span class="giallo-l"><span>00335,</span><span class="z-keyword">0xb191a95efc41af23eaf794aea75d4b4c9308a85647f6793201533b30b3d9d368</span></span> <span class="giallo-l"><span>00336,</span><span class="z-keyword">0xb5318d5c8c6f173084a7d838110e3e3de8739123b4ec387658c0b579cb87fcec</span></span> <span class="giallo-l"><span>00337,</span><span class="z-keyword">0xa84d51fe94498ad9c2f558ad6fe685d9aa73ef5ab52c794861277e690ff27d65</span></span> <span class="giallo-l"><span>00338,</span><span class="z-keyword">0xf0b5744f941d4eea8fa255edaa9f7af5028da4900c7fd0b2a1214b00c33f96fb</span></span> <span class="giallo-l"><span>00339,</span><span class="z-keyword">0x5a637c4c3cebacbb0caf5c8bb9080288270e8f2ad3106e50ce82a65bc27386a5</span></span> <span class="giallo-l"><span>00340,</span><span class="z-keyword">0x6bd16b95991a8cfb3671511c673093106b4aa7d626edd4558bc58ca67f8054c1</span></span> <span class="giallo-l"><span>00341,</span><span class="z-keyword">0xe0d9d5cba01b6dc8c430de66d0503e58b9be6195e7a767fc26e15277af7a08fa</span></span> <span class="giallo-l"><span>00342,</span><span class="z-keyword">0x203bc599777747671b50d1ddcc78edc4a180537d2e6fe14610426772d1caf926</span></span> <span class="giallo-l"><span>00343,</span><span class="z-keyword">0xa668f92ec27ced688ad1ce7eeb4f437996bdc213ab001f5d548f5e283f243754</span></span> <span class="giallo-l"><span>00344,</span><span class="z-keyword">0x9cfd6013d6c92d918e19c4b6118dcf5d73e9070af0c7300f8db0ccc7fef5e89a</span></span> <span class="giallo-l"><span>00345,</span><span class="z-keyword">0x54595ee743dc095ed8c3a82f1c0ae34ab2ef7ebb494286a990be0f6b9e85e6a8</span></span> <span class="giallo-l"><span>00346,</span><span class="z-keyword">0x2297e35e02ef969b43a787aa88feb7e101a21fb5d73a81af1c4bc06c57a7c3bf</span></span> <span class="giallo-l"><span>00347,</span><span class="z-keyword">0xdb8912b310472c79894387c19d79d84113709d05057c043380ec4ad8145991fc</span></span> <span class="giallo-l"><span>00348,</span><span class="z-keyword">0x1dde5ab9d554e74a5635f8042ccee5454b215eb598cfbf696a74a459fc1ec87f</span></span> <span class="giallo-l"><span>00349,</span><span class="z-keyword">0x7e25d7fe6b0e71c03d401537f46ea1628e91513cc3991171227d6ec165058e2e</span></span> <span class="giallo-l"><span>00350,</span><span class="z-keyword">0x2bce5715759f8e6f9f17a735408e410f9965ac3cfd27e2c710060f3778d662b2</span></span> <span class="giallo-l"><span>00351,</span><span class="z-keyword">0x112b61e1ad4e349919eadac971bb9128d385eb3f51668b2895cb978f148a83f2</span></span> <span class="giallo-l"><span>00352,</span><span class="z-keyword">0x2ffd764d428f87651d62f1a1113874042f1c77dee8b999524e896663e1a0e000</span></span> <span class="giallo-l"><span>00353,</span><span class="z-keyword">0x8d5ed81a06d6bb19866099c16d80a7dfe3ebf9c642236410a5f3f491fabab7b8</span></span> <span class="giallo-l"><span>00354,</span><span class="z-keyword">0x78c57cc6fa8c8eaee7bef3b0573faacf9a42783f39c9a307a3cebd4a66a56e37</span></span> <span class="giallo-l"><span>00355,</span><span class="z-keyword">0x55973475ad5f1404bca12aec3688d80cb5881796a9d0a9a917245f8ed9bed47b</span></span> <span class="giallo-l"><span>00356,</span><span class="z-keyword">0xc7493a6e7fcfb05ceb9f11b9af843556bea9f87883a2ee21ee76cbbb769204fb</span></span> <span class="giallo-l"><span>00357,</span><span class="z-keyword">0xe5dd91711b000ce8cd41d02ec760a50625f924fcf7a095353f6965322881fb94</span></span> <span class="giallo-l"><span>00358,</span><span class="z-keyword">0x60ed8451fe763621afb94803cbec04b48e9ab83c8d05e2ec1524e623dbe0decb</span></span> <span class="giallo-l"><span>00359,</span><span class="z-keyword">0xeeb9573da28cde717ede462163188da0c184c4aa61e166e9bc4ee047fa0c170b</span></span> <span class="giallo-l"><span>00360,</span><span class="z-keyword">0x277ba2fed1fae84aa2b23a43872100f00b7699326a22df5679115b1dd88c5206</span></span> <span class="giallo-l"><span>00361,</span><span class="z-keyword">0xfc97c47f7bf57fce450809d63a32e255db170aa3fbc94c88d9b15a09f22e2f8f</span></span> <span class="giallo-l"><span>00362,</span><span class="z-keyword">0x77f810e72a7d1aa4a164ba9f7bf0164b6f14842dda65d584508d7f403942c319</span></span> <span class="giallo-l"><span>00363,</span><span class="z-keyword">0x056ef66ff214f7a777abda23d7c32c1ed17e2d25f3e5e4299e11c22412bfb1df</span></span> <span class="giallo-l"><span>00364,</span><span class="z-keyword">0x374faafad27fc139a45b9a73cb5957de978227d494de6cbe4d9bb4d48fc26197</span></span> <span class="giallo-l"><span>00365,</span><span class="z-keyword">0xa959566e36f4790873b779f74d0b31b5c08b4177e844e430fee9c33c190839c2</span></span> <span class="giallo-l"><span>00366,</span><span class="z-keyword">0x905c4a521e63de87fdd413379e245a1c8c2aafd1cf92e5ed6394892a635e62a9</span></span> <span class="giallo-l"><span>00367,</span><span class="z-keyword">0xed4e7dab8d5ac5eb9d4e3b711be5a5074eaceee1936455fc145362871d64faae</span></span> <span class="giallo-l"><span>00368,</span><span class="z-keyword">0xb4a84335f5900e1df9ffd45af119abb6808b69960359257826702a0792dbb9c9</span></span> <span class="giallo-l"><span>00369,</span><span class="z-keyword">0x1f3be8331532a43391f286dce1908e750c2c1db4f40e04240df8a49b15077ffe</span></span> <span class="giallo-l"><span>00370,</span><span class="z-keyword">0xccf6672e6da5a00cd8ce25a1dcd7ac9701d10e13db51b249cec8a168fbc1fad3</span></span> <span class="giallo-l"><span>00371,</span><span class="z-keyword">0x1aa762ac08985e6a081e59742827fdcaa0194f37db5a03574bea395a548c1ae8</span></span> <span class="giallo-l"><span>00372,</span><span class="z-keyword">0x05d7f23c6cb10f2e5ea143504193e0c18799879225cc7bb9f548c2a7bca406a5</span></span> <span class="giallo-l"><span>00373,</span><span class="z-keyword">0x9a8322055f128164d9b1ae8be520dabd5aa9a78e6b38887d2d0ef1c29f8fe5fb</span></span> <span class="giallo-l"><span>00374,</span><span class="z-keyword">0xdab73b8e1681ad78f5948c11596f320dc9e37833a372a4bb75131ae27144789d</span></span> <span class="giallo-l"><span>00375,</span><span class="z-keyword">0xe97d6f9f8cf09791cfa7d844116e30f30c0c25a010500db0721e1a0794a0f0bd</span></span> <span class="giallo-l"><span>00376,</span><span class="z-keyword">0x6af73957e98a3366086abd58c1d750803706d7bc3ae2bbbab4eb6030d58cb244</span></span> <span class="giallo-l"><span>00377,</span><span class="z-keyword">0xfa0bd020aa5cff144e0c34ec5a67a63cd593c607905dfd7a8697796a7641385d</span></span> <span class="giallo-l"><span>00378,</span><span class="z-keyword">0x85b101eb40a52a559a3bffc4667c2fa220ad9cacca9a34c62c684e87cafa5e56</span></span> <span class="giallo-l"><span>00379,</span><span class="z-keyword">0xfbe01c0b7b7e3e3434a5a4723c3619f544c6fc91324421172c74b3aceb816f39</span></span> <span class="giallo-l"><span>00380,</span><span class="z-keyword">0x3e90265a2de6ab0f66324c687364be3c3a4bf46b96fb5dedc4da99c2a59c66f2</span></span> <span class="giallo-l"><span>00381,</span><span class="z-keyword">0x0b316492b1f48b2a578bf289dbfdcfeccc756410f0260e2b14b8b2bf972ab173</span></span> <span class="giallo-l"><span>00382,</span><span class="z-keyword">0xa02e585dc76ee230753d64e6f49d31f6c785e03834bba8acc2fe3f97b2b0de67</span></span> <span class="giallo-l"><span>00383,</span><span class="z-keyword">0x2198573b3c6f4e37218236277eb87d39d60646c6a46b7f516de4ee75f7eb57cd</span></span> <span class="giallo-l"><span>00384,</span><span class="z-keyword">0x0c367f630c9a45d6320139277a8d2f880118a31a856daea875c5a095986f50fa</span></span> <span class="giallo-l"><span>00385,</span><span class="z-keyword">0x8893c8da5a5e2df4e794962fd80bf6d4b8785de5ec445115f1851f601d92afc0</span></span> <span class="giallo-l"><span>00386,</span><span class="z-keyword">0x30637c5e41cbd7671b1b2744d5abde33576904c2fb999de2262dde69d552b4e5</span></span> <span class="giallo-l"><span>00387,</span><span class="z-keyword">0x069b5e283383b315d1a151162386e05161a9ae0704c2b5d3162d18fe91445c14</span></span> <span class="giallo-l"><span>00388,</span><span class="z-keyword">0x82890633807a55f66db32bbfbc7eddec26666cf69d927c6ec17d3e52839f3d3e</span></span> <span class="giallo-l"><span>00389,</span><span class="z-keyword">0xdef916eb755fd6d271775e79079003b9851e520c744dc2fc544599069a2f9a2b</span></span> <span class="giallo-l"><span>00390,</span><span class="z-keyword">0x00f646779628de768f0a78b66f79310092a7eed1b1f42d871bc14945b31c4dab</span></span> <span class="giallo-l"><span>00391,</span><span class="z-keyword">0x6055482350dcadf13a115468db04f05b533177f9cb92ce0d1174e80cf72ffe92</span></span> <span class="giallo-l"><span>00392,</span><span class="z-keyword">0x01eb08ec62a30cb0bc16493c077396adcf2921cf45e7fe07f8ad8a9eb3cb2486</span></span> <span class="giallo-l"><span>00393,</span><span class="z-keyword">0xa5b5b2ed61c5a22e51f28e7081d3c57657bfe1ee7ca90ba380e21b0c29bb871d</span></span> <span class="giallo-l"><span>00394,</span><span class="z-keyword">0xc96f2c65a9b708e26fb06146840df2ba2fee86811fc64b8b03cb8da0e864cf21</span></span> <span class="giallo-l"><span>00395,</span><span class="z-keyword">0xc7c791690e0a24e565ad4325f0916eacd1472c5c67ed9d08007f519ab5ea4751</span></span> <span class="giallo-l"><span>00396,</span><span class="z-keyword">0x98f01c73bc56a14d597f9a2fc522c1f9ce473d5aebcf9f025bf85e10ab5e69b2</span></span> <span class="giallo-l"><span>00397,</span><span class="z-keyword">0xece428f5e482195f4fc650d8ba4535cdc50da4bbd6daff83dabf40f0fc1cb264</span></span> <span class="giallo-l"><span>00398,</span><span class="z-keyword">0x15d52476e016b06a31965a6f867703d8e72de4d75952ea588619e24d16946860</span></span> <span class="giallo-l"><span>00399,</span><span class="z-keyword">0x07f402789b0a04c5c653605ae4a4d9b538575eb278790ee1fca13e1f47aa85a4</span></span> <span class="giallo-l"><span>00400,</span><span class="z-keyword">0x837a78da3c31e197110da75373e9161ec3630eac20956d4976bfdfe5a3f76705</span></span> <span class="giallo-l"><span>00401,</span><span class="z-keyword">0xf319bb85477c7540c8296e257ae3e9887477cc5ce6615e79ff465e67447ef449</span></span> <span class="giallo-l"><span>00402,</span><span class="z-keyword">0x28918ded462955d7564a1cf7515dcde37e47a0bf649af47ce19c1bd2f42420f2</span></span> <span class="giallo-l"><span>00403,</span><span class="z-keyword">0x8d3e10d5ddb059e88145c8a640d6f435b50abf014464ef4112bb7153172e8712</span></span> <span class="giallo-l"><span>00404,</span><span class="z-keyword">0x729d063ef003bc0cd25960f423adc378a96f94bf330e2894980e229c7f792827</span></span> <span class="giallo-l"><span>00405,</span><span class="z-keyword">0x3857def7fbba5ea6f0330f98e7810ff7efec3dec752c7a72961925ebb55935ab</span></span> <span class="giallo-l"><span>00406,</span><span class="z-keyword">0x7be7d5cd302192b0891e799f7fd3dc6214225bac396740ca00eab0987afa0e15</span></span> <span class="giallo-l"><span>00407,</span><span class="z-keyword">0x0a5da5b2bd5353f6dfccb3173ffc30d765f1abae1eb3fe1a2ba70a4c9e69144c</span></span> <span class="giallo-l"><span>00408,</span><span class="z-keyword">0x4ef48eb40d14a101421b182a44e62e46058b24a968731f9672658c2998359339</span></span> <span class="giallo-l"><span>00409,</span><span class="z-keyword">0xe4148ff741b9ad3ceebc501e8db8796f923b39918bc4e003164b490a0b61d9a7</span></span> <span class="giallo-l"><span>00410,</span><span class="z-keyword">0xb195d1d07cd0b541bde741b4086345048fc40eba5c36958db1e84b72f813f9ce</span></span> <span class="giallo-l"><span>00411,</span><span class="z-keyword">0xab2766df14efa74b0e28bb35708e39d6b1ca1d0bca5a94ef65b5aedfb53bb200</span></span> <span class="giallo-l"><span>00412,</span><span class="z-keyword">0x4fcf3d8ce7b02562b9f72decca131bda4095b44bff685e901c1a5b5d29ad1bdb</span></span> <span class="giallo-l"><span>00413,</span><span class="z-keyword">0x371970b092f836d650467a8ce9b049da8e286f73b4ef1063380be6ec1c07622a</span></span> <span class="giallo-l"><span>00414,</span><span class="z-keyword">0x7525f2eda283e525441c353da10bdc982c0b1ff04dea2c153b3543fdad000b73</span></span> <span class="giallo-l"><span>00415,</span><span class="z-keyword">0x4820498a2f344d87b28241909d366f5be00766e75b23645c45a09c75ec8dfdb4</span></span> <span class="giallo-l"><span>00416,</span><span class="z-keyword">0x55dcafa7fd60cb0110e64c6d5cc69db5f031a572e110368f9067151b0890a0f6</span></span> <span class="giallo-l"><span>00417,</span><span class="z-keyword">0x9a836ceab0f6c37b3523b9df29cd0434d420819221ef1063600765b3ca5f522f</span></span> <span class="giallo-l"><span>00418,</span><span class="z-keyword">0xc524844779cb06e98494028130b971a762f7e249dd1d79e08acfc33d7927aae8</span></span> <span class="giallo-l"><span>00419,</span><span class="z-keyword">0xaa00e84454c9ec2852bedc300676f8d20bda558c13442ec8b9a148fbe5d37098</span></span> <span class="giallo-l"><span>00420,</span><span class="z-keyword">0x1a718263b17245356ffb42bb178e9590283ea2e0a82ff52dab5f904da8951895</span></span> <span class="giallo-l"><span>00421,</span><span class="z-keyword">0xb7a7719554eabde85fa9f5bac7580c6f352f60a460f9a07fbe87fff47ba7c19d</span></span> <span class="giallo-l"><span>00422,</span><span class="z-keyword">0x05e01b82ba2d8b2fda2a7e149186ae56e933298b9251269a4e2eab1717f44fda</span></span> <span class="giallo-l"><span>00423,</span><span class="z-keyword">0x0c5c203528a51dc0cc9a0852cea64ed0debab06b3ac95d012870589a5ae4c0a0</span></span> <span class="giallo-l"><span>00424,</span><span class="z-keyword">0x7d31cd1ad7743f0c08549c8aba82c3914de61f8637f768725812dae0be1c3cf5</span></span> <span class="giallo-l"><span>00425,</span><span class="z-keyword">0x737fc2002808f4c81dbad877b69160a9ebdc3f8382b5e1f2f08defce897857ab</span></span> <span class="giallo-l"><span>00426,</span><span class="z-keyword">0xb042cd22b27a2d46775de19a0fe07ea0187139b69a8a5f9f8ad680b49a50e81c</span></span> <span class="giallo-l"><span>00427,</span><span class="z-keyword">0xa5f8fadbaf1e1b1c025e9ca7646d214d84afa0d2575026bfd188492553ad2dc9</span></span> <span class="giallo-l"><span>00428,</span><span class="z-keyword">0x2247adf42e4fabead0c52c18fd8d9c3d378b6a82dc3941e9f2e7c03a3e6a5316</span></span> <span class="giallo-l"><span>00429,</span><span class="z-keyword">0x1cae28d5c467521d0a2986ae1ab697c0137fb88a2cd57b7b65e1087002f4ca8b</span></span> <span class="giallo-l"><span>00430,</span><span class="z-keyword">0xab59cee6f8c573ce2e2abac2865d1590cdcc0e4289aa75144582810327d2bffd</span></span> <span class="giallo-l"><span>00431,</span><span class="z-keyword">0xed24090f25bc8dca7749c25f4d6a81a6c0421251b40e9fefaaf7896a49e1cec8</span></span> <span class="giallo-l"><span>00432,</span><span class="z-keyword">0xecfb2f473b32475d203492960f9c706024ad7be82ced8dd0f9506c2cedf3b29f</span></span> <span class="giallo-l"><span>00433,</span><span class="z-keyword">0xea10cb3faf85fe26801f5c5c6f963aa09936d48cc6070abdc86ef7c1ab93eb6b</span></span> <span class="giallo-l"><span>00434,</span><span class="z-keyword">0xed8823c84177d8ffabf104566f313a2b2a43d05304ba6c74c2f5555bae0ef329</span></span> <span class="giallo-l"><span>00435,</span><span class="z-keyword">0x1acee0de8d8fa5a692ca7fe4e6e6b6070264bbce1d27bae29aa96794a92fffaf</span></span> <span class="giallo-l"><span>00436,</span><span class="z-keyword">0xc3510bf4ec6f2561e65ef90ac5f69719835bd88ebc526470a11645a2c743696f</span></span> <span class="giallo-l"><span>00437,</span><span class="z-keyword">0xf2dcc620fcc9352d6e87c27c30f9dcbc38e05c66d4cc315a6b04b3007234821b</span></span> <span class="giallo-l"><span>00438,</span><span class="z-keyword">0x00f5e21daa244de11bbc15728bcda77c7c15fd858252459ad7c10c0ac877ae9c</span></span> <span class="giallo-l"><span>00439,</span><span class="z-keyword">0x5149508dee482fd1927f619b3984641ee6a4cd545e763475d97a759cdd6b9ce4</span></span> <span class="giallo-l"><span>00440,</span><span class="z-keyword">0x9feb91891bf0aa0981ae9b6d8a71dbec00cc4a2ebf9a94a0aecc1815d621b2c1</span></span> <span class="giallo-l"><span>00441,</span><span class="z-keyword">0x3f1832caadae9d68b7056679e7e36db138a48754d0bd69f0f7c369ecfff7763c</span></span> <span class="giallo-l"><span>00442,</span><span class="z-keyword">0x1d30de4aac58ef2504ba7fca3cdc0536a6129314efcf91c713578bebd2182e6f</span></span> <span class="giallo-l"><span>00443,</span><span class="z-keyword">0xea71b6f9916c2fe3cee071ccbbf4105935e111b40d71ecc3b327ae5a992a6d49</span></span> <span class="giallo-l"><span>00444,</span><span class="z-keyword">0xc56da958661c206315768f8f855721cce15e24ff1f350b294a1331eb29db56e2</span></span> <span class="giallo-l"><span>00445,</span><span class="z-keyword">0x02cff3d78ac49a70b6466ab49a54dd2695b8ae3a423b9e52dae2351864ad4e4d</span></span> <span class="giallo-l"><span>00446,</span><span class="z-keyword">0x2280f1cf6ebfeddf1211be1d8801bb188f0afb1626da2921ee603ede2bbcf926</span></span> <span class="giallo-l"><span>00447,</span><span class="z-keyword">0x3cff32e3d7dbda7c7efec80b3c9ceaf9c56b9d5d0c03b53cd12897c0ecb8a59a</span></span> <span class="giallo-l"><span>00448,</span><span class="z-keyword">0x7dd2c4f161ae53d17ee1bce79c6dc3a848fabc81c2ed01d08d768e02c7ae8b19</span></span> <span class="giallo-l"><span>00449,</span><span class="z-keyword">0x6d1d274b948411de02b87258045266f96be9a450a363da2482a1219aecf586cf</span></span> <span class="giallo-l"><span>00450,</span><span class="z-keyword">0x2b5e114981c6f32c8a3b78fa35ce6132d9ca9b597dd94ffd91b77657f5e51be2</span></span> <span class="giallo-l"><span>00451,</span><span class="z-keyword">0x4abe0e076ff522ec7b0eaf0d6751f9dfb7f164b42864e0255f1502a77315178c</span></span> <span class="giallo-l"><span>00452,</span><span class="z-keyword">0x42606107511944b1c7dc61fd2d3467fc43128e69092df1eef47479dbca67f3e8</span></span> <span class="giallo-l"><span>00453,</span><span class="z-keyword">0x23cdebe00f8b0071fe04101936e236e3dcb4e58b94a8101a0f449ec38aaf53b2</span></span> <span class="giallo-l"><span>00454,</span><span class="z-keyword">0xb2b5e5f97f7552d912156e250165b87cf670d32260186a1a41c47bd53e4b7f51</span></span> <span class="giallo-l"><span>00455,</span><span class="z-keyword">0x54943c8b31b13a4f0cc4f3472967383de372b4ca8f89979f6043d44ae330888b</span></span> <span class="giallo-l"><span>00456,</span><span class="z-keyword">0xcab079083dd2ddc43386c219d265ed110b97d315943e37e859764ddb5c380a2c</span></span> <span class="giallo-l"><span>00457,</span><span class="z-keyword">0x82d06ed1ec9bfb436ed64caeb0a1c99efdc719d79167ec9600fed7802c5cb1ba</span></span> <span class="giallo-l"><span>00458,</span><span class="z-keyword">0x2bff3cd79eed0180444dfcbfb8fb93579be52e5d0eb92fcd3ae6c70702a93254</span></span> <span class="giallo-l"><span>00459,</span><span class="z-keyword">0x29e03017ed0f32215c0705d87beff1ecde7afc804217ec41c250a0541e71dd67</span></span> <span class="giallo-l"><span>00460,</span><span class="z-keyword">0x6f2ddb12b11f17f35b123ca3692ac57b18043af935e33eb2f662fa0fe862a866</span></span> <span class="giallo-l"><span>00461,</span><span class="z-keyword">0x86535bae04792f1724aabb2201189ef0b12ca7624e1e9fd296d129d3ef1f74f7</span></span> <span class="giallo-l"><span>00462,</span><span class="z-keyword">0x3658342ed3dba9eedabc93cae0d6cc657bedef4d1dc6c631113af874dd65fb64</span></span> <span class="giallo-l"><span>00463,</span><span class="z-keyword">0x4f586d74db2e09c1ddb553421304a352ae8ca4dfcdd49cb9905c83184cd1050d</span></span> <span class="giallo-l"><span>00464,</span><span class="z-keyword">0x2da57d6c84f0f2de638453005d496136fac3d1a4957f0e6a8aca32070522c965</span></span> <span class="giallo-l"><span>00465,</span><span class="z-keyword">0xafdd52d62167b3f4a6e0c88d5bd5fffd1f4fa06a528e52f2cf3a095cf5f84fea</span></span> <span class="giallo-l"><span>00466,</span><span class="z-keyword">0x21cf05fbe816d55dc025ddc38f55aa7e66bcdb98ccff8abfd031c0832f69dd62</span></span> <span class="giallo-l"><span>00467,</span><span class="z-keyword">0x27685b9d5efe40fe088b50b9a1ea62e8dadeb0425171ad45e6bcc3c283af2acf</span></span> <span class="giallo-l"><span>00468,</span><span class="z-keyword">0x610466b6f8c2771439da2e8a7343c8d961a040e3bbc73ca6c661e4a13f977132</span></span> <span class="giallo-l"><span>00469,</span><span class="z-keyword">0x8c5751e2b93bc6f0ddffd243332a890e3794bb3de71a80ca45c95b971be88167</span></span> <span class="giallo-l"><span>00470,</span><span class="z-keyword">0x2e445b03b86127fe3149c740429382afdd2d0bd2e1ff0b1f05ece2e23470017c</span></span> <span class="giallo-l"><span>00471,</span><span class="z-keyword">0x7f37562302193a70baf1096ce39a616be3737721795d7a106ca321593f29af71</span></span> <span class="giallo-l"><span>00472,</span><span class="z-keyword">0x5f279db60b9c122ef92a239345b84ae0d9d6ab6399ef756e89078c9ded3df15c</span></span> <span class="giallo-l"><span>00473,</span><span class="z-keyword">0x5ae48eaec56b9a49cbb966ec90af455eaa03ee66604e50195cc6ca4dc3f0e1b6</span></span> <span class="giallo-l"><span>00474,</span><span class="z-keyword">0x8b70d9c82bf64392306a74b2075f1218f3e25ff143962e2c63d0300437bd9794</span></span> <span class="giallo-l"><span>00475,</span><span class="z-keyword">0xa8e53747848b2eee9050ce20905f07d99282ae9a35ce825ea1b7faf09677a468</span></span> <span class="giallo-l"><span>00476,</span><span class="z-keyword">0xdd34a7c17094183961aa4c17d9cd6e2e73daeac22f27af1f0d948772d9727e11</span></span> <span class="giallo-l"><span>00477,</span><span class="z-keyword">0x488d852ffe678ca5d7fd3b4f04afeb893595b929c6a968c2b8e6ff7204be27bd</span></span> <span class="giallo-l"><span>00478,</span><span class="z-keyword">0x232a4fc9a0cf3b37008375f24a562c44e25a0f54774e2384db37ea0acc0b599f</span></span> <span class="giallo-l"><span>00479,</span><span class="z-keyword">0x4b082f2481b4819595dba7d5f02505e200b32e78c59100241de37b51720217e1</span></span> <span class="giallo-l"><span>00480,</span><span class="z-keyword">0xb54b802e1b7923c298d222ff23b5f0d1c8b76b886c764b517a1e29bd4801ebe0</span></span> <span class="giallo-l"><span>00481,</span><span class="z-keyword">0x213ae81b453ef36e78b560492832c28c71db8bbb5d12816cf0477c16155ab8d6</span></span> <span class="giallo-l"><span>00482,</span><span class="z-keyword">0x5d09d6eed5b020f1268016d5117587d519d1aaea97b575c6ab24a85135daab13</span></span> <span class="giallo-l"><span>00483,</span><span class="z-keyword">0xf3c11c6e063ba5b267f6616529b2495424a633e08f6a78bedaa660496914ca81</span></span> <span class="giallo-l"><span>00484,</span><span class="z-keyword">0xcdc41b84ddcf6530555d2fd03651ca3fcc29981f4b9df53944efe410442174c4</span></span> <span class="giallo-l"><span>00485,</span><span class="z-keyword">0xb26f2e53df52942461b1c54800e6eb25858b1d86f9bee68c40b8f13ca1fb44bd</span></span> <span class="giallo-l"><span>00486,</span><span class="z-keyword">0x82b8c438d8704a976289eb09500c628a3c07ceaca62d081de94e345d14bf58af</span></span> <span class="giallo-l"><span>00487,</span><span class="z-keyword">0xd834f157ce0cabf68f199cabbda6fe5a47256b25acbfaabd376ee9d28d2366c3</span></span> <span class="giallo-l"><span>00488,</span><span class="z-keyword">0xfa3989a5ba10e3c27731de69a30136ee3ea9e603cb27d12e2a5f32afa60ddada</span></span> <span class="giallo-l"><span>00489,</span><span class="z-keyword">0x4db390c5cb4c32c03d7f9cd7b8823b700e9d64da825194b83e3df46ce5751864</span></span> <span class="giallo-l"><span>00490,</span><span class="z-keyword">0xb9ad2e4d9c6627f63d60befc8778777c829594a044f464f12956c904486f7691</span></span> <span class="giallo-l"><span>00491,</span><span class="z-keyword">0x6aa98f9f56f6ef66ad09f15071de716f61e203ab7a31a98737fd5c46649a14e2</span></span> <span class="giallo-l"><span>00492,</span><span class="z-keyword">0xebdcd70d9e477a11b4fc48d3258dd5bcf6c9222db25dfef74dff86487714b798</span></span> <span class="giallo-l"><span>00493,</span><span class="z-keyword">0x3079f6253e59035a7e4a039275e685c9017d7e1055252fcc7db8c4a5c9bac205</span></span> <span class="giallo-l"><span>00494,</span><span class="z-keyword">0x33f97b590b8f704670771f738f9df52e2037a876fb185f0cecb89fba754af618</span></span> <span class="giallo-l"><span>00495,</span><span class="z-keyword">0xee3904aea19ec5886c2f52956576a8e81fa4b2bacc4464257c1dc3190d6694bb</span></span> <span class="giallo-l"><span>00496,</span><span class="z-keyword">0xcdf13c18466bff16c454c4548995f6d11eb639ebfe71dc793b648066cbb23cb7</span></span> <span class="giallo-l"><span>00497,</span><span class="z-keyword">0x27f7ad957db315648dae2007f3c0c8d7ee81a6c7c3cba09119091325e7ffbf9b</span></span> <span class="giallo-l"><span>00498,</span><span class="z-keyword">0xfed48beb69c269ece25dd3b123aae953c66433728e03370df36a76624736b61f</span></span> <span class="giallo-l"><span>00499,</span><span class="z-keyword">0xd9c9a7333aded4d0f68412484ca0032f348c55ce9ecf21c986d22855625b3ba3</span></span> <span class="giallo-l"><span>00500,</span><span class="z-keyword">0xb11653db38e95638077c58252fa5695f38b933a229decc1bf3d1dd124c0d5f00</span></span> <span class="giallo-l"><span>00501,</span><span class="z-keyword">0xb202cc73bfc03b7f9f584614f21533221cbd0acc95409239090ddc52b5f27d9a</span></span> <span class="giallo-l"><span>00502,</span><span class="z-keyword">0x19ef7cc080401251d654b9529fe8018fb1bc1a58cc6b99e8a5a47a40872c5955</span></span> <span class="giallo-l"><span>00503,</span><span class="z-keyword">0x45f20620961362cc0f7f6e4f3fe15312150eb015de00fe77f6730383c79b9688</span></span> <span class="giallo-l"><span>00504,</span><span class="z-keyword">0x21e3a8f27e2686892a5cf54955dbf7509feb97114352d211efa8573dc344245d</span></span> <span class="giallo-l"><span>00505,</span><span class="z-keyword">0x6dd1ba5667a00e35a95d075c187344e3dd341c0b96e9d7c686b1cf8768e2d4ad</span></span> <span class="giallo-l"><span>00506,</span><span class="z-keyword">0xc0414076dded3d476fba3387ed8b0eb57402f1017dbd117dfaa64eebeb162f24</span></span> <span class="giallo-l"><span>00507,</span><span class="z-keyword">0xa7340f2eaab8704157b80028c86a7f0cb1fef4864da34554f08dfcb614cf4955</span></span> <span class="giallo-l"><span>00508,</span><span class="z-keyword">0xdde4c38d485ca458dcaf7dd54cbd451ee8c9eeae251d59b2f5fa6faa97280a14</span></span> <span class="giallo-l"><span>00509,</span><span class="z-keyword">0xfa5dc42a17a4f780caf728dfc049b9fd56455f05e2ea06202c763ec143b9fd6f</span></span> <span class="giallo-l"><span>00510,</span><span class="z-keyword">0xea2b8d47198cfdc653a2136b98df5615aee70388df0c64eb5cfb90cacd50a931</span></span> <span class="giallo-l"><span>00511,</span><span class="z-keyword">0xd5d2416f6a00df2713ec8fa6cc13ef973d1eb9d900d852903fe1046633599565</span></span> <span class="giallo-l"><span>00512,</span><span class="z-keyword">0xe2918e5026ffd68825dd25cad6ed824a9ab0a4fa4b85a35c4ecf4ef8e0544d08</span></span> <span class="giallo-l"><span>00513,</span><span class="z-keyword">0xd39eefadcb758f4e3c4e4b34eef2e976c6a3959432abcebdfc78d06bcc3148d4</span></span> <span class="giallo-l"><span>00514,</span><span class="z-keyword">0x8bd8f6bdf0226ae2173194ea147c71af760a5c0c661ff1f5ad7cac137b1b6d83</span></span> <span class="giallo-l"><span>00515,</span><span class="z-keyword">0x66d4642ecbc838dc65765a4fcecd474b20b9ae0637244181a84bb373b13d5601</span></span> <span class="giallo-l"><span>00516,</span><span class="z-keyword">0xed3b11872cdaf7b8feb4ba80cc6635e2123473ceec8e939eb46471c70872bb97</span></span> <span class="giallo-l"><span>00517,</span><span class="z-keyword">0x5ef487b21fd4c9f018e1c42787966f14f32ed2e1581fd159ea1e4259a6d73cc8</span></span> <span class="giallo-l"><span>00518,</span><span class="z-keyword">0x710270293ed9c587e43e725361f93c98be4769eace47c2016e4189ef59c5b7e4</span></span> <span class="giallo-l"><span>00519,</span><span class="z-keyword">0x218c3b62dc99a297a595e41cca22f5f8535ff99908dc03940c9e4a855104b61f</span></span> <span class="giallo-l"><span>00520,</span><span class="z-keyword">0x062e17197c2a5da9db37319b5a50917706cbb5b2f94436f231515944f5a533af</span></span> <span class="giallo-l"><span>00521,</span><span class="z-keyword">0x5b55367f4c641c3f847e97b9507772f3defe8e7a7b7e7ba7485a5350838e1786</span></span> <span class="giallo-l"><span>00522,</span><span class="z-keyword">0xdbca1ed318fb0b730386df7aa1e3093735b7579852cfc869c4ef4bc80cdd6564</span></span> <span class="giallo-l"><span>00523,</span><span class="z-keyword">0x297cf9d5925da0389d57e13787de1938ca0efbc4fdf2683d957e86f076191df4</span></span> <span class="giallo-l"><span>00524,</span><span class="z-keyword">0xf389f3b6336ac065daf31616b7dad80bf6e725ffa95b57da3cea36466c04fa47</span></span> <span class="giallo-l"><span>00525,</span><span class="z-keyword">0xd851e82289f5aeca6786aab0281c156e6e75cce90fb8689cbbbc6cff69f034bd</span></span> <span class="giallo-l"><span>00526,</span><span class="z-keyword">0xc69972a185d32c7419238da9577424406252b97d93001e401d8649fe6991809c</span></span> <span class="giallo-l"><span>00527,</span><span class="z-keyword">0x2c103256a2b901f09cd43ae21da8743d4b7c8e5c925d98a67de5579de1d89630</span></span> <span class="giallo-l"><span>00528,</span><span class="z-keyword">0x32a674ae21d37007a12f57639d299bd71d378c127c3b5bf80d9b7b72f8a89800</span></span> <span class="giallo-l"><span>00529,</span><span class="z-keyword">0x1bf711d19f7b6ee55cebb887105666aa7f30c594081b4b9bacca5b42c935d68c</span></span> <span class="giallo-l"><span>00530,</span><span class="z-keyword">0xaab9d4e3f1f4a07e2dc09ecd78ee8fdd50daf8ec5349ce42d33e93e73452e1c9</span></span> <span class="giallo-l"><span>00531,</span><span class="z-keyword">0x0f51dbcac068fc62805ec9b43a0b1b83c683b23f255eb63cd81ea3e2562953ca</span></span> <span class="giallo-l"><span>00532,</span><span class="z-keyword">0xb4c6703d6f10db4d87cfd07d94c45cdf6176fc42656997210ed219af1320df18</span></span> <span class="giallo-l"><span>00533,</span><span class="z-keyword">0xbb2932ed5e95ea609fc5a252cc60087f857230da2797d62330595e0647430f1f</span></span> <span class="giallo-l"><span>00534,</span><span class="z-keyword">0xc65d109d82fe28526fe4653452cf09db4db6a254c2c3054b8ce3d6cad489bc3e</span></span> <span class="giallo-l"><span>00535,</span><span class="z-keyword">0xbb367122e14176555be535edd3085bbffe0cfa73f3754ca9eaa10dcae6f60e82</span></span> <span class="giallo-l"><span>00536,</span><span class="z-keyword">0xfaadd066133e49dcb1a5fa2c92f376f3d165c3b276ac75e5881fe7012b2734dc</span></span> <span class="giallo-l"><span>00537,</span><span class="z-keyword">0x576b374c1d32e2db299b04073d838366c4525a766e1c10dd8fe0a79ac2ce45f4</span></span> <span class="giallo-l"><span>00538,</span><span class="z-keyword">0xd8eab6c1d289e8f853425d63e99768ba364012c21537e9be20e9b8999ed94eb8</span></span> <span class="giallo-l"><span>00539,</span><span class="z-keyword">0x2c32d06d103d4b1f9d31779131b008f404e149a5bd8a53f6805ad0331e592281</span></span> <span class="giallo-l"><span>00540,</span><span class="z-keyword">0xf3078a9b01c1741a63baca8c231bb4a482e62d835c4eb3ca3ef752154ef9454b</span></span> <span class="giallo-l"><span>00541,</span><span class="z-keyword">0x3063ad60f10b704d724c082e97a0145796854d3ce3d1550347309657dd36b8f9</span></span> <span class="giallo-l"><span>00542,</span><span class="z-keyword">0x90a242f8e1785389d27726dab026c0e30677713f67c4bc2747673358990aa4d9</span></span> <span class="giallo-l"><span>00543,</span><span class="z-keyword">0xbe9dd353aa0b026bc9363961397d25bb46f26570ea7f90ed982373d6a7115c72</span></span> <span class="giallo-l"><span>00544,</span><span class="z-keyword">0x1c5c761520401a356ed867ac5172ffcf59b1a9b9c6fda3908a4c9474ea075592</span></span> <span class="giallo-l"><span>00545,</span><span class="z-keyword">0xe6369239027eb6239ee703f7e9e6dfdb32dd1a94b70094dfcadc9fbe0154e4cd</span></span> <span class="giallo-l"><span>00546,</span><span class="z-keyword">0x2135141345bcdc69e19b4e3df1ce29a017c07fb80df9b27bc38287c2c5ccd628</span></span> <span class="giallo-l"><span>00547,</span><span class="z-keyword">0x0fd9e031326788cff66e44315940516bf926d51524e880548d90717d0da9d6c6</span></span> <span class="giallo-l"><span>00548,</span><span class="z-keyword">0xe318be79b341bdbc93f1900e82a5fff4f52df9b9a113edbe4bfaa512d1411189</span></span> <span class="giallo-l"><span>00549,</span><span class="z-keyword">0x2dde72e5e61c9eea6351d4ff14794a71685daefea6ed3cf9b62ca9aa99f9313f</span></span> <span class="giallo-l"><span>00550,</span><span class="z-keyword">0xd89b717d47ffb827b1490a37ffd97547694c6ad3dbdee5cd56a3583717962751</span></span> <span class="giallo-l"><span>00551,</span><span class="z-keyword">0xa8dfd8606b55c4f54453ccf9e48838bca6accabcb629be668755b0a13867a77c</span></span> <span class="giallo-l"><span>00552,</span><span class="z-keyword">0xd6a3521a5eaec4c47314a4b123701777fb7ab51af66093ad8c57bde9249bfe8a</span></span> <span class="giallo-l"><span>00553,</span><span class="z-keyword">0xf702584d8c87da3ca916ab9caac71d0a0922884cb8db05cf513d5b4144bac3a6</span></span> <span class="giallo-l"><span>00554,</span><span class="z-keyword">0x700d58da768be40c844feeadc5f42385dab83a5b758aafc432172fc150403739</span></span> <span class="giallo-l"><span>00555,</span><span class="z-keyword">0x41db6d144ada4684a7a61e108131d5d78d250b3e47c8cccc85b447e5b1088a8c</span></span> <span class="giallo-l"><span>00556,</span><span class="z-keyword">0x3503dd53c35d41dd5df98f30d4a4df5f7c4a456edb598cb5c2ecc91cc81198d3</span></span> <span class="giallo-l"><span>00557,</span><span class="z-keyword">0x02391085f2bdccf3e4774ffe1e0a7fdf318fdebd564f5015c64d6d1edefb34bb</span></span> <span class="giallo-l"><span>00558,</span><span class="z-keyword">0xed670fa946019be6e96bd20ec27eb5c92bd6177ae0a32fc9cbe2c179cf7f536c</span></span> <span class="giallo-l"><span>00559,</span><span class="z-keyword">0x63277435c400bbc4916dcf4d295ab0cb233d68834bcda11cc231e999996628cf</span></span> <span class="giallo-l"><span>00560,</span><span class="z-keyword">0xe89160d7dc2b0d06408df356eb166aad39c73e6fd51e97f5a64d1f6d57fa1686</span></span> <span class="giallo-l"><span>00561,</span><span class="z-keyword">0xf95c755f337bd6df5127911e601a763a36070bda95ec63ab8adbd1fbf148a35d</span></span> <span class="giallo-l"><span>00562,</span><span class="z-keyword">0x97a6fdba7ddb6462d9cae6ecaaf13c2ac670f7db6216547a5c20ef46a9a2af6b</span></span> <span class="giallo-l"><span>00563,</span><span class="z-keyword">0x8aa6ac0e68888875b0afe306759d787609bd56cbad19a9cdbed484cba64b15b6</span></span> <span class="giallo-l"><span>00564,</span><span class="z-keyword">0xba8486b8d3fc13f529e72ac00fddca459b530ff9a9ec0948a7838089401efc60</span></span> <span class="giallo-l"><span>00565,</span><span class="z-keyword">0x7cba894eacdce587e611f2740c3de0d15e3754efe0331e976e1cf0150035fb2b</span></span> <span class="giallo-l"><span>00566,</span><span class="z-keyword">0x54b3e34b615873aa7def6c73d8d45bab4e5f0ee5a9c8e503340ec9bf42e32cb3</span></span> <span class="giallo-l"><span>00567,</span><span class="z-keyword">0x40280a8567c1cab76c46ea7666b3f17b06a6b1d845922feb286020e7c3439091</span></span> <span class="giallo-l"><span>00568,</span><span class="z-keyword">0xad863b1e23e92bc3b1dfd81f66371f01eb200bb178d4c1659b39fecc1d5209e3</span></span> <span class="giallo-l"><span>00569,</span><span class="z-keyword">0xdcb283eaa11602480e3a38aec7563c48bd939a61149760408704f243062dffe0</span></span> <span class="giallo-l"><span>00570,</span><span class="z-keyword">0xfb9123623556bc897c2f316008fddb109a20ce6abbb666bf55d9f0e96aff0dc6</span></span> <span class="giallo-l"><span>00571,</span><span class="z-keyword">0xb65f3342d82ea682030d61222badd0d0032f03a44fb33454fd5965edfb57e9ab</span></span> <span class="giallo-l"><span>00572,</span><span class="z-keyword">0xdc59179d2daa0417c7f7879eee3d53a08066ad558a36cee1535a9b515b0d0cef</span></span> <span class="giallo-l"><span>00573,</span><span class="z-keyword">0x21aec308be98ab2777b0030e3b55220901ba3e4c2059a076086ef52e11e15e9c</span></span> <span class="giallo-l"><span>00574,</span><span class="z-keyword">0x55e72fc99ac693fb34bb00d1ed8611d53d6414693acaaa52fdabfd3099dfc88b</span></span> <span class="giallo-l"><span>00575,</span><span class="z-keyword">0xf6564eb58e1d7f625d3a634513ab089b913301c69a30faa1bb52730be7908721</span></span> <span class="giallo-l"><span>00576,</span><span class="z-keyword">0x923096d4ee10bb045085a46459592497f6314b580c75c62cda1e27c637f105df</span></span> <span class="giallo-l"><span>00577,</span><span class="z-keyword">0x5914605dadf8851cf40c7591ff45b182fc6751a233e8ded429a92df0fca49c5d</span></span> <span class="giallo-l"><span>00578,</span><span class="z-keyword">0x57d591a81cbbb89601aa972f81d25b61b88f534fa7fdbf207611ebb6aa1cc267</span></span> <span class="giallo-l"><span>00579,</span><span class="z-keyword">0x705b8e045b05fb96483e3356c8b0e0120cfef7a8e9649476bce35c26a8d25f95</span></span> <span class="giallo-l"><span>00580,</span><span class="z-keyword">0x5b210184902c591dc9dd3630edbe4d816137515009ff3447144360d49ee26317</span></span> <span class="giallo-l"><span>00581,</span><span class="z-keyword">0xd3dc3f99fc86600deabcc70f3bd7ef4fa9fe70da3a428b2b4ec622012b115d7e</span></span> <span class="giallo-l"><span>00582,</span><span class="z-keyword">0xd6b2c7ef628b2a4e0be27bba141b8f45946d18ad5d17255d9230b21555a377cd</span></span> <span class="giallo-l"><span>00583,</span><span class="z-keyword">0x434001606cc9da452057323ef3d56d1cf3505f9dd19aae59e918617e11e180e9</span></span> <span class="giallo-l"><span>00584,</span><span class="z-keyword">0x21b2682b8046bd14001c17d9a9feb7feda179d3a56f21a722df82042056dd1c9</span></span> <span class="giallo-l"><span>00585,</span><span class="z-keyword">0x02f0b1510358fee5dda91e345cfe38e0e0bdb0643d0165ebc51cd382fd0ed6fc</span></span> <span class="giallo-l"><span>00586,</span><span class="z-keyword">0x60d868cb6169cbec6c74545f6cc362b6b44290d889527a728b1af1f846e9230a</span></span> <span class="giallo-l"><span>00587,</span><span class="z-keyword">0x59cc91f73e2cb552ff57ac76eeb2de51c49f80f237e5e05302115e2d1500f668</span></span> <span class="giallo-l"><span>00588,</span><span class="z-keyword">0xefefa87ce3db08c5545fc2bb64021e8112434e06ec3760bed7b6440d852cd576</span></span> <span class="giallo-l"><span>00589,</span><span class="z-keyword">0x85c8dc20f625a20a8d969f1cd97a54a4c760817067763f9992be2e1e9d2d9e8b</span></span> <span class="giallo-l"><span>00590,</span><span class="z-keyword">0x2bd79cac465f01ebb1eb59886d2b7d2d1c7b7c1debb19d5cea88470aa13fadd9</span></span> <span class="giallo-l"><span>00591,</span><span class="z-keyword">0xd9b21bd9fc16529e92da39239593c1021e195231affab0eed3475b79e01d8c65</span></span> <span class="giallo-l"><span>00592,</span><span class="z-keyword">0x9dd2dc6ad9373a8e5e80ec6ec9eba8b0f2242692bf27a93678270986620a743e</span></span> <span class="giallo-l"><span>00593,</span><span class="z-keyword">0x0a9de411103269d9df322cc24c80bc49e30b0d0021f0a13c84e784a95c1412c6</span></span> <span class="giallo-l"><span>00594,</span><span class="z-keyword">0x54bb502669ff807c87513c7ac708c471efaf3782d0ff9b7dba577dbd5024a8d3</span></span> <span class="giallo-l"><span>00595,</span><span class="z-keyword">0x08fa26596e31b58ac3788844e300b057d53983911166d3848105b53c0b064993</span></span> <span class="giallo-l"><span>00596,</span><span class="z-keyword">0x5e2423f9905b980f953f2c35daf3385540333d41dddd46c710ab7dab864278f4</span></span> <span class="giallo-l"><span>00597,</span><span class="z-keyword">0x49b11d141d74f6eff4a99a858413e3ab5f3d3740c6ed5c705cd66070af051a63</span></span> <span class="giallo-l"><span>00598,</span><span class="z-keyword">0x050d0b97623cdfd0c8d202dc6bf4e0c3a73df861383ed307131163623422e0e0</span></span> <span class="giallo-l"><span>00599,</span><span class="z-keyword">0xa19b1a209ced8078ab2f240886f68b64cc67bd5806a08d472ba3cccefc5eb9e0</span></span> <span class="giallo-l"><span>00600,</span><span class="z-keyword">0xa81ae85fb6a0ebae94d8df6f34414ea890a7ec7621ac195c683a6d6c34a594a0</span></span> <span class="giallo-l"><span>00601,</span><span class="z-keyword">0x9e26205a26df3598d2ec6236069fb7a74c37fa84cf323c4fa09f4bf7412e687c</span></span> <span class="giallo-l"><span>00602,</span><span class="z-keyword">0x287136148ea36dabb0693ef81fe921e25974d96a2724ff0d86b10e3e78302ffe</span></span> <span class="giallo-l"><span>00603,</span><span class="z-keyword">0x9a115bef53f5237d03975ba6c2baf4377bf8e15ac54bf2093375681a38cbf19e</span></span> <span class="giallo-l"><span>00604,</span><span class="z-keyword">0xba62e0022781cddf46d8da27f2c69b7c1dcd33fc184b2329fd59cb187e351d3b</span></span> <span class="giallo-l"><span>00605,</span><span class="z-keyword">0x0d936f160c2fd830cfc16d6c17e87ca0cf6e6b28ec1f6b7d934100e82d61c59f</span></span> <span class="giallo-l"><span>00606,</span><span class="z-keyword">0xae859b842f320c06c3899683b50a2d37a32e1b07786c761fa092e10e572793ce</span></span> <span class="giallo-l"><span>00607,</span><span class="z-keyword">0x62d75fce6440773a1c0e6573ac37e429164c377aa00135c7e1c2e2f7b06a4759</span></span> <span class="giallo-l"><span>00608,</span><span class="z-keyword">0xd449c48d3ab67d1f1f15eaf0dcd5351f9c463f6aa103e6b4ce6a17a3b69bb523</span></span> <span class="giallo-l"><span>00609,</span><span class="z-keyword">0x7e60445e276f7e090b8ddc8a36a01bc4b66faa212588130c1175a5797a837bb6</span></span> <span class="giallo-l"><span>00610,</span><span class="z-keyword">0x2f230cba76af9df75862b04ecf554ad6bb46abd4be7a8e99dc468de6d5905408</span></span> <span class="giallo-l"><span>00611,</span><span class="z-keyword">0x290b8c2bbdea109cbf5209a39382993c21f9d520ff8fd07e85d273de90c5f587</span></span> <span class="giallo-l"><span>00612,</span><span class="z-keyword">0xb363f64740a275f7816130024de8ccfdbd67fae7526a015679bee407a5e5f485</span></span> <span class="giallo-l"><span>00613,</span><span class="z-keyword">0x80a4144c9bb6e7aba587a8a91a1362a5edf92e0fc4dbcd339a717a9200cf391a</span></span> <span class="giallo-l"><span>00614,</span><span class="z-keyword">0x20913bde281d7f10d729b290f509ab76ed07603f32033cb73071f43cef734092</span></span> <span class="giallo-l"><span>00615,</span><span class="z-keyword">0x8b6e7a1e1535c08d0457aacae6cc68c0385a62a35282179c726707090c84985f</span></span> <span class="giallo-l"><span>00616,</span><span class="z-keyword">0xbd35481ad334939158e73a3b0e8214993e9de1202e8a8ff567c5dbf88a3dccc1</span></span> <span class="giallo-l"><span>00617,</span><span class="z-keyword">0x624ad401fff7fe715ab546b1898e5f3e735f42c134d592d49b4615afd5b6d3e1</span></span> <span class="giallo-l"><span>00618,</span><span class="z-keyword">0xc70c6f7e13ccb5d9a1e56381ac39cabeb4c2e9f1693134d59599b7260bfd7954</span></span> <span class="giallo-l"><span>00619,</span><span class="z-keyword">0x1b807cedf382c87a6ee8cf00a7178eba5516948a0318aacb8176f3e577ce0a6a</span></span> <span class="giallo-l"><span>00620,</span><span class="z-keyword">0x850650230838e76460e4ddca3edc33bd286c3f8d40ad3a1ff89b35280cc6510f</span></span> <span class="giallo-l"><span>00621,</span><span class="z-keyword">0x385fbb21923e5bbca8952a90a3d861ba963d83ddd01c9730fe177341cdb25260</span></span> <span class="giallo-l"><span>00622,</span><span class="z-keyword">0x92fb5e57d123f079903c0f55481f913c45d490c7df412a721d38cbc528037875</span></span> <span class="giallo-l"><span>00623,</span><span class="z-keyword">0x642081dd761497e077b1aab32917656570396000b075f9c182ffeb34e905bf91</span></span> <span class="giallo-l"><span>00624,</span><span class="z-keyword">0x1d72d6273c3ce96a26a5442357d4bd58b84dad51a2eb39f25ec02929e55290dc</span></span> <span class="giallo-l"><span>00625,</span><span class="z-keyword">0xf7ca7cb8ad47a85c6dad965e8c89bf7b33af62fc5dbfae0f5e141ae4ae1c280c</span></span> <span class="giallo-l"><span>00626,</span><span class="z-keyword">0x4f92dd261b9f5a9ed03735dc46722963d949ad3038f66ce380e4a1aaec9997ce</span></span> <span class="giallo-l"><span>00627,</span><span class="z-keyword">0x06e70723c3b912cfe421cb2126e812684742e304f2b8f6d6eb57b1fa959b19e7</span></span> <span class="giallo-l"><span>00628,</span><span class="z-keyword">0x313cbe432878645b4d887d961d6ff1dcd3c75b508b9263c05ed385754b7c7709</span></span> <span class="giallo-l"><span>00629,</span><span class="z-keyword">0xe939c15140cdf455b99492b6259ecf0c93ff858719948940f54dcc0d202988bd</span></span> <span class="giallo-l"><span>00630,</span><span class="z-keyword">0x1fbd3e9af1082f0e99094876294f6a857d8162f32c1f583eba1618acd2099a17</span></span> <span class="giallo-l"><span>00631,</span><span class="z-keyword">0x333c0583cffee0f355a1e3ccb6aa6aa16c80ebdc789e698c5f0f17521fc75035</span></span> <span class="giallo-l"><span>00632,</span><span class="z-keyword">0xbd6027f363c5a6efaf7d6f483653d256c6038a628064927411e970280a7ada9e</span></span> <span class="giallo-l"><span>00633,</span><span class="z-keyword">0x2fc5d74d149d6b265a5f6ef7b220738da67423b7aa176bd97d8b1c0df694ea47</span></span> <span class="giallo-l"><span>00634,</span><span class="z-keyword">0x5b3c9d594d6329d06de454698372063fe7c17da6f5dedb0ed68d7220e51af8d0</span></span> <span class="giallo-l"><span>00635,</span><span class="z-keyword">0x95e4dedec09d095e65d74638d433817b736659254cfbb46483ff449a9a1414b6</span></span> <span class="giallo-l"><span>00636,</span><span class="z-keyword">0xf8124b1e4bc3e7715dcff4eac8fdfd594f035a5c37ed7e041c85928cb0f32a93</span></span> <span class="giallo-l"><span>00637,</span><span class="z-keyword">0x12daf758eb702d488f8ae9c61e89b165f4b1e4090dba46713796dd49866585dc</span></span> <span class="giallo-l"><span>00638,</span><span class="z-keyword">0x75957ec2b9f6cd5f4e74a8f9c7f87432ba90888af7eebd1cb621b4d8b002d113</span></span> <span class="giallo-l"><span>00639,</span><span class="z-keyword">0x7c4f218a868ac866144c6d3d76ce9418c7674546ed3dc36e8ef313dd58913d6a</span></span> <span class="giallo-l"><span>00640,</span><span class="z-keyword">0x3cdc61329614d0f9f495f56c7be93a89783786ec23004628348b62819a5db04c</span></span> <span class="giallo-l"><span>00641,</span><span class="z-keyword">0x471f9e808ae0a317cce604dd035331ef6409ba0c3b0b0bf36ed93946fcd0fe83</span></span> <span class="giallo-l"><span>00642,</span><span class="z-keyword">0x551764bd61137d2595500f29b441cf8588f4ed1f7e1023182ee72656ad70bae8</span></span> <span class="giallo-l"><span>00643,</span><span class="z-keyword">0x368d4f6f887c76cd7416b91139d0613952a137d983d7ade47602ea026edf5e04</span></span> <span class="giallo-l"><span>00644,</span><span class="z-keyword">0x81a7c3da06068fc345f11d7bc65b30d249f3bae56c476ef2c16a2d7a04e19112</span></span> <span class="giallo-l"><span>00645,</span><span class="z-keyword">0x2582b644739c464536ed4befe7d7bcf77bba70a416a74869934701eba0300a4e</span></span> <span class="giallo-l"><span>00646,</span><span class="z-keyword">0x7fd3548a22eafe728cfee056c100c5ec3622ee0280a79be7b7fb5cd1af2499b5</span></span> <span class="giallo-l"><span>00647,</span><span class="z-keyword">0x07e93c81557232d569357182dc05bbbcf7ff3f5b3786163cfb5df756e601d9d9</span></span> <span class="giallo-l"><span>00648,</span><span class="z-keyword">0x01a981a6bc6a5c30e9e24acbd2610094f612785ee1da40150ef6adf7759418a3</span></span> <span class="giallo-l"><span>00649,</span><span class="z-keyword">0x05bf160d3f11c285bd8d159e9a675bf04b17615fcadb4390e8f582246d52a263</span></span> <span class="giallo-l"><span>00650,</span><span class="z-keyword">0x119bef0c67ab4480ee8952c208c75959a4a98db6b646410d4276c650e107354f</span></span> <span class="giallo-l"><span>00651,</span><span class="z-keyword">0x4d3f0b82017c63839fe95826858a18ac4ae5376c004d04a23aba4d6d7a32b96f</span></span> <span class="giallo-l"><span>00652,</span><span class="z-keyword">0x730975c7bcbee5e2bc9299e12abb46dfc7f5b94416c94b6b103ae22d4a189049</span></span> <span class="giallo-l"><span>00653,</span><span class="z-keyword">0x2eb89f05e222461e22e437518949767e25e432862909e07df410c6ca237cb567</span></span> <span class="giallo-l"><span>00654,</span><span class="z-keyword">0x51b0bde3cc9eaf4d7ababa77e2e06e65b262864cd9894a8f9edf4b3483ee1d28</span></span> <span class="giallo-l"><span>00655,</span><span class="z-keyword">0x06381406a98b16d278488bbba3f91c0ec10c1ace930d75833f15ba9c73500a2d</span></span> <span class="giallo-l"><span>00656,</span><span class="z-keyword">0x0c07242390289d92c0deb8bf23da435720a753a07822a0bde0bfddc258c2ae90</span></span> <span class="giallo-l"><span>00657,</span><span class="z-keyword">0x4b0dfe65c189822fa4cd1648d3fbb1ecf75b8b5538383cde1b3f899caf1d1bb1</span></span> <span class="giallo-l"><span>00658,</span><span class="z-keyword">0xeafc91b6b61da1feb8af3c78fc9b7d01239962fdbfbd40c920a55f620ff74351</span></span> <span class="giallo-l"><span>00659,</span><span class="z-keyword">0x49e7399f27b5e26165b5603002b529ab4a974346259ba9aac2128387c0b6516a</span></span> <span class="giallo-l"><span>00660,</span><span class="z-keyword">0x376add4f0e8ed9e97c43c5e439d90b5742c913908bbd5ff6da3ea59ac381da92</span></span> <span class="giallo-l"><span>00661,</span><span class="z-keyword">0xa8a70e6e484c3180d23874a903ba032a1377e3bd53fa9818d7c11dae93883fa5</span></span> <span class="giallo-l"><span>00662,</span><span class="z-keyword">0xdffecb3c77a67ecd4d71ef3d16a47cb27dfeeda34126567620ad4bc0e6ff5961</span></span> <span class="giallo-l"><span>00663,</span><span class="z-keyword">0x6c4ef261baa1dc41e4e3f559e686ce4e340cb14cebebc5ec6cd2d8d11b4bb550</span></span> <span class="giallo-l"><span>00664,</span><span class="z-keyword">0x3eb2993dbbfdd451bf6ee204a1aa8363bccdf05442fb2d37283d0e9743c9548f</span></span> <span class="giallo-l"><span>00665,</span><span class="z-keyword">0x8f4067864f02001aa64082821d09b6fa8bd4f08eb10a97f2b3d725988dec18ef</span></span> <span class="giallo-l"><span>00666,</span><span class="z-keyword">0x4ed7ee7ff95fba3f7e26f8ba3dedd661c29cc693e39ac180fb1cf51cf06be01e</span></span> <span class="giallo-l"><span>00667,</span><span class="z-keyword">0xa6b898d4e160d6568325e5178aad53d3b1928eb26c0a6983e2e564787cb59169</span></span> <span class="giallo-l"><span>00668,</span><span class="z-keyword">0xc4a9d166c6bf0bf68df60ac3841b9dd7643261a1f680ebc4a3eb1e78a2bae263</span></span> <span class="giallo-l"><span>00669,</span><span class="z-keyword">0xd8d978428ae77afca8ea889e5e315b4840b2c03a2f9cf046e6809ab3cc2bb50b</span></span> <span class="giallo-l"><span>00670,</span><span class="z-keyword">0xbe3afc5ce9e69625defb1cef154c5ed21bd685b3b444f0bf18eb578438483e84</span></span> <span class="giallo-l"><span>00671,</span><span class="z-keyword">0xbf138a264139a579902a52806444d5b72e5a7d700b441fb3e48007d1d96badb4</span></span> <span class="giallo-l"><span>00672,</span><span class="z-keyword">0xbf106779ccffef7ba05420f4d363f699759225b5c63c0570c644684ed02a1a82</span></span> <span class="giallo-l"><span>00673,</span><span class="z-keyword">0xdefe7756ebd4bbb46d00e6a9ec83e0b448ad30cd07e8140e8d198a762e17bc9d</span></span> <span class="giallo-l"><span>00674,</span><span class="z-keyword">0xc6dc6388bc26f755dbc33c06ede33976846dc45cf406aaacc275f36bafbeb8a6</span></span> <span class="giallo-l"><span>00675,</span><span class="z-keyword">0x1e729aa1a7eba72fa1b394e8e02ac0b11ff5b52c45ade0e1dbe6cf94133d3d52</span></span> <span class="giallo-l"><span>00676,</span><span class="z-keyword">0xa5855d981860b945790cd878ab958c0c8f9d634e19eed4ffb6f2b6fb0bdac0b4</span></span> <span class="giallo-l"><span>00677,</span><span class="z-keyword">0xf3e17cb0fdfb1b6843f71e8371f3ec7943f3fe8c336f50eec94be6b3d7cc74c0</span></span> <span class="giallo-l"><span>00678,</span><span class="z-keyword">0x42e737249c54ec77b3e92f6e2ad6cefa998f950a04b6e86467096abe91018de1</span></span> <span class="giallo-l"><span>00679,</span><span class="z-keyword">0xf0fc97a52d48a5cd63c3a44569661bf5d52b37631aa5de0f9c43bf9fe2ac0e54</span></span> <span class="giallo-l"><span>00680,</span><span class="z-keyword">0xa6045d364b325ce7f818cda8750a79196c59419e2be015438e097fc8b52dfa0d</span></span> <span class="giallo-l"><span>00681,</span><span class="z-keyword">0x247222f0af90a8ec543ba8c04c847b648fce30a323ffb4cec28f0c1571f878a4</span></span> <span class="giallo-l"><span>00682,</span><span class="z-keyword">0xa6b3aedbef826280e9fb8ac59718ab16e5369cd11be51532675fc454d89d533a</span></span> <span class="giallo-l"><span>00683,</span><span class="z-keyword">0x19fcceed6516cae75fdec68f8d34a12c90b64c4d140c4576e724251e6ee6ebed</span></span> <span class="giallo-l"><span>00684,</span><span class="z-keyword">0x388b0bdc52a25713bd30615e094a873e633092c199bbe247c96c32a61fc12263</span></span> <span class="giallo-l"><span>00685,</span><span class="z-keyword">0xa2bcc3ddd6f1ec7a0e90f3faf0eb8418a297538a351f16523bf767951cdf179b</span></span> <span class="giallo-l"><span>00686,</span><span class="z-keyword">0xdf515337eccd495de4a93cfd27e7cd44bfdaaf7cad84ab831255b232d9c3dbad</span></span> <span class="giallo-l"><span>00687,</span><span class="z-keyword">0x8977442562e00f0c2d71e621848a4ed4b54dc37900075e31d4e945cc1ff9cd5a</span></span> <span class="giallo-l"><span>00688,</span><span class="z-keyword">0xa979df6fe13d81c5777eae13b0416a370a2c631c41446e51ffb060a8a6a71452</span></span> <span class="giallo-l"><span>00689,</span><span class="z-keyword">0x33e5fa30c4826bbd3448bbb05dd7273639f122e9c9cacaad987e1def1daa7c80</span></span> <span class="giallo-l"><span>00690,</span><span class="z-keyword">0x7c95061fb3cac78558039c1cebd4c7e70831f6f5a7906b9faa1a7554cbb43e28</span></span> <span class="giallo-l"><span>00691,</span><span class="z-keyword">0x062b4177522f6cbaebe9e708a4717d0f5218b21041f84b7eaa13293477135e10</span></span> <span class="giallo-l"><span>00692,</span><span class="z-keyword">0x945645ca1e3e1c23eade81c2c8e0a7cd428d3dc875b15fc9bbdbde163bc742a7</span></span> <span class="giallo-l"><span>00693,</span><span class="z-keyword">0x8c6754fdf4780c58461bb089f7d5cfce43a0c0b527b7044e27eda9852f34a7a0</span></span> <span class="giallo-l"><span>00694,</span><span class="z-keyword">0x222e02bcbbe7f319c293f0c4da042bf7cd9c3bf8c953f4319a14191e4f005966</span></span> <span class="giallo-l"><span>00695,</span><span class="z-keyword">0xcebc5a0e235e81bd4488436792b62e736be4cdbcc60f200326cc91b436808baa</span></span> <span class="giallo-l"><span>00696,</span><span class="z-keyword">0xf73fca1b251055ccf2966f306db54c0201bea107de603c1aac0f7b2914386dd8</span></span> <span class="giallo-l"><span>00697,</span><span class="z-keyword">0xcc3b18315c91ff81f2f9c76c74c0aec6f4bb76fc6cee9512ee81026de4f687aa</span></span> <span class="giallo-l"><span>00698,</span><span class="z-keyword">0x062461dfeaa7dc2a5a6e7149f2ba928b78aef2b9958605a31185bcd7f004522c</span></span> <span class="giallo-l"><span>00699,</span><span class="z-keyword">0x7dcae2e8fbc54bedb91edeb0c02141574a70e0412b2045e311330119491c2129</span></span> <span class="giallo-l"><span>00700,</span><span class="z-keyword">0x64f029a915ad77e37247bb296e4e3eca49dac180d5b91d5b9e1366cb5d02df74</span></span> <span class="giallo-l"><span>00701,</span><span class="z-keyword">0xc0ae757bd5b3d4a2a87884cfe45bd3ee2f11239b51f9dd5cfc05401c5c66bb8d</span></span> <span class="giallo-l"><span>00702,</span><span class="z-keyword">0xabe351f7c2bbfcbe08dc7bcdb0eeb08079046bb9f2c94a80ed7bf8e51bddeff4</span></span> <span class="giallo-l"><span>00703,</span><span class="z-keyword">0xddee734cacc8d4ef083d67efa4df54519a60e0101c0a43842eaf93af88ab3377</span></span> <span class="giallo-l"><span>00704,</span><span class="z-keyword">0x2ea464e978346b97200486d8994e77706f83622452eb3850a745b215b6351eab</span></span> <span class="giallo-l"><span>00705,</span><span class="z-keyword">0x9f0bc9d6161d69f28e3f342553c62fe53e281dee8c05002bd562b964c7abc1a6</span></span> <span class="giallo-l"><span>00706,</span><span class="z-keyword">0x58568eed1ab113f2d3305f595ff6306f9bd4a20dbc168388afce22679b648ccd</span></span> <span class="giallo-l"><span>00707,</span><span class="z-keyword">0x6aca18990b84a8ef483d70e93ef95a3fefd969b44162724e8d205b2e44a60e09</span></span> <span class="giallo-l"><span>00708,</span><span class="z-keyword">0x2478502ca3b5bd3787da2b2702e4ed470abc698594043bd7eefc6b0d200cfae9</span></span> <span class="giallo-l"><span>00709,</span><span class="z-keyword">0x07426af091dc9d0b455e6c0a6de13abd24f3eb3a8e7763538159bcd1bf141645</span></span> <span class="giallo-l"><span>00710,</span><span class="z-keyword">0xa70b753c132d447457a4a4c500a03afa9fc5a506cd08966303adf5439a183fd2</span></span> <span class="giallo-l"><span>00711,</span><span class="z-keyword">0x1146e2f9e5e7d485c0b97ed15f1f6a5d3ce2b829460d37cdb9ac49d7f6b2ee08</span></span> <span class="giallo-l"><span>00712,</span><span class="z-keyword">0x560a81199fb507f115ab5c06337c8c4dc0fe38d991a0057b88816849e2899ad0</span></span> <span class="giallo-l"><span>00713,</span><span class="z-keyword">0x54d9396ec97021ae660990c80c6a06075f9e7e2cb7520f242b8c4019f29fe4c3</span></span> <span class="giallo-l"><span>00714,</span><span class="z-keyword">0x8979cc56b72d0fa09ab853f0c94da9223e371e4e3a76d085a8d5e0ccfa812c9f</span></span> <span class="giallo-l"><span>00715,</span><span class="z-keyword">0x1a583ca6146142cd35125be61ebecf376f08db4cb907d613d8877b383a961923</span></span> <span class="giallo-l"><span>00716,</span><span class="z-keyword">0x4850905c37251bdd1612b0948a06170a335831bd753be7c62d0d50a8f10bfb34</span></span> <span class="giallo-l"><span>00717,</span><span class="z-keyword">0xf510edaada3d10661180eb5af717d93b8c5e39971c0c7b82245958bdc47d4359</span></span> <span class="giallo-l"><span>00718,</span><span class="z-keyword">0x511c0a35f990cf41f851e42863956b7fa20eb133503b7f5e8b7dcfd42ff57d8e</span></span> <span class="giallo-l"><span>00719,</span><span class="z-keyword">0x14409e14f0ae0f18d080c8f6bf0ae89e4817e214ac3b2c3e7625266375a502a1</span></span> <span class="giallo-l"><span>00720,</span><span class="z-keyword">0xcf91e8a7472e27a4172246ac5c5a761575f2f25650a2284ea607f8b607ece639</span></span> <span class="giallo-l"><span>00721,</span><span class="z-keyword">0xaa8695870b38dbd336c12ca05e61ae474fc3540e3780da64432d6cae23de1ed5</span></span> <span class="giallo-l"><span>00722,</span><span class="z-keyword">0x96e85fdbaab8e3e96a18a455b6f7c52dfc256146b15b4a17cd5349a1e05dd900</span></span> <span class="giallo-l"><span>00723,</span><span class="z-keyword">0x78bf01d3000e5bf37d29358748ec99c6e4eb1d6e3203dcb914b0b7009bb475b7</span></span> <span class="giallo-l"><span>00724,</span><span class="z-keyword">0xd7c27830b175b06d64f2c9e7f6533d396a6527aa8078030d35e2997805031dfe</span></span> <span class="giallo-l"><span>00725,</span><span class="z-keyword">0x8859c97fca028d013b18ac01644d4070df18cb369a380207c646808ee242d99e</span></span> <span class="giallo-l"><span>00726,</span><span class="z-keyword">0xa705da9bf450e3f38cbc0916a3430caf7b7c2e5b84b0eed30865c21417a787e9</span></span> <span class="giallo-l"><span>00727,</span><span class="z-keyword">0x58d8312647f7b4f93bb4e166ebefe27b4031924f7550d9ba1d2ab7fa58fbd547</span></span> <span class="giallo-l"><span>00728,</span><span class="z-keyword">0x2daec9311d82d342bf0a5f197beda1aa5bec47277d79baccc91d033c2151d583</span></span> <span class="giallo-l"><span>00729,</span><span class="z-keyword">0xfe141ac786b2e586770563dd5812bab7673e4939e29473e6c4a1a75d5217bf13</span></span> <span class="giallo-l"><span>00730,</span><span class="z-keyword">0x4ab51ad5fce5b07c3935e88c8a21e911e30fec10a5066b79e0d01df2737bd613</span></span> <span class="giallo-l"><span>00731,</span><span class="z-keyword">0x11b0f603bc13ce8a712ca6ef749c8c923097c455c6b86386f166b1e47daebfd9</span></span> <span class="giallo-l"><span>00732,</span><span class="z-keyword">0x3e648126f5543d814037eb55ff7d4079433fb586ec6b3a2bd0ed968f8fed9603</span></span> <span class="giallo-l"><span>00733,</span><span class="z-keyword">0x87195980bf623a55f7bb30e396648aecd839768429e6dc5ecd3417dc44c6521d</span></span> <span class="giallo-l"><span>00734,</span><span class="z-keyword">0x1a924a1baf8970146ef21e1ae77cbececbadcb975f4f950314313381d50fa823</span></span> <span class="giallo-l"><span>00735,</span><span class="z-keyword">0x34d9d6a7333d35e1f16458eb9bcac884e81f93dc421c3ad47b7a46ea6f929c7a</span></span> <span class="giallo-l"><span>00736,</span><span class="z-keyword">0x1569f88b5514b6f98302427c8ab4b4b6c020b517b290b2c7b1e8b6b9ee2b74f3</span></span> <span class="giallo-l"><span>00737,</span><span class="z-keyword">0x288181ee87c7c1f4c8052ae1692959d57f9f4b123014deebfeeb6df20dfaa424</span></span> <span class="giallo-l"><span>00738,</span><span class="z-keyword">0x28dbb0e5bd25ae20d92b68183f093bf002cb40e2d0e7b9597ea6e58478db184b</span></span> <span class="giallo-l"><span>00739,</span><span class="z-keyword">0x4bd79b88bf29f2048cff7bb28f048b67312009bb49d5c33e0a8df28fb26de7b7</span></span> <span class="giallo-l"><span>00740,</span><span class="z-keyword">0xc84ee78099163d07ff47d4e2f864338e0fcbdaa1298b6fa71352e6896655b918</span></span> <span class="giallo-l"><span>00741,</span><span class="z-keyword">0x2aacc622a545af97bb40c4d5decffd5142427c482ca5bb8ef7f29951e1807e4d</span></span> <span class="giallo-l"><span>00742,</span><span class="z-keyword">0x165aa7d2b8608774366225bc7252056104da64abd35ddbd1db832ae375bb6031</span></span> <span class="giallo-l"><span>00743,</span><span class="z-keyword">0x4505bedc2d45231f48b90817f82a686da0f8b362a79bb0d774cb396288491461</span></span> <span class="giallo-l"><span>00744,</span><span class="z-keyword">0x08785ac95582347c80d4321d003a4c31d343effc0cc8e8d4a32f8370996123c1</span></span> <span class="giallo-l"><span>00745,</span><span class="z-keyword">0x6ea3cb82c7125522aa5fe08d65c4edcd10e1823d312f13288c5ae9b69b2d2935</span></span> <span class="giallo-l"><span>00746,</span><span class="z-keyword">0x3ec58c854981ed2f44dd8516cf166b12232e5e32d2fbeddf070fa45a1d8cc638</span></span> <span class="giallo-l"><span>00747,</span><span class="z-keyword">0xaaaebe5b4f04d2085247c7c9855d1add2e8f0d7e545c532cde20b6145ea711fd</span></span> <span class="giallo-l"><span>00748,</span><span class="z-keyword">0x5ab3b22293636bc4bb517aac1a3c22fd297cdf1c8da5cab2353c7b657208f1d0</span></span> <span class="giallo-l"><span>00749,</span><span class="z-keyword">0x27aebfb9c574b6b4a90161369be8e3361b887534f6031f35654424c9d50e3efc</span></span> <span class="giallo-l"><span>00750,</span><span class="z-keyword">0xcc08abf8cae1d37837d395bfd9094e01b70dd66c8cfc9800fe8fecb4b2b09599</span></span> <span class="giallo-l"><span>00751,</span><span class="z-keyword">0x032ebacd972a00b4cd4fc81ee4e8499468ac379eabf1de2762e98aaa957e4cca</span></span> <span class="giallo-l"><span>00752,</span><span class="z-keyword">0xf09c12bf003999d4e98769faca1a7c12352abd26bfb290a048b846c669bbfc89</span></span> <span class="giallo-l"><span>00753,</span><span class="z-keyword">0x876733dd576846ad12f5967b4c131194b19013232b270faa88f816795c403e6b</span></span> <span class="giallo-l"><span>00754,</span><span class="z-keyword">0xf50f5eb285818911c3fc43b60174f25a9e5b9dcac9a5f3e6914d8b0af439234a</span></span> <span class="giallo-l"><span>00755,</span><span class="z-keyword">0x4d52bb12e70194eb981ae85c08a02d16b7e899262dc34e7b028eda0a123421a2</span></span> <span class="giallo-l"><span>00756,</span><span class="z-keyword">0x0af4e42bc526ccc68e29d057456f30076323afdb70a6aaecef47cb316a689c88</span></span> <span class="giallo-l"><span>00757,</span><span class="z-keyword">0xd1988f793da01c8d63bbd508befde9fe8ccc1f2f5974d9bdf0b2d8afa0b9f997</span></span> <span class="giallo-l"><span>00758,</span><span class="z-keyword">0xc66fcb070ebb36a3ef93360bb74079d15f8c4cad6fada6a408dc33f982308279</span></span> <span class="giallo-l"><span>00759,</span><span class="z-keyword">0xa6242a1ccc07f0b240026340ccc6d91d99396732364858d8dab438965f90545d</span></span> <span class="giallo-l"><span>00760,</span><span class="z-keyword">0x824af748696096e08232cea82a07f15a590908d73e4b72da6733ed3dce3ce648</span></span> <span class="giallo-l"><span>00761,</span><span class="z-keyword">0x76b41584de30eb80fd613f82c44d7fa70aff42a1760221e3852d8865923ce75f</span></span> <span class="giallo-l"><span>00762,</span><span class="z-keyword">0xb3ed5869910b3b75a102644af13fb642991e19aa885848ea9099f31091cffe0e</span></span> <span class="giallo-l"><span>00763,</span><span class="z-keyword">0x713aaaf6faa21e1ace76e89e35cb9cadc04e01a6808e264dc08075a0a4074e09</span></span> <span class="giallo-l"><span>00764,</span><span class="z-keyword">0x3a6de7d91da79fe7ceb3f9ab4634e88efb40832ef2e776624ffde6b3d37b6443</span></span> <span class="giallo-l"><span>00765,</span><span class="z-keyword">0x18b5d60216a44d195c8c533a95a82c1cf17184393db431accc269b8f759f6341</span></span> <span class="giallo-l"><span>00766,</span><span class="z-keyword">0x6b5ade6c06f8ba9ef42f64369a90145db95ee3f84c7ef2f4cc0bbd088d400287</span></span> <span class="giallo-l"><span>00767,</span><span class="z-keyword">0xa008476355318634f1f429e5921b41860e1f2b84a56f25bfc4d1bb3ad99e339d</span></span> <span class="giallo-l"><span>00768,</span><span class="z-keyword">0x8dc563b6cdbec477ab54634e7dbe0a986ea6f745e81d1fbe2d9ee2036222f50b</span></span> <span class="giallo-l"><span>00769,</span><span class="z-keyword">0xefd6696f77b898d126c7df1d9f481853086479c17279d5d138348e5202bce86d</span></span> <span class="giallo-l"><span>00770,</span><span class="z-keyword">0xd9db47f4de8d5d1c4700ea620d918e8ad0877e06d40183790fe55bf6a334748a</span></span> <span class="giallo-l"><span>00771,</span><span class="z-keyword">0x2aa70a70c541cd444fd2caf88968d737fa7df568af3e13526cb9efd7d0c340fb</span></span> <span class="giallo-l"><span>00772,</span><span class="z-keyword">0x44dcb9abd03e34d90516dfcf01de57529d8e5efe899d526fb222840547e98dd8</span></span> <span class="giallo-l"><span>00773,</span><span class="z-keyword">0xe4dcc8e85df47ef9e3e5ca5d5fa8bf8597cde9c9234f6ee5020260e69e911b2e</span></span> <span class="giallo-l"><span>00774,</span><span class="z-keyword">0x63f82331a80309f20bd3c9500671446c81923ce5023224f9502343c7db25d83b</span></span> <span class="giallo-l"><span>00775,</span><span class="z-keyword">0xf24f282ea23a59a5c6451e66987eca682686d8b5df910676b2fcac68e675a3da</span></span> <span class="giallo-l"><span>00776,</span><span class="z-keyword">0x382525f177efd6e19eb9949fdf8f31802f86c7754d43898dafc36eacdcf72db8</span></span> <span class="giallo-l"><span>00777,</span><span class="z-keyword">0x2d3a5e7ae6a0aa3498ff29bd9c01bb50be16608071cdc311690b08d54b81ceb4</span></span> <span class="giallo-l"><span>00778,</span><span class="z-keyword">0x9a24e96613beb77c7482edb95e3bd149f3a95df7fde1e01c23eff75a71f73dd7</span></span> <span class="giallo-l"><span>00779,</span><span class="z-keyword">0x0be7242c1c73f21c6912fe398bf625f142d4b00f260cd0169b82162c7b215da0</span></span> <span class="giallo-l"><span>00780,</span><span class="z-keyword">0x0b8c7a94e807b13c8053ee0c97d5f38f263e31d9fa703d9b11de00c7d4c7945d</span></span> <span class="giallo-l"><span>00781,</span><span class="z-keyword">0x6e9ae0809cf9e38136a64b629b4b58f37bcbf54b6744ef3121403abb14b1582b</span></span> <span class="giallo-l"><span>00782,</span><span class="z-keyword">0xe888e6c289f0734c57b9c61c1b6798e5d94139252173305a7764c8c4cc9da157</span></span> <span class="giallo-l"><span>00783,</span><span class="z-keyword">0x03027295eb991e1dd03d652ebc3ac786ee4c263504a78fe31398341844f235f4</span></span> <span class="giallo-l"><span>00784,</span><span class="z-keyword">0xb6efb516952e014d0e2197320e521f15d58f6eb8c88bae72fed90c570ec3bf85</span></span> <span class="giallo-l"><span>00785,</span><span class="z-keyword">0x79728b75e2cbcd3ec3a144ad474dd75eac9e1dd898fb3c97023c4edfe7d91890</span></span> <span class="giallo-l"><span>00786,</span><span class="z-keyword">0x0586eef4843820a247d8f8201c6b77e828096bc02c4c5bc3d2c3b83bf42ce549</span></span> <span class="giallo-l"><span>00787,</span><span class="z-keyword">0xa0d4c8c20e3a37f678959b563859677050107b0e63d043ca1930dd48a93c0311</span></span> <span class="giallo-l"><span>00788,</span><span class="z-keyword">0xa55feb48d4922a3189983989333d70c7fc6b18656446bce243eaf77fd21c54bb</span></span> <span class="giallo-l"><span>00789,</span><span class="z-keyword">0x9b95d3aa1408771b1e1e743db3216bf9e512a1fdaf6035f7a9f40e3019e9134c</span></span> <span class="giallo-l"><span>00790,</span><span class="z-keyword">0x4a62280eabc47623a8015bbbdb99a64521c554491b9ca4baee28def4c857cfa4</span></span> <span class="giallo-l"><span>00791,</span><span class="z-keyword">0x064776dafa35a56678a5574157b74c8e5f1433d823f8addfacd972e0d2dfa90b</span></span> <span class="giallo-l"><span>00792,</span><span class="z-keyword">0xe9a295429a1b3fe4ae05e4444fa3e7939ee234416505e5bb12533e45204ccce8</span></span> <span class="giallo-l"><span>00793,</span><span class="z-keyword">0x93ac12baf1d3519d2d6db741537a098b5b97e00c7044e96eb2c49900a7d3c3f4</span></span> <span class="giallo-l"><span>00794,</span><span class="z-keyword">0xb199a3097a3b71bb74286673315795e98805a6951174ec6957b80bcadddffe1b</span></span> <span class="giallo-l"><span>00795,</span><span class="z-keyword">0x284915ec1b0af683caaf90546c773bdb1e950f8923f9468192e160aa757a4869</span></span> <span class="giallo-l"><span>00796,</span><span class="z-keyword">0x80b8a59801157a40d10e17c3915a16f78eca8b03998466f59ce4c4f910ac0760</span></span> <span class="giallo-l"><span>00797,</span><span class="z-keyword">0x40e902aaa84d1fa5c8cfc7ec95846be5b541c785a9514f6886257431d7c7d5e7</span></span> <span class="giallo-l"><span>00798,</span><span class="z-keyword">0x25bb39c7596cf80eed1af44ca924abd9f738b386cc3604beb0cc0e139b570a5c</span></span> <span class="giallo-l"><span>00799,</span><span class="z-keyword">0x565a1bf8ee5e84e7e9ff397ee36a656ffa670321bacd7533e77eaf91ea104561</span></span> <span class="giallo-l"><span>00800,</span><span class="z-keyword">0x6723d6d967dab127477429efceb7f975d2cec28aad8ddb603fef54cc69fdc6b0</span></span> <span class="giallo-l"><span>00801,</span><span class="z-keyword">0x2c9057ba31e7f3ddad8a3324a066efb9353cbdce8e399ba3061531737b118713</span></span> <span class="giallo-l"><span>00802,</span><span class="z-keyword">0x75e347ad895b4b6dadad02d048f988ec7298298756d55d924a6605e3ce2bc9e6</span></span> <span class="giallo-l"><span>00803,</span><span class="z-keyword">0xafb8c20ffd497fd6ed9ce26ae25f7a83c66e30bfbae612cf83dd83972a75d7f3</span></span> <span class="giallo-l"><span>00804,</span><span class="z-keyword">0x472b0432e2d130803fee6986e35c0decf8989cb0d0645cce4848848a30cc990d</span></span> <span class="giallo-l"><span>00805,</span><span class="z-keyword">0xa00ad7738c5a78e98095ad2803f5f02736ddf5fc471940d4d01642317be7bafd</span></span> <span class="giallo-l"><span>00806,</span><span class="z-keyword">0x4fabbfd520862fb8c2a3cef755e30fab50f8e235460924f43eb239e3276738da</span></span> <span class="giallo-l"><span>00807,</span><span class="z-keyword">0xebadaa845247da44fad909d4bad16b43a5e63c6f48bc3eaffe2b98b27f9e1c3d</span></span> <span class="giallo-l"><span>00808,</span><span class="z-keyword">0x71a5a039aa5425f801492260210074426cf5deb420cb2ddf9defb3601564f0d5</span></span> <span class="giallo-l"><span>00809,</span><span class="z-keyword">0x2a78afe865f39dadda88e3d3d493b6be19af8374a62f0b48c3cc8b41e28227aa</span></span> <span class="giallo-l"><span>00810,</span><span class="z-keyword">0xddc911377e4dd2291f709e0243a6cc7331a49aa27aab1ef211470f4662c8e460</span></span> <span class="giallo-l"><span>00811,</span><span class="z-keyword">0x47305f69611d5c09e9f302c34c1a491b8166f950f14fa56ed0885c11257f0224</span></span> <span class="giallo-l"><span>00812,</span><span class="z-keyword">0x6492e81274651a77c064ac8a6cec00c509e58de9a951070770cab002658d662a</span></span> <span class="giallo-l"><span>00813,</span><span class="z-keyword">0x9ccf4c433a7e66762068756cbde59d2c603e1dc1d64cd0e61bd39bd636ddd877</span></span> <span class="giallo-l"><span>00814,</span><span class="z-keyword">0x02f878d63294625f5b8e01973359df0621504feeb548141ee1fabd1747bb2f4e</span></span> <span class="giallo-l"><span>00815,</span><span class="z-keyword">0xe97a4d00ec948995c670a9c30441ca9f510c6369f00ef2fb38624f14d8531eb8</span></span> <span class="giallo-l"><span>00816,</span><span class="z-keyword">0x13c60a90e71fbfa321264b1dfbcdf76d0b15f3adbed05f31b02848e4fddad79c</span></span> <span class="giallo-l"><span>00817,</span><span class="z-keyword">0x6f8e5552d9e7982de12d6cca3368f02671fa6b071f0618876d4a1e9a4d79a3ea</span></span> <span class="giallo-l"><span>00818,</span><span class="z-keyword">0x8143cae1101045cfd98b8202617280228a5b68c0d4f37180b79327d4fd555a61</span></span> <span class="giallo-l"><span>00819,</span><span class="z-keyword">0x3894e28cbfa568d39fa7db232e4954e9c14f36eccbcc4c1d35cb8562285fbcf2</span></span> <span class="giallo-l"><span>00820,</span><span class="z-keyword">0x97b69aecc1068e3d89e32195d6b0058b13a2b762cdfbecee7d54256e67bc4b81</span></span> <span class="giallo-l"><span>00821,</span><span class="z-keyword">0x22732c1861dceac8803885adf29e9c9b7758ee5c2de3660d175aec67e0deb2d8</span></span> <span class="giallo-l"><span>00822,</span><span class="z-keyword">0x6977fa0d3194c37772fb68df9929cc9974fd9441cd4881adf20e17408465d544</span></span> <span class="giallo-l"><span>00823,</span><span class="z-keyword">0x0d164934226bdbae6b1a9c2e284a02bfe3e7552ac901576e33aee614f8f4d9e1</span></span> <span class="giallo-l"><span>00824,</span><span class="z-keyword">0x0de9eb6ca895573dc439ff773e617cec54c9a3e83c8412ae6bed73594f51845c</span></span> <span class="giallo-l"><span>00825,</span><span class="z-keyword">0x14eaae6399e76bb8c66fbf9cf4333701bfeda482cc347590402ba802332e5610</span></span> <span class="giallo-l"><span>00826,</span><span class="z-keyword">0xe0848f10dad16982805b6bc7f6151605db509bb228fc49dc647bb472c0fdd83d</span></span> <span class="giallo-l"><span>00827,</span><span class="z-keyword">0x6846201d042855e80cd3e2a1b2f5f0a6360d499cd803900873c1900264e45448</span></span> <span class="giallo-l"><span>00828,</span><span class="z-keyword">0xe89c0e11010967dc5ceb97b9ef40a45f36ecd9390c82b58d95592deb04b6e746</span></span> <span class="giallo-l"><span>00829,</span><span class="z-keyword">0x3096af7600019e93e14000a119faa50fc3c60c4fedfab2b65ef7c5e76c40dd2c</span></span> <span class="giallo-l"><span>00830,</span><span class="z-keyword">0x55e8b4c2d3dc809690f3276cd43ddb11b907c7a975de41041a1cf47e6fd535b7</span></span> <span class="giallo-l"><span>00831,</span><span class="z-keyword">0xc501837ee2c215da498b734153628de1acc5d433179078696ce82a4f2fda42c1</span></span> <span class="giallo-l"><span>00832,</span><span class="z-keyword">0xf7000808e45b53416da880d5a8a6face40cb10a55fd1a9f4c07bc125da165ea6</span></span> <span class="giallo-l"><span>00833,</span><span class="z-keyword">0x5d73b97ad48b73368898a1e39b0f725c43ca3757b9224dacd2f8db81b90d6807</span></span> <span class="giallo-l"><span>00834,</span><span class="z-keyword">0xf240decca5d9b9a21a75948716f83b68499f5f260fba9e535320d7ad2b8f654f</span></span> <span class="giallo-l"><span>00835,</span><span class="z-keyword">0xfbd0a3686d9e771cbe2410e0eaaa2535d140a5b5628d2dc5b79afe2a54da0255</span></span> <span class="giallo-l"><span>00836,</span><span class="z-keyword">0xfbd2c4fe042a2c0c30942153fd2b2a148fd11275cda67d7e945ea50d8ce9588a</span></span> <span class="giallo-l"><span>00837,</span><span class="z-keyword">0x8bdc330460491a8d07586f41f6c980500b273533b9a98d0d0d180230a35abe43</span></span> <span class="giallo-l"><span>00838,</span><span class="z-keyword">0x2a2047ce16869ba58f7aa520202bc2c2345fac6bfca50e06194361165cedc4ad</span></span> <span class="giallo-l"><span>00839,</span><span class="z-keyword">0x84c88273e2546de530b060ff56c8c9fe3aef02cc968fbeac333fdc4de9c49cde</span></span> <span class="giallo-l"><span>00840,</span><span class="z-keyword">0xb96ae20a3f7c6cb7890d5f72037ba8a1a8be4e4f758be430f089ba62c9886887</span></span> <span class="giallo-l"><span>00841,</span><span class="z-keyword">0x5cfe6abdb5b075a8fc721d49e76d0c136de22d165ff61d27a7acf7050d84a31d</span></span> <span class="giallo-l"><span>00842,</span><span class="z-keyword">0xb7d8f3a61da1cf210b8d80336009634c26f97ec52375533406ac0f0f7e22f5fb</span></span> <span class="giallo-l"><span>00843,</span><span class="z-keyword">0xc14d7f51eb905c4e662965caae40a537cb7a85d85458a5508e91a2498e479fd4</span></span> <span class="giallo-l"><span>00844,</span><span class="z-keyword">0xc5eea731a2a18fbbc08066a06515c8f05d8838912d961c32b31ac31736d8e5df</span></span> <span class="giallo-l"><span>00845,</span><span class="z-keyword">0xaea57615f40fa35e4c73f273cee2b1f077838a18001e8ddb9e87d28286149014</span></span> <span class="giallo-l"><span>00846,</span><span class="z-keyword">0xbe228f4af7a96d9c1cbbd4e76864e68c332232ba5ce81de3e11c0d8b33bbf1ad</span></span> <span class="giallo-l"><span>00847,</span><span class="z-keyword">0x5721c5a99dfa32e02559d43450e95be7f59d245160fce626eb8e5c81c271be87</span></span> <span class="giallo-l"><span>00848,</span><span class="z-keyword">0x4f17a7ba2d98477f2d2b3ade28f2107d35516e8f953b636ac1f6014f4d1c2204</span></span> <span class="giallo-l"><span>00849,</span><span class="z-keyword">0x81731fd5dd5f8ba504c4c3bd1080eddb3e400e8655bfb1e93da5450177923ce8</span></span> <span class="giallo-l"><span>00850,</span><span class="z-keyword">0xc8596aa574934f8d7b7a0c938ce736d7da8c63dc40bda9719b1469d1ef93ba0d</span></span> <span class="giallo-l"><span>00851,</span><span class="z-keyword">0xd9d76d294b8224a90bd65300b2bb1c3c5e53441b3182c5b0d41011f626046a9f</span></span> <span class="giallo-l"><span>00852,</span><span class="z-keyword">0x3db9cab96ffd143cf6bf1c330e6cef7467783d82443e5122006e5d2fa200f1c2</span></span> <span class="giallo-l"><span>00853,</span><span class="z-keyword">0x05eacb145ed3b25a1949999d28e34eaf4aaf8cc033cea6569f8b53a4d49199cf</span></span> <span class="giallo-l"><span>00854,</span><span class="z-keyword">0x787444532a61379ba993a92688941b3fac90f64fcf9a32d022ef0cd78544f813</span></span> <span class="giallo-l"><span>00855,</span><span class="z-keyword">0xb042cdda0306e8678b89046603d24839002d4916d40849b5dc9e65f3124952f0</span></span> <span class="giallo-l"><span>00856,</span><span class="z-keyword">0xc3dd963be82c9bd8bd0a27cf846b0fc901d63b7a5de84844305385a2de4dcb57</span></span> <span class="giallo-l"><span>00857,</span><span class="z-keyword">0x1caf90ed8dc29fba89264af3ba07d0874e2f03c223cf387fec52bb0b7c4c5017</span></span> <span class="giallo-l"><span>00858,</span><span class="z-keyword">0x7d89c8e7e7bb553c60a7fff4c056575791ef965ece8adcbb8923c17c2ca42403</span></span> <span class="giallo-l"><span>00859,</span><span class="z-keyword">0xec9f0685cf4c7e59b45c2627b98afbf56f2d113415af631bd875962dabe376ba</span></span> <span class="giallo-l"><span>00860,</span><span class="z-keyword">0x608f5138cd3fdba7adca86cca1623b02d967a4ddfdabc1626298aef841f06e98</span></span> <span class="giallo-l"><span>00861,</span><span class="z-keyword">0xbc7139248334659528164fddc3c05f6933494abdbee4e82b5c16960461fb6bb9</span></span> <span class="giallo-l"><span>00862,</span><span class="z-keyword">0xf5d2654fda6b2a14dfe9f390fe8464887263d7415ab839418c21db6d00b75e02</span></span> <span class="giallo-l"><span>00863,</span><span class="z-keyword">0x29f0d1bd4ed36f2a8fcddc968249af476e48f49eafa8c1cb3ddaef3c9f6fbb5d</span></span> <span class="giallo-l"><span>00864,</span><span class="z-keyword">0xba09ed24136ed4ecce9e3aca125ba9cffdb949164e4ac0115a7e5636bae9ff81</span></span> <span class="giallo-l"><span>00865,</span><span class="z-keyword">0xef98f25e48fa78413bfcb8bc7d7bfede024ae12b74727667431d0b7b24c88197</span></span> <span class="giallo-l"><span>00866,</span><span class="z-keyword">0x62ec875a0d3529f36a0559e183518082de0a399e1b4840e3d5d23b4ea1e6adcc</span></span> <span class="giallo-l"><span>00867,</span><span class="z-keyword">0x6e38f92d9e902c7c4e46d334d8f15126fd82a220c3529cecddde6b7892187ada</span></span> <span class="giallo-l"><span>00868,</span><span class="z-keyword">0xada339e00fa18f5a7a48601c4d9db77332f4df313771b2a166bcdf02c07b5dad</span></span> <span class="giallo-l"><span>00869,</span><span class="z-keyword">0x687f70ac1c22d04c591b239219d4cea3fc899e22a15656cdadbfffee43900445</span></span> <span class="giallo-l"><span>00870,</span><span class="z-keyword">0x69305b6644efa1ddeffdbb7c5fbd55450e67237a3bb38fb8f08e81c567952569</span></span> <span class="giallo-l"><span>00871,</span><span class="z-keyword">0xdfb483577885f06bf36bda6c0918ddbb8ff30612412e6b4a67cc4bc867f2c44c</span></span> <span class="giallo-l"><span>00872,</span><span class="z-keyword">0x1fe0bd683f075a332f51a8d355282e02186aaa79a97f75c6a317dea751ed8b30</span></span> <span class="giallo-l"><span>00873,</span><span class="z-keyword">0x6754774ca2adf65caf7d126d0a1b7a3a9e9385968e96d8ed20389a3c3a96895b</span></span> <span class="giallo-l"><span>00874,</span><span class="z-keyword">0x89ed1e981eaab47a9b1afe89f4d8fd3eb60d208cd9cc2cd3c94c2a5e784f3bf0</span></span> <span class="giallo-l"><span>00875,</span><span class="z-keyword">0x918e70e47775c40e4aa6674b40d2f502e26dea08e7fdcc95fc612f9411268617</span></span> <span class="giallo-l"><span>00876,</span><span class="z-keyword">0xb174fe364a001d733d0ea0de0724d33c30d59ead3ba2f7c318322935c17b9027</span></span> <span class="giallo-l"><span>00877,</span><span class="z-keyword">0x1ee06c6001f96af9abdc53c79801ed63bac846f1de194b8e31fb0e99e6cb2dee</span></span> <span class="giallo-l"><span>00878,</span><span class="z-keyword">0xacf82dea7eff2b6749a07263ad51979a18d25e10191259c97531804deffe5f59</span></span> <span class="giallo-l"><span>00879,</span><span class="z-keyword">0x194ae19978f7ceff5b951ccc21ca69e4093db9f14b3dd735675b658614b50163</span></span> <span class="giallo-l"><span>00880,</span><span class="z-keyword">0x88dc77d7fb4be097712c34808ae6bb09f4adc13e82457e2bdb930cf79cbb08d3</span></span> <span class="giallo-l"><span>00881,</span><span class="z-keyword">0x291ee430fcbda963ea5ab68df639ea92ce325530844b6e5b43a306fbd3bf86e7</span></span> <span class="giallo-l"><span>00882,</span><span class="z-keyword">0xe0bd01b96a078f578b599838c06357e455d023c72381c0c9d96d2a57099f038a</span></span> <span class="giallo-l"><span>00883,</span><span class="z-keyword">0x24ee5653b2b7060f64b723f52723897140c6a39d07a35da8b362335a12fdda1e</span></span> <span class="giallo-l"><span>00884,</span><span class="z-keyword">0xf46491735b52306f745dc8a439441898c7a9dcfe6301ef0cb0f933c55d8b9432</span></span> <span class="giallo-l"><span>00885,</span><span class="z-keyword">0x18be58079d1320046e689e4fe43cc04d43cfa1794999974288fcf3625e6411a4</span></span> <span class="giallo-l"><span>00886,</span><span class="z-keyword">0x7b8e7f87674815b502a57c0797eca3288e0b5ade2a8ca7f78dd7ba632b127e25</span></span> <span class="giallo-l"><span>00887,</span><span class="z-keyword">0xebfbdc0207cea435c10b7052a0937c699721b2e7e41a2d925d0eab2ab81e9c8b</span></span> <span class="giallo-l"><span>00888,</span><span class="z-keyword">0x2911ec4630e2dd25d76cb86d8ad8427de4fca247c5e641ff2ae16038edb9ff52</span></span> <span class="giallo-l"><span>00889,</span><span class="z-keyword">0x7bc66f0a17605a2e0a082da2f3f99d6d424efa091d15c856e0bab50875629e07</span></span> <span class="giallo-l"><span>00890,</span><span class="z-keyword">0xde4cc0f167df6278f89a5cd047e8079d7e9368fed79d2ecb3e8b31537f744260</span></span> <span class="giallo-l"><span>00891,</span><span class="z-keyword">0x1aa1a5b9610ffa5b41fac5bd68fcc7f767d3434baaeea70e20f738d369a44315</span></span> <span class="giallo-l"><span>00892,</span><span class="z-keyword">0xb5354846b7a3b0764849ba2c006bbd7ab19d10f2479bd99c822442214eb135aa</span></span> <span class="giallo-l"><span>00893,</span><span class="z-keyword">0x75d76eeec8dd8ee7b5849b76e8e3c5b363adbf59fed68f0df8c89ced4106ff94</span></span> <span class="giallo-l"><span>00894,</span><span class="z-keyword">0x81aa556ec3ccd95dbb8e26a987f6e0434ca41766f68949258ce05f805f74a808</span></span> <span class="giallo-l"><span>00895,</span><span class="z-keyword">0x4704352715ff20066ba6150a55318d0e9066ae548b4375e4ce9b31e530598c61</span></span> <span class="giallo-l"><span>00896,</span><span class="z-keyword">0x1ab5749f22bdf79c27d6a073d93687b6e375b33f38cda1d8ea1b8aa794c0de76</span></span> <span class="giallo-l"><span>00897,</span><span class="z-keyword">0xb81f63bc9725916a88ddb5a5a6d7b7d558afb1d55bf29d57952da749e99ecbb2</span></span> <span class="giallo-l"><span>00898,</span><span class="z-keyword">0xac96c90242fbe989a37f1711dfed7051aaa38a13d8e8bc3ca5a518a90713cccd</span></span> <span class="giallo-l"><span>00899,</span><span class="z-keyword">0x922b1cf4946990d76e6aa05024474ffce4b71c683db79dcd7d08fdafe537d04c</span></span> <span class="giallo-l"><span>00900,</span><span class="z-keyword">0x0f8ce28573d070b2160ba328d9eaa3d81af5b60443acea676cee7cd234f0dc9a</span></span> <span class="giallo-l"><span>00901,</span><span class="z-keyword">0xf6f06a90999d172458e44c324081d1ee668709a2e4273a35fbfcf1312b913999</span></span> <span class="giallo-l"><span>00902,</span><span class="z-keyword">0x65bd2e95f8d26b9e2b3360b40175eb62b0881772fc80085a3d872a533362f5db</span></span> <span class="giallo-l"><span>00903,</span><span class="z-keyword">0x3b916edf62cfaa0bdca3d8b3f13b9654ace5f3a1c6c9a787dc07452b69cd985f</span></span> <span class="giallo-l"><span>00904,</span><span class="z-keyword">0x2ebf7c0d8151e785e5eb6ffbda1269e7d9d7f36545711099119ec1d486642994</span></span> <span class="giallo-l"><span>00905,</span><span class="z-keyword">0x9e7868aa92b87527f63245914226d675e3d09172ef63e3191562d1869ccfd5f2</span></span> <span class="giallo-l"><span>00906,</span><span class="z-keyword">0x6fe8a5a96b514f6763167cd7925516af89e4014baae26d735fbfa65dc9ee1fd8</span></span> <span class="giallo-l"><span>00907,</span><span class="z-keyword">0xfc681d3f63c0705f771f6f7cf8fbae11076db7aea57e4aa4db082fc82324eaf4</span></span> <span class="giallo-l"><span>00908,</span><span class="z-keyword">0x65f7339775a6fcd357411605348f51cf908f2a6bda04b392ce76132c1fc5a40f</span></span> <span class="giallo-l"><span>00909,</span><span class="z-keyword">0x38ce4f9f511d38303d855f92e28b6e096b749211b0861af2aee292fd34ab3af6</span></span> <span class="giallo-l"><span>00910,</span><span class="z-keyword">0xd44a929f41f40d97e7767775efbcf22213dd313c0bbbecbfe6130712b28b2fb2</span></span> <span class="giallo-l"><span>00911,</span><span class="z-keyword">0xfc91f464f9eae7f2fe1844bcd1c304c8467227c5df40b5518f2d262e14aeb011</span></span> <span class="giallo-l"><span>00912,</span><span class="z-keyword">0x9acf8a7ebab7d5ea23e59c7434b854b29d79a7d52153264f96886051df865c23</span></span> <span class="giallo-l"><span>00913,</span><span class="z-keyword">0x0790733786688f30e6d7d11388f7daf100afa105770f218e84321adc6427fd24</span></span> <span class="giallo-l"><span>00914,</span><span class="z-keyword">0x822dfb1aa7d617e0cdb16f997d992e643890aa048e9fbf89051e42349602ace9</span></span> <span class="giallo-l"><span>00915,</span><span class="z-keyword">0x62602cadc14d41fb1a9d1c682afdbdc3a535828fd89ab1474040dd571631207d</span></span> <span class="giallo-l"><span>00916,</span><span class="z-keyword">0x8b6dd223bb5846cf7af3766332bb4a3c7d0075b350f82c907db76a2765be8dbc</span></span> <span class="giallo-l"><span>00917,</span><span class="z-keyword">0xb309c46944a731132a289569e9cf52c57e9921b99cb00d02926f93fc83d6e86d</span></span> <span class="giallo-l"><span>00918,</span><span class="z-keyword">0x8974583a7b7ae104b867fa6ea76b999ddc399498dc070cd622df9b2eaadcf4a6</span></span> <span class="giallo-l"><span>00919,</span><span class="z-keyword">0xd139d7b42b3dc5b0316ec6e718f6ed470c2b8063357ca6a5525eaedfd77fe93a</span></span> <span class="giallo-l"><span>00920,</span><span class="z-keyword">0x5b83da490a1580b57e046be20c03b6f6b9378cfb8b8313a2d58cd10bac12884b</span></span> <span class="giallo-l"><span>00921,</span><span class="z-keyword">0x7a62f3b8756e0b45061ad40d0d08a4f400abcc7f8f9d21c4eac35d5eb3c69032</span></span> <span class="giallo-l"><span>00922,</span><span class="z-keyword">0x30f2071bcc7e743301be529cce48170478cf733c09f76bc7a007486e907b8d42</span></span> <span class="giallo-l"><span>00923,</span><span class="z-keyword">0x9f05e1511533dd79377f64581191380f2a4414538f9812bc978575ade32e4747</span></span> <span class="giallo-l"><span>00924,</span><span class="z-keyword">0x8d0da5014bf3664e6f3ee37a221447169bc7ef4cc2a98fd8141462fd4e6eeb28</span></span> <span class="giallo-l"><span>00925,</span><span class="z-keyword">0x9de1930ee287c457d1d7e31f789e7d73dbd9b2ae0b1db00a74a8ce7dcf8b022e</span></span> <span class="giallo-l"><span>00926,</span><span class="z-keyword">0xac17e41e8ebb278089444caf7fb6de4be8be17e0d2737713c19ee56e233b8052</span></span> <span class="giallo-l"><span>00927,</span><span class="z-keyword">0xad6865ca7acf691972f0906fa666ed8742cff9e41ccbf870f1c2e6c8566e1597</span></span> <span class="giallo-l"><span>00928,</span><span class="z-keyword">0x3feef311a950eb4f513f3f125bf4941b2664e7696c637c0998aaec146910944d</span></span> <span class="giallo-l"><span>00929,</span><span class="z-keyword">0x6e2d1f4b1c5ebbb67159e8db1774180c58e50b633117fa630e99025a4b648b12</span></span> <span class="giallo-l"><span>00930,</span><span class="z-keyword">0x228684d7571e71ed0dc00adc98f4ed6242dadbc65bffe61c131c91e396206d0e</span></span> <span class="giallo-l"><span>00931,</span><span class="z-keyword">0x2485471e5350c5da449bbd5b6cd731be0a47123f5b26becf1790b2a65e8ea608</span></span> <span class="giallo-l"><span>00932,</span><span class="z-keyword">0xf2f69e075dbae9462a935692b7dd566909e2d95734929376b0b7be14e0d42fd2</span></span> <span class="giallo-l"><span>00933,</span><span class="z-keyword">0x44eff5aecb4e111871225cc1b58c1c04786b1a4aba892784b7551b9e8ba90595</span></span> <span class="giallo-l"><span>00934,</span><span class="z-keyword">0xac8cf5be8f250e984277952c431a84b01c0ebd96e4d46cb1b456d0aabe2fa7e2</span></span> <span class="giallo-l"><span>00935,</span><span class="z-keyword">0xc052cdd4116d1987a3939c7cbfa2f266e8d181465561a8d0ade58075cce59ab0</span></span> <span class="giallo-l"><span>00936,</span><span class="z-keyword">0x0d1ce1ba874c0fe555d4c8d7a238c459d5cd3f93634abd7bf304eac7a225bd7d</span></span> <span class="giallo-l"><span>00937,</span><span class="z-keyword">0x20d0836298d617aab81be691f33cd1dc61546b081a1e913b7cf34e5afcb8c8d3</span></span> <span class="giallo-l"><span>00938,</span><span class="z-keyword">0xfb915a9512d1e0bb47c535ab0cc6e7ddaa439a720c4acd6d591be03ff738a402</span></span> <span class="giallo-l"><span>00939,</span><span class="z-keyword">0x2d5f2cb94ecafe782fc87c9a65f35a98a38b249bfe8a6c6483070d22f485c752</span></span> <span class="giallo-l"><span>00940,</span><span class="z-keyword">0x31a360b2a347dc2d8ff1e2ee51c8d487fb02b3ba20ea86104e8c0010e6840674</span></span> <span class="giallo-l"><span>00941,</span><span class="z-keyword">0x6247e765c7acc0135a2a1c8359ed9280836e63aa78bea7e5d489d44cfceda482</span></span> <span class="giallo-l"><span>00942,</span><span class="z-keyword">0xc352aa92f9ed89ebfc84d9bf131e0e386a26b3e6264cf3ef6e0d3262fc55df2c</span></span> <span class="giallo-l"><span>00943,</span><span class="z-keyword">0xb8b31db995add4b70a2637cc3e46d37b0f9bb608f63ed39b1676115569cc95e1</span></span> <span class="giallo-l"><span>00944,</span><span class="z-keyword">0x2a8be08321010d8fbc280fbe2ff0d9a9102738f588dccbb4401ec722067450fb</span></span> <span class="giallo-l"><span>00945,</span><span class="z-keyword">0x80961bb9747aa130e7b0f37c81951fb8d28bd916ac200bf5cf0ff8b4b5bb2bd1</span></span> <span class="giallo-l"><span>00946,</span><span class="z-keyword">0xcaefe64b2e4fb5f87ec1027d5ce8c9c545e116b687657c5b3789d195c29377c0</span></span> <span class="giallo-l"><span>00947,</span><span class="z-keyword">0xccd88affa72df06596b5ea6d9429fb5c0d3ffb7fb2ae2be3746463c4572841c4</span></span> <span class="giallo-l"><span>00948,</span><span class="z-keyword">0x11d91c258be65dae198f1301b2b3bbefc22d80a62dc3c789577a9d9584441322</span></span> <span class="giallo-l"><span>00949,</span><span class="z-keyword">0x209f845f27a7cfc68440e96a9a05f0bf9ffdfe3fa2b77f0b66ce46de6ee6a1df</span></span> <span class="giallo-l"><span>00950,</span><span class="z-keyword">0x4a9dede78effcd06746878f1ad7c1c255e7451ead558f94a610d64de9e84a569</span></span> <span class="giallo-l"><span>00951,</span><span class="z-keyword">0x6493fcf8ae0df3ba0344e3f3962cd9cedc50b435d278c680b1ad7fe580046213</span></span> <span class="giallo-l"><span>00952,</span><span class="z-keyword">0x611a2c464cb0aed5d1ff89013df62f77a4c66a4dbfbd1310b861e17c0821d850</span></span> <span class="giallo-l"><span>00953,</span><span class="z-keyword">0x81e7d01751bb41cf701d58e15e5e24af7cab732efa990fdfc807d04965a7949a</span></span> <span class="giallo-l"><span>00954,</span><span class="z-keyword">0x19895bb27f335092570be78e1c9e4390bc3165c12f3b4801c3386502dc1c14fb</span></span> <span class="giallo-l"><span>00955,</span><span class="z-keyword">0x443f9153e9d10aa291a75482f6ccb32b7f03e5ff28ffecbc218bfb0d17645c82</span></span> <span class="giallo-l"><span>00956,</span><span class="z-keyword">0x3dcb543b7fe04863694029ec36709cb2be65281eb77801ec7a43c47421b2f266</span></span> <span class="giallo-l"><span>00957,</span><span class="z-keyword">0xa2d2aa3950ccd9bd38664a108384da939a29e5bd3602b44f2e6d0f7e078f8181</span></span> <span class="giallo-l"><span>00958,</span><span class="z-keyword">0x24f3f044349785645a815ecae5ca634e5068415f3e47f83a4de78d1f5a0ae0a8</span></span> <span class="giallo-l"><span>00959,</span><span class="z-keyword">0x8fc647c479f7467e99986f5a67aeda9ffc96c49cc3b2d939adf2e02e6cb631f1</span></span> <span class="giallo-l"><span>00960,</span><span class="z-keyword">0x680241a45f3921d7038f95843ee7c15a97fac6acfffad14edd0b80cd52525b8d</span></span> <span class="giallo-l"><span>00961,</span><span class="z-keyword">0x759690ad2ec0fd1d75ef612e00b72ba25bc5c2cafa795df819ac5410fe245a45</span></span> <span class="giallo-l"><span>00962,</span><span class="z-keyword">0x12b37dfb28e1b19692de0b9ff9e4564d3712ba1abf0085cce006e61354f9b7c5</span></span> <span class="giallo-l"><span>00963,</span><span class="z-keyword">0x2b4168b786abedf1fd231b205fd827ce376aa3dfad7df2e8ffa37559c8aaa489</span></span> <span class="giallo-l"><span>00964,</span><span class="z-keyword">0xa7136656c0ac8a32a5cacdb85d35f7b1cfbf46add043b65d63870b7be188e662</span></span> <span class="giallo-l"><span>00965,</span><span class="z-keyword">0x8a62b4050b97c853f8b86c1a27865c5e8550689c699c7ac2cf18d534b4bb523a</span></span> <span class="giallo-l"><span>00966,</span><span class="z-keyword">0x73e45b2c1971c37f6bffd67467b444874a0168db85f916c4e1e1cc0d760a48e7</span></span> <span class="giallo-l"><span>00967,</span><span class="z-keyword">0x399424597ccba8d81b2fb6d2f5b16a310e43bbee1d546bc0a80450f7ab202a60</span></span> <span class="giallo-l"><span>00968,</span><span class="z-keyword">0xdce8aff6baa754aa1d9c385dfd56b5d0ff0c9644cb0756cdecf9c4b1dc75396b</span></span> <span class="giallo-l"><span>00969,</span><span class="z-keyword">0x49be47569890def0996f17dea252bad3c05e4f90c23a6b441e05db55deef4df3</span></span> <span class="giallo-l"><span>00970,</span><span class="z-keyword">0x68c57c6ab509c836dd5c5c0ce07cb41070698639ea7ea4b9faa07dd05d9ae9b4</span></span> <span class="giallo-l"><span>00971,</span><span class="z-keyword">0xc4f6b046bf04ee48a7360f9271b8507f13e222b37deab56d84090d8ad7071e40</span></span> <span class="giallo-l"><span>00972,</span><span class="z-keyword">0x13a7fe3ff99f61c26ce53cfad439b83aa50af5659ca5095a1666106ae43b178e</span></span> <span class="giallo-l"><span>00973,</span><span class="z-keyword">0x135d2ae11ee8c376d2ee5ca54ebe8ce915d133c5c9330f9669c3f870cdebe438</span></span> <span class="giallo-l"><span>00974,</span><span class="z-keyword">0x922bb3c21c999cafa708dbc7df398abd83cdb51aab98537adceb848b95b0531e</span></span> <span class="giallo-l"><span>00975,</span><span class="z-keyword">0x27b6441bb01ad4bcc2254fbbaea88e69e4adc75d9305a086085602eb971306af</span></span> <span class="giallo-l"><span>00976,</span><span class="z-keyword">0x63eafa02faf46070cc68eff888506aae7e0bb2a4ef9558fa2ab095bd30b95d4b</span></span> <span class="giallo-l"><span>00977,</span><span class="z-keyword">0x05bdc732d86d690e9fd8fe7fa8ee4077e92535202176ee37b9a2f124e7bd4212</span></span> <span class="giallo-l"><span>00978,</span><span class="z-keyword">0x95d7750a07f5423f61cbdd6797537c1316d250854bd865639df437ca3c70cbb8</span></span> <span class="giallo-l"><span>00979,</span><span class="z-keyword">0x8cf0d6245c51d3d854eb5a77b46562c4416f5dd64386eb5254036e44e189c9e1</span></span> <span class="giallo-l"><span>00980,</span><span class="z-keyword">0xa8768f5c3b2f7d860b55b71d01ededf8c4925a13c4f6eba25d2f1e9eb5232965</span></span> <span class="giallo-l"><span>00981,</span><span class="z-keyword">0xc4e8ddcfb6cf6972583902cb5e2d10c8be3ba895b076f7ba8e29c09de1a5e512</span></span> <span class="giallo-l"><span>00982,</span><span class="z-keyword">0xd4ecd7c319b9e27e4929f7c0e3ee7baa94b58604b55a0684832524f816124f41</span></span> <span class="giallo-l"><span>00983,</span><span class="z-keyword">0xd39b640f89b8d62e6a58bdda604a6931e5a97494270b8c13639c9291152a856c</span></span> <span class="giallo-l"><span>00984,</span><span class="z-keyword">0x22592d52da8f0eed167b072bd3f9d68708ac37af6884b76497f518e419efc4e3</span></span> <span class="giallo-l"><span>00985,</span><span class="z-keyword">0xe4e144f9d02c04d79c9d03a3141f6a90d3a9217d2f348a8b5f57ed50deba907f</span></span> <span class="giallo-l"><span>00986,</span><span class="z-keyword">0xb5e7db59cf4b1329d19cd7dec561c3eb7353eaf71f3f5eb92f1cfa9525425fd1</span></span> <span class="giallo-l"><span>00987,</span><span class="z-keyword">0x9316c767971e58e2fcfd1bfa386d6d678f05194403a9371194b26e160614f57c</span></span> <span class="giallo-l"><span>00988,</span><span class="z-keyword">0x871302efe9a899f706e248554a0a7834244e9b94db1aacad82a96f70d50ce3c8</span></span> <span class="giallo-l"><span>00989,</span><span class="z-keyword">0x1c3a761603d969947df6da3491d18a2f55dc67cad3d7ae813aca79089e8e4dee</span></span> <span class="giallo-l"><span>00990,</span><span class="z-keyword">0xa666b3895ff153f24a671fb6588494111eecd4c4482379b6bd662361f955de46</span></span> <span class="giallo-l"><span>00991,</span><span class="z-keyword">0x3154c955d0dc8f9ed8f5e7ebd476b549d5778600afc737a213ed6156765af846</span></span> <span class="giallo-l"><span>00992,</span><span class="z-keyword">0xd078def25dcdd2df52d7e37bc2910e598ac00c921473f8d93137a07d3a403edc</span></span> <span class="giallo-l"><span>00993,</span><span class="z-keyword">0x6b2615f1fe8043e3f4f06ff4f918c0b34bed01cf776b535a3a16530b81fc9d91</span></span> <span class="giallo-l"><span>00994,</span><span class="z-keyword">0x6ed3f90facb487fa49945d0ed5f987a03b8bf76b0377fe2980bfe9cac2a5b6dd</span></span> <span class="giallo-l"><span>00995,</span><span class="z-keyword">0xd3223ce7a69afde216dd1c957c6116cb76bc2d70895921c2ccd6b9d4f79038f0</span></span> <span class="giallo-l"><span>00996,</span><span class="z-keyword">0x016c769b453ee0995a23b0b20bb83c3870ec7754867b8676da1c3e4849511160</span></span> <span class="giallo-l"><span>00997,</span><span class="z-keyword">0xe19a4c9d8889c46240475ea0e669e967b4ca09dd35085c327dcf75e127093d3b</span></span> <span class="giallo-l"><span>00998,</span><span class="z-keyword">0x36c9ff39ced94ac5d4ce3c5d8ce14030ca154bcc2e99abdcbd71344e8b0fdfce</span></span> <span class="giallo-l"><span>00999,</span><span class="z-keyword">0x83c72fa27934098dbf8aea00c2491a9dba82ed6ae6f116f12ef96404f63ea6f2</span></span> <span class="giallo-l"><span>01000,</span><span class="z-keyword">0xddcc603638d6f6aca751013a22d42f0b3dc9e55794978e37f46c38b622fe0ce5</span></span> <span class="giallo-l"><span>01001,</span><span class="z-keyword">0x2d0fc419efdaf8f46067013cf528064da86116db18b5382289afb4b6e1cf2b9c</span></span> <span class="giallo-l"><span>01002,</span><span class="z-keyword">0xf69f7b396a816ec0b8a377e3e75ee054c47339cce83f24de1453561c04f24789</span></span> <span class="giallo-l"><span>01003,</span><span class="z-keyword">0x1763271040eea5424900aea6164448f842f699eb662f8409d95e5a5635cf20c2</span></span> <span class="giallo-l"><span>01004,</span><span class="z-keyword">0xfbfc02162b85f7c870dba66af17bdcbad0f5e6dbb8c7b0f2ef936a0858595077</span></span> <span class="giallo-l"><span>01005,</span><span class="z-keyword">0x584687a4b29aad825e7a6f106afe5f27a97ae104d3cdd7389fad0f44ad5cb101</span></span> <span class="giallo-l"><span>01006,</span><span class="z-keyword">0xdf8970e84c6c9134c98a890c83c4649fbae258db7cc5d3b1fc3c63cd6ab64708</span></span> <span class="giallo-l"><span>01007,</span><span class="z-keyword">0x2fbbff929c09f13110369d940831fde47cd6eef07d5449d4b3f9d353ca155dce</span></span> <span class="giallo-l"><span>01008,</span><span class="z-keyword">0x235c9a91c69ce2ce21267dfa82b595caacd3f9ee09d9ad725e5913c317a05646</span></span> <span class="giallo-l"><span>01009,</span><span class="z-keyword">0xfa09b4f1cabfd5bf65704b38982b06a536e316ef4b533db69a73ce2bf88a571b</span></span> <span class="giallo-l"><span>01010,</span><span class="z-keyword">0x3cacc95c0a0f16f81baca64b7331b81bb577b2ce6d451b9b3773f1770fb1a948</span></span> <span class="giallo-l"><span>01011,</span><span class="z-keyword">0xdbcb3c6423aa05a61c71ddbf3181af582e525b5a72a9ebb8e44913bb981acfb0</span></span> <span class="giallo-l"><span>01012,</span><span class="z-keyword">0x6ac002dda4b8f105f2bfcfe0be9f0dd8cd543abaf99e36340397026f68fb1210</span></span> <span class="giallo-l"><span>01013,</span><span class="z-keyword">0xdd1763be363eae6e854d82cf948ce79aa3903b24fb1bebf83efa5bb9ad8454c1</span></span> <span class="giallo-l"><span>01014,</span><span class="z-keyword">0xc4e0e059fb5489787f907324c81a46a400a87b3cc056601f8a9eb5fc88b1d32a</span></span> <span class="giallo-l"><span>01015,</span><span class="z-keyword">0xd2d13e5ed7819f3841af3e911c3516211bac48169a52d6c0f0525b94af603d61</span></span> <span class="giallo-l"><span>01016,</span><span class="z-keyword">0xa93277ff5640373ca1446607c231f0bed5bd15a096142e7376580f3fc78841c8</span></span> <span class="giallo-l"><span>01017,</span><span class="z-keyword">0x019e6db033ebcb56d9d51ba309d4f010fe79a0df9f6f3114b052390e273ec750</span></span> <span class="giallo-l"><span>01018,</span><span class="z-keyword">0x763ea921a273d3b92099e451f36949767992111073117536583f5fab34dff71d</span></span> <span class="giallo-l"><span>01019,</span><span class="z-keyword">0x45d2795144aa708f2aa6d5016635c887f97c9e609dd7eaa30fbdbe04ee2acfb9</span></span> <span class="giallo-l"><span>01020,</span><span class="z-keyword">0x37e8f37e7fe680451499d4cda814162837dd4e60b9dbcc1cb4a09d8aad95cb5d</span></span> <span class="giallo-l"><span>01021,</span><span class="z-keyword">0x6654a92dac9365e122dfbf52b5d2134dadf1d638aafa879893e50ee2da2152ad</span></span> <span class="giallo-l"><span>01022,</span><span class="z-keyword">0xb81a65c13cc3d54b281e9ad392e8792910ad09b39b8dcaf6ae8e3fbce06117a3</span></span> <span class="giallo-l"><span>01023,</span><span class="z-keyword">0xb72e8700d81b2d7c322dc74a3f37dfce6f3b08a487a92242fd0ec2b8bebe21fb</span></span> <span class="giallo-l"><span>01024,</span><span class="z-keyword">0x75f6d852198927b79d8ad8bd5505983052e9ac80b80d5dacebd4687d60d549e8</span></span> <span class="giallo-l"><span>01025,</span><span class="z-keyword">0xcd13479c8725155feebfed83954d53ffcb6725683f43c866acffbc6e9b97ccfe</span></span> <span class="giallo-l"><span>01026,</span><span class="z-keyword">0x1ff6a9b9fc585560ae6780a7c54170e8f501324a894f00f08828697d661ef0e2</span></span> <span class="giallo-l"><span>01027,</span><span class="z-keyword">0x6c76c020b3f3f95b9c50a8d6d7949cc9c9798522070f5e35e61c6521473e15e6</span></span> <span class="giallo-l"><span>01028,</span><span class="z-keyword">0x78f9905648fbb6eaaff40a458301f05a7bb753a6288eafc141c797ca01db044d</span></span> <span class="giallo-l"><span>01029,</span><span class="z-keyword">0x3dcb5e2a8b6791f5141c8ff08ac59a36030c9436e6ec6de8274be01fb81112c0</span></span> <span class="giallo-l"><span>01030,</span><span class="z-keyword">0x373e75f1325d787a5f7e66c6b888083a7b1b2e6250d2764bbe1b4f1145dd9b72</span></span> <span class="giallo-l"><span>01031,</span><span class="z-keyword">0xf06e62b5bde482371af35d2b3eb05bc4e9f80da90c64f9a36c8405bd0779f123</span></span> <span class="giallo-l"><span>01032,</span><span class="z-keyword">0x3f19793eebeb6aabbbaa055ef131d73f1186be249bd8bbe2b11af0dbd783cf7f</span></span> <span class="giallo-l"><span>01033,</span><span class="z-keyword">0xa9765c1c7bb916043bb42b1572cd96f905c3e2f5fdae49010a5102a9eb4a700c</span></span> <span class="giallo-l"><span>01034,</span><span class="z-keyword">0x1dcfe01766b650af58d6becf6de168e7da980e7058c7b6424da1b0c470a7ebca</span></span> <span class="giallo-l"><span>01035,</span><span class="z-keyword">0x946b550f1e19e68d272a10be6c0a1f9310da704cdbdf518c8a90b694748a8c29</span></span> <span class="giallo-l"><span>01036,</span><span class="z-keyword">0xb953b4b78c6b2446d60625b65ebdb25165d4c9a46916ee303b5daa16029257c6</span></span> <span class="giallo-l"><span>01037,</span><span class="z-keyword">0x8356dd445dc79c97a83819c8538aab5176664d436bfac3e9971b1c9cea78022f</span></span> <span class="giallo-l"><span>01038,</span><span class="z-keyword">0x3cefbeb9ce2ed071c7abb2b55fa1f8ced72cf1f2f9bcc24955a17aaf1eb99c29</span></span> <span class="giallo-l"><span>01039,</span><span class="z-keyword">0x4765ee428148e60b0038ce5034cbaa7259b0d85403d37936cff1f1f220c09419</span></span> <span class="giallo-l"><span>01040,</span><span class="z-keyword">0xc559659c692f7eefd643fcfdebf8697a04634c839b6e1724382b3bcdfcb15170</span></span> <span class="giallo-l"><span>01041,</span><span class="z-keyword">0x1b1f9767d845eef02506d6a6c54fffcce5bd6bc59b41b00f17ef06e4c63edede</span></span> <span class="giallo-l"><span>01042,</span><span class="z-keyword">0xed5a8fb5f2b0ab802832bb99d32a9ba463945ffbfce2f56f26e9c39fda1c3fe8</span></span> <span class="giallo-l"><span>01043,</span><span class="z-keyword">0xa396fcbd5b63936ec43b6bacaf2b0236783c638eacc72614daa29e792ffe1ac2</span></span> <span class="giallo-l"><span>01044,</span><span class="z-keyword">0x33bd34bdc9b4c51f344e476fb8c97fe80cfded7c90de437f100505b17823c66a</span></span> <span class="giallo-l"><span>01045,</span><span class="z-keyword">0xe62bdcaa8531750ae8fc247c76445a76670077643060efc80323e864c2c2c480</span></span> <span class="giallo-l"><span>01046,</span><span class="z-keyword">0x37db60cdd4270773f870c9cb8eb3368d0e1443789dc44cd653b0f423addab3c9</span></span> <span class="giallo-l"><span>01047,</span><span class="z-keyword">0xd02ff344a0e66526266e7ac1ef9269ee132e793c2a3eb2c20c95212665880232</span></span> <span class="giallo-l"><span>01048,</span><span class="z-keyword">0x27c44206ef714c1ebdfa21cd959c074063432f3fdcd7a3b0b2ec4375e12ba53e</span></span> <span class="giallo-l"><span>01049,</span><span class="z-keyword">0xd74dcd433ceba7a2a6702e807c68470b446772565b466b0878d4518983640500</span></span> <span class="giallo-l"><span>01050,</span><span class="z-keyword">0x583482c4b0a752dd12430176b663ff8ea5fd11f2eeebd8b956702d0eb473a748</span></span> <span class="giallo-l"><span>01051,</span><span class="z-keyword">0xb1375fb5970e469451f9e7b9a29f3b20ec0c583ec90b79fbbf38f9e981d9a9ea</span></span> <span class="giallo-l"><span>01052,</span><span class="z-keyword">0xfc68a5dbc89395b13fec398a9ad78b00d813fbbb259f005e6fba1eb1bdc7f2cb</span></span> <span class="giallo-l"><span>01053,</span><span class="z-keyword">0x038d0dc543117df0c46ca6cf4467721780eb951017373d51aa88ece1a380f56c</span></span> <span class="giallo-l"><span>01054,</span><span class="z-keyword">0xfc630d10c00e0f843cadfac7d24f8ad02f7603bc7555efb4fe7e6a33d42d8fca</span></span> <span class="giallo-l"><span>01055,</span><span class="z-keyword">0xdc564afcfef0c40d16d7fbfd90afc419bbc37fc750f790130acaffc32f985dad</span></span> <span class="giallo-l"><span>01056,</span><span class="z-keyword">0x75fba5d5c98ffc1f67f8a1ea520808f94a547003fa4fafa34ba7f9b2dfab7383</span></span> <span class="giallo-l"><span>01057,</span><span class="z-keyword">0xf2a347f31fba049b5994122c3d6de4d37196ce8fed6c7c7b5c2c6926c28811c1</span></span> <span class="giallo-l"><span>01058,</span><span class="z-keyword">0x7e00f70a6b91f77cdd78c01ca54d506dcc25f226fbbd13d56b0c80e8c80c2694</span></span> <span class="giallo-l"><span>01059,</span><span class="z-keyword">0x7c557845f4abf757fef7dbbd11b44e44c92025733d16b57ebdec6ae10f381f38</span></span> <span class="giallo-l"><span>01060,</span><span class="z-keyword">0xd6b988695e3c2a57b1d3038de5262349766cea46600f70b8cda2998ae395894c</span></span> <span class="giallo-l"><span>01061,</span><span class="z-keyword">0x7edcc464ec0b7bd04070e80a4795a4d59581d9d6d53756eef10ae5a38b40259b</span></span> <span class="giallo-l"><span>01062,</span><span class="z-keyword">0x84fae3dfe3699b7ab0c58b47c604799d1fa7a0088138efd63cd4603e79cae112</span></span> <span class="giallo-l"><span>01063,</span><span class="z-keyword">0x97a50adfaebf0ad4f60329d82fc6fd897416be8c698e6a6d3b6e7da8934a2f97</span></span> <span class="giallo-l"><span>01064,</span><span class="z-keyword">0x25e68a390fda36ad8fee616a22d79cfc531127e6c8cbc11710e8f5743399d9bc</span></span> <span class="giallo-l"><span>01065,</span><span class="z-keyword">0x88ea91bdc01e8bc0fdda51dd2abbf05a92a14c20052dcb563faef0bcaaf5d161</span></span> <span class="giallo-l"><span>01066,</span><span class="z-keyword">0x77a58ff5479dab194fa000221e98fa4e6dc77aec51aed889bcb852db57db3d03</span></span> <span class="giallo-l"><span>01067,</span><span class="z-keyword">0x95926dd93886d32de8692bda38da9e4ab10f9026ddc5b9ff69c30f55e0915ebd</span></span> <span class="giallo-l"><span>01068,</span><span class="z-keyword">0x9e4b22f0088519c08bfd6cefbe125caeefa43b83b451fffba1a87223dfbcc62f</span></span> <span class="giallo-l"><span>01069,</span><span class="z-keyword">0x5451d56c823a2e8d42ad39859e0758b8a4829a11daadd96ceb4ab2b29874c7b2</span></span> <span class="giallo-l"><span>01070,</span><span class="z-keyword">0xdd746cbf406b80fca7b25d95961640fb0ae5d411468001224c3770b2554b95ec</span></span> <span class="giallo-l"><span>01071,</span><span class="z-keyword">0xe7162b854ae8194deb0bd3a34eb77be0bf539ce76c566ae2e05207968a908b95</span></span> <span class="giallo-l"><span>01072,</span><span class="z-keyword">0xa0266c3199c30bb4c8ec4b5797d112795c89dbfac6478dd5d3b772a14158fd69</span></span> <span class="giallo-l"><span>01073,</span><span class="z-keyword">0xfb390415ebb31243ff63e550cf27cad325550dfee0b421c1c1be75a845319585</span></span> <span class="giallo-l"><span>01074,</span><span class="z-keyword">0x7d668fd503ab1327817d49218ba493e6174918a03b3120133126c453ca345e20</span></span> <span class="giallo-l"><span>01075,</span><span class="z-keyword">0x38bef7ff6fd5999f6446ad8abfdf10a24045ae1b837b0ab70e1db500eaf4cead</span></span> <span class="giallo-l"><span>01076,</span><span class="z-keyword">0x55f5a07a76490536966de1a99fee90d723ebae9e8d0806d9ed6f1580b2174db7</span></span> <span class="giallo-l"><span>01077,</span><span class="z-keyword">0x61a13d92beef22d97be7f3c1656cae6760fc08e36db7d381d5c96222fd50f864</span></span> <span class="giallo-l"><span>01078,</span><span class="z-keyword">0x227e71270b878bdc138b23386bb7b33cec9175875b461b04902f4af708c31580</span></span> <span class="giallo-l"><span>01079,</span><span class="z-keyword">0xf1a39e59434a97dce0d30cae7bd6feb571827cceb3ba57af6af183e953c24b6a</span></span> <span class="giallo-l"><span>01080,</span><span class="z-keyword">0x1b7d09908d41e6463da4ef25bc4a7e2545528671a510352110cd382f5b300d8d</span></span> <span class="giallo-l"><span>01081,</span><span class="z-keyword">0x679b43594ec30c0fde26f3a2e05561c7e110ebc15cce1ec5b6d7da2fc5a415c3</span></span> <span class="giallo-l"><span>01082,</span><span class="z-keyword">0x5e7dea252df625a366ac47bfcb1e8eb2df49d44d0be463f98ba95d256d6982d5</span></span> <span class="giallo-l"><span>01083,</span><span class="z-keyword">0xcdcb8e564e8695a687939ac1a0fd1a0cc5dbb352f9cd24427cde8360b2a9f200</span></span> <span class="giallo-l"><span>01084,</span><span class="z-keyword">0x5f2ca307599872cfc55256ad29009b53f3303d024b5b782a4abb591c8cbe5a57</span></span> <span class="giallo-l"><span>01085,</span><span class="z-keyword">0x12230dff9cefa72d522ebb791d84eee3ec55b5c4a4600209cab7c376171fa159</span></span> <span class="giallo-l"><span>01086,</span><span class="z-keyword">0x6eb5d461ec98068957cdab5b2028bbd8b1b2f7a221a8ea9c8011071da37d7b2d</span></span> <span class="giallo-l"><span>01087,</span><span class="z-keyword">0x45541bfe08784bc6d1298d97e0308241efaf18a47bffe4894dcc26ef776b7b0d</span></span> <span class="giallo-l"><span>01088,</span><span class="z-keyword">0x09f2f43ee828665d8d45859b5e36a8b9d31283550eccf4f73b1a87638e709803</span></span> <span class="giallo-l"><span>01089,</span><span class="z-keyword">0x4519917d2bb898a1810ede8b13275e678198aa773f7eef2b2c05c129942cb259</span></span> <span class="giallo-l"><span>01090,</span><span class="z-keyword">0x506362e6d66ca9341da4fb5706d690f94711b6673ab9b7d7ac22dbd39e0af8db</span></span> <span class="giallo-l"><span>01091,</span><span class="z-keyword">0x408e7c249b773c396ee2a412fdd8ef7e43fcb5538e026aedfd34d7b9b721e60d</span></span> <span class="giallo-l"><span>01092,</span><span class="z-keyword">0x4f1216d3d70323582c6544bf9c07bc6bf3582ddd01a52550b257b1e078dc12fa</span></span> <span class="giallo-l"><span>01093,</span><span class="z-keyword">0xf7943fdae6b71a9c1a6d7320a61ebb908c32b91e8c9679808b09da9f28774225</span></span> <span class="giallo-l"><span>01094,</span><span class="z-keyword">0xa2458aba8fb9a34aa4b4a5ac20b23f843e8b12929bdbf793499c0187de963643</span></span> <span class="giallo-l"><span>01095,</span><span class="z-keyword">0xc3174a59e85dd195642088336274f531f551c50dbadf407323d0d1d5ef961bff</span></span> <span class="giallo-l"><span>01096,</span><span class="z-keyword">0x5475a30e12c46b42b661a0932c94efe35bb76575dc0030255dae625933f32712</span></span> <span class="giallo-l"><span>01097,</span><span class="z-keyword">0xd2ce1e42bbb308bb9e0abb971cf5b4d9ab1cca8fbd73d11b3cfc19dd0b3b235e</span></span> <span class="giallo-l"><span>01098,</span><span class="z-keyword">0x5fb12ec44e61e8a76d79d4646c09a67627cccf3576e52206f580364cc03080de</span></span> <span class="giallo-l"><span>01099,</span><span class="z-keyword">0x1cd92052c419c186c329a14c7bab28a4496c23e243635d5a263a3ba34d0052c4</span></span> <span class="giallo-l"><span>01100,</span><span class="z-keyword">0x22b095d488d0fbd0f10e209b322ca59ad319975d6d3c90a81d1fd9b6d0243dc6</span></span> <span class="giallo-l"><span>01101,</span><span class="z-keyword">0x844b63b3997c0468086656f4733991f97ec42d5fb1b65c050113d515117bb756</span></span> <span class="giallo-l"><span>01102,</span><span class="z-keyword">0xbcce4dd3d6cd5b08a76bb8890eef30ad7df184972df8a271648de5269fe1ed26</span></span> <span class="giallo-l"><span>01103,</span><span class="z-keyword">0xc97117921c0dc002265d161013da1171084008fe5b51d046c695b5e626c9994b</span></span> <span class="giallo-l"><span>01104,</span><span class="z-keyword">0x5035027c4b5ec5e2df56117a2e012b79c9aafea7bc89a3015e9061e226893245</span></span> <span class="giallo-l"><span>01105,</span><span class="z-keyword">0x9331be3bcf98379d8a0e2f65a70785c10fd620d3fad050315c2a1e2f6c8bd6a7</span></span> <span class="giallo-l"><span>01106,</span><span class="z-keyword">0x901078cb9b1d4516ecbda207acb6e6e2891a134b0c80b647240fd8ad50016063</span></span> <span class="giallo-l"><span>01107,</span><span class="z-keyword">0xf8edc0d4190782ba1a6bb98105a33cedd5d71c25b22e0138d5bc5d902f9f5a34</span></span> <span class="giallo-l"><span>01108,</span><span class="z-keyword">0x42362545904d6792bb88ae2a9f7d29b10623e58260d0ec47749781227123a2d9</span></span> <span class="giallo-l"><span>01109,</span><span class="z-keyword">0xbc521ceaa2bd28faf23c9f256b2b24c98bfdb90a020d25216026f95d065eb0f7</span></span> <span class="giallo-l"><span>01110,</span><span class="z-keyword">0x199eeafe5585e55674bfa0a341988e470b65ef78061b3f20eade8d1e271ef3a6</span></span> <span class="giallo-l"><span>01111,</span><span class="z-keyword">0xd34462829eff8702ce5561c6b1b715e63c8a89b7f5eb274e8c5588cd15678ba1</span></span> <span class="giallo-l"><span>01112,</span><span class="z-keyword">0x1c93ba5b0b9c65421fb9cef8cd24cae654c4ba7d386a53b6036e4019eb517c55</span></span> <span class="giallo-l"><span>01113,</span><span class="z-keyword">0xbeafcef83fc5e6769d82b3c304c0cbd5a1add1277e1ac300f0bc5c7e2822f2df</span></span> <span class="giallo-l"><span>01114,</span><span class="z-keyword">0x71ec790b6d9c1f8e40159317162256dcd6f52a700215fc61d329587c64b248d9</span></span> <span class="giallo-l"><span>01115,</span><span class="z-keyword">0x6f6094bffde8d3ae31ac86b2ffa489481cb8b4b440d4613edb06f5e40f0effc7</span></span> <span class="giallo-l"><span>01116,</span><span class="z-keyword">0x053afb71d72d02a534cf646231ef23fbcb10a93ffbb85b43bf6364a1b6cc2015</span></span> <span class="giallo-l"><span>01117,</span><span class="z-keyword">0x98396ff4fbee74940a9a03c33032d84f7285608a0a3ee7c58e016ca8c42157cb</span></span> <span class="giallo-l"><span>01118,</span><span class="z-keyword">0x5747971200ae6086c2054eb6a3d0a5307b84a2c2e7ce4dd0b99fcf278b5b066a</span></span> <span class="giallo-l"><span>01119,</span><span class="z-keyword">0x1554c47385b828df19e22779047108210de2c8a34fd0346f77b9a80c630637a1</span></span> <span class="giallo-l"><span>01120,</span><span class="z-keyword">0x5db300fa117451b25a6f7a59a55e33947378c5216687ed6ba23f38a721cbc21e</span></span> <span class="giallo-l"><span>01121,</span><span class="z-keyword">0xb9aeb88a7f2c33e5ef7b0eb9e4001ce50b96bd4576f174ff5fbaf2aaa0ca3cff</span></span> <span class="giallo-l"><span>01122,</span><span class="z-keyword">0xa8849157cde19e3801e69291365f8fc095855ea313f1a6cf5b39d1f117ff166a</span></span> <span class="giallo-l"><span>01123,</span><span class="z-keyword">0x0b7bcf33f4e42502cf5f0c981f1103bbb8f9c98a0a4a02f3ac10baa8328906ea</span></span> <span class="giallo-l"><span>01124,</span><span class="z-keyword">0x224f4405f110ce6825bab6f6c209a4b5518894bf489795e92195a87013406ff6</span></span> <span class="giallo-l"><span>01125,</span><span class="z-keyword">0x0b6064b3c367b296c0a422c00bf4606867164d315c7ab16d89f1ad2957a4734c</span></span> <span class="giallo-l"><span>01126,</span><span class="z-keyword">0xc7344cf278e4f244a49689243aae7f3fe30e1ce07e5aba04ceac1cc40fa922cb</span></span> <span class="giallo-l"><span>01127,</span><span class="z-keyword">0xad12ba3851456ed8b37c7f21c8825c885a767cff2bb776be648cb8356946cb0b</span></span> <span class="giallo-l"><span>01128,</span><span class="z-keyword">0x3a386e6dc1d155d89af575c544cd88581c7d178bac55cc44f63b2ee888223764</span></span> <span class="giallo-l"><span>01129,</span><span class="z-keyword">0xc77dcea67936565fa9d9eb078ce575698500dd17988daf0a7a8f246ff5508833</span></span> <span class="giallo-l"><span>01130,</span><span class="z-keyword">0xa25a8fc183706411fa20ed4f3b2a68d96e0b161fc09468f33beb434c48f58bba</span></span> <span class="giallo-l"><span>01131,</span><span class="z-keyword">0x0225209e1b7c3463f869898432742732f32fd1e7c5f64e5ed74adaae2eace9e1</span></span> <span class="giallo-l"><span>01132,</span><span class="z-keyword">0x1ba9f77cea8694123218706715d4224221fdd5af2b022d015071d6443aa3a1aa</span></span> <span class="giallo-l"><span>01133,</span><span class="z-keyword">0x8e1c1d63b865ae597bfb51c82899e0aa4107a88dcc6ab180ebb568c6de993700</span></span> <span class="giallo-l"><span>01134,</span><span class="z-keyword">0x3197a1d6c72f1891609283366e120a1f4c61412f83835684f28901d35249a04a</span></span> <span class="giallo-l"><span>01135,</span><span class="z-keyword">0xd28f2c9f79253b151384e63f867a55278831d92575d63ea0a6b14f39f373161c</span></span> <span class="giallo-l"><span>01136,</span><span class="z-keyword">0x6cf8d26d850172c2e2bb9629792fa93afec55de913957c778fe0895734ae70d4</span></span> <span class="giallo-l"><span>01137,</span><span class="z-keyword">0x62215680c0a6143f5f66137de7a13356a0d1837fa842aca997aa6d4eeb1bd7d7</span></span> <span class="giallo-l"><span>01138,</span><span class="z-keyword">0x44e4142c95e4d04f4b598a4146c0fa04fde6db6afd78ddcc8be9fd16018ce72b</span></span> <span class="giallo-l"><span>01139,</span><span class="z-keyword">0x1a70666e7cc7d475d738b07cb5e2984097e0e30df160b1d9b0698f33a9048c83</span></span> <span class="giallo-l"><span>01140,</span><span class="z-keyword">0x9bef85d30bd7319c6ac73e9195d2fb5a87900b61f09eff71ff9aaf6dd39d6c8e</span></span> <span class="giallo-l"><span>01141,</span><span class="z-keyword">0x48066cf2b5c1a5a553ecd2ca62a466bd7e462a9836e3108fa9b9c50084109d71</span></span> <span class="giallo-l"><span>01142,</span><span class="z-keyword">0x112745d12d9f1ffe670ec1b1b1526ce0b586f0348788742af013d8b5ae8f1e50</span></span> <span class="giallo-l"><span>01143,</span><span class="z-keyword">0xc07f562554568dd0a8d7d83f4151cfa979abf944c364f627daacfe42d6c8e75f</span></span> <span class="giallo-l"><span>01144,</span><span class="z-keyword">0xff3489f3959c367261b35a4a8cd106e9b8e504da8f95c752126874757a68d8a6</span></span> <span class="giallo-l"><span>01145,</span><span class="z-keyword">0xaa9a507ed68dfe695d15723f7f31e32977b1aa74bb8a948c2edc27a55c6b377b</span></span> <span class="giallo-l"><span>01146,</span><span class="z-keyword">0xae05fa5d0e96ad9e6fdda36bcc44637b1a4b9822c275dd6b0fbb7471715fbc57</span></span> <span class="giallo-l"><span>01147,</span><span class="z-keyword">0x0dca795f11fbe372384ddae72721019ac51bb29767f1de14c808ca5278015b6b</span></span> <span class="giallo-l"><span>01148,</span><span class="z-keyword">0xb970027bb776fd436f03d55bfc77b43836eebe0391f2f2673a794e5d9648ab7c</span></span> <span class="giallo-l"><span>01149,</span><span class="z-keyword">0xb2f6f5174d78083b50511b907c2e86378294179e05d89fbd98baf0996055f8ba</span></span> <span class="giallo-l"><span>01150,</span><span class="z-keyword">0xae9dea31e94ecadfec8694ff8db30c1527a1b4deaabc042794cbf0f7ba068fc2</span></span> <span class="giallo-l"><span>01151,</span><span class="z-keyword">0x1cb2b8d45a6d2a7a1b43aacd57d78702ff161f96b9141d8489ada32fe1c8a705</span></span> <span class="giallo-l"><span>01152,</span><span class="z-keyword">0x28b41e3872cd3343b0901208ef472e26d98ee3facb64d2787e6f1196cda87d09</span></span> <span class="giallo-l"><span>01153,</span><span class="z-keyword">0x9cc1f6f0ae4b10e85063dbcd30cc2077a2eff89daadb9ee3391e9c460e39d1cc</span></span> <span class="giallo-l"><span>01154,</span><span class="z-keyword">0x1d470ae11e0f409328f29e315a1881c3eae67123d48019c748a01f4e4f381aee</span></span> <span class="giallo-l"><span>01155,</span><span class="z-keyword">0xb516307f14425bd9ee0434ccedb692092eff147562ee7805e0c6e0df0a475d7b</span></span> <span class="giallo-l"><span>01156,</span><span class="z-keyword">0x8c4c11190ca958c76cad26d8514fb383ee51183c49eb56ab2aa41704249b6ddb</span></span> <span class="giallo-l"><span>01157,</span><span class="z-keyword">0xd7bb8fbd3048f3b139a3c64191ecf38bf1a218dd9544903b8ef3d0e546cd8af1</span></span> <span class="giallo-l"><span>01158,</span><span class="z-keyword">0x12ec0becbbf83afd68392f4d9b67d5a8da89979557cce60530735a1465c0fc6c</span></span> <span class="giallo-l"><span>01159,</span><span class="z-keyword">0x4fafaf52d0c069b6f587ee7a519e715604f4de04fca1a19e726671ac56596b38</span></span> <span class="giallo-l"><span>01160,</span><span class="z-keyword">0xd0e1b363591af53d56c1c6a146bb78ecdfec21f12b34759aa832501c89c26a40</span></span> <span class="giallo-l"><span>01161,</span><span class="z-keyword">0xcaff530399938686e3364b6b228b3ac59e3b22f21b1c2b3450118170fb281836</span></span> <span class="giallo-l"><span>01162,</span><span class="z-keyword">0x070dea605d09f3096df0b0f76948df8a38831c90c4581ffcf6fed7bde0cc268a</span></span> <span class="giallo-l"><span>01163,</span><span class="z-keyword">0xd285b66ebcd5852a1911fe5599702a89a0dadda1405cf84dcf6d55bcfe0f9578</span></span> <span class="giallo-l"><span>01164,</span><span class="z-keyword">0x2eb4c50feff7659cdd8f3ef48b6f9175a2a4b891d09af13bd0b414bff9b0bcfc</span></span> <span class="giallo-l"><span>01165,</span><span class="z-keyword">0xff4e71c2c49d497341e7386bdca329ab892c94197d5fbbd18166cd48843de333</span></span> <span class="giallo-l"><span>01166,</span><span class="z-keyword">0x4116850a1bd36ed591c1e95e3cb1aace3675a61d1c86e1660da988d5faec71dd</span></span> <span class="giallo-l"><span>01167,</span><span class="z-keyword">0x5b6986455f3550b4faaa88fdccbffaf90f897971254d9b8f3ddec649b5260b5d</span></span> <span class="giallo-l"><span>01168,</span><span class="z-keyword">0xa23912b4a361e10bdd6093479763b042c8d09f8fc8a5909170b57b6aebd98339</span></span> <span class="giallo-l"><span>01169,</span><span class="z-keyword">0x0737b4e5ab8f9071f44e61b66da61df228dc0414f3ba5dde12b7a8fb10b2e618</span></span> <span class="giallo-l"><span>01170,</span><span class="z-keyword">0xdf35982e9c74b401291f2ae70a09ea99766219008b0e01880cf6302e9d62b60c</span></span> <span class="giallo-l"><span>01171,</span><span class="z-keyword">0xcc7466dda5723a0c33c326d1596717848dfd0256867df4d68deaa8adc3f61db9</span></span> <span class="giallo-l"><span>01172,</span><span class="z-keyword">0x9abdb4aeec79e7dfe79fdb6711da93c071c9099542344da75fe1d968009f98e1</span></span> <span class="giallo-l"><span>01173,</span><span class="z-keyword">0xcdbdfbc64a23515c0dcf517dfd71825cbe5d9fc98566f9c6b02f733e8a1ba3ef</span></span> <span class="giallo-l"><span>01174,</span><span class="z-keyword">0xd79c75b859479066f9caa316c37f67fb7728dfc01a0d94f6a27ef126ac0692cf</span></span> <span class="giallo-l"><span>01175,</span><span class="z-keyword">0x0d2dbfd717f62ea857069cde24b45df8fd214ef044057175265d747411304051</span></span> <span class="giallo-l"><span>01176,</span><span class="z-keyword">0x94adbb4c520dffca694df807f479af7b035da83f3de81f014e28ea2d34e70adc</span></span> <span class="giallo-l"><span>01177,</span><span class="z-keyword">0xd5e0dc5aa1b4441e615373ed2c8782ce41b20b2a7816e81ee4311c243d3b7be0</span></span> <span class="giallo-l"><span>01178,</span><span class="z-keyword">0x5c34962d525fd40d9c8bc44f522af67fd89111d332eb9ba5cc9b0f138a4059e6</span></span> <span class="giallo-l"><span>01179,</span><span class="z-keyword">0x1de75523ed57212207b3227983ba8bbed7607c3574300abdf11cd1a372136e40</span></span> <span class="giallo-l"><span>01180,</span><span class="z-keyword">0xaac82868aa7edb8173d1d41c6b0745b7eee734182d4fdfd54e6043350afc116d</span></span> <span class="giallo-l"><span>01181,</span><span class="z-keyword">0x5899663553cb5e7842e72b43a64d86113a4b76aaec2b0774021361171aeaee29</span></span> <span class="giallo-l"><span>01182,</span><span class="z-keyword">0x74b8aa4405d31335e0f8eb310028c7d05972831702b931b5f28d5afb3d52d854</span></span> <span class="giallo-l"><span>01183,</span><span class="z-keyword">0x38d8567174aadf1166952a632dcc85d4a4b8c20c946f2399878183141a10b561</span></span> <span class="giallo-l"><span>01184,</span><span class="z-keyword">0x2a82d902f0d2aedb663fe6998f7abaf0cd666aa3d6bea64e81d8d83c92b0351b</span></span> <span class="giallo-l"><span>01185,</span><span class="z-keyword">0x528d123a4c8b57d0b25864c5b3f673c21fbee2a1826dab6cd6ae9ee0024e85f5</span></span> <span class="giallo-l"><span>01186,</span><span class="z-keyword">0xdcefe6dde10acc340d071c61813392ec065800ade9040e5b721fb20fb8239a7e</span></span> <span class="giallo-l"><span>01187,</span><span class="z-keyword">0x25b5519cbb7efa28ff1b23d0f46e38f7b3b2c3fd96d493c5285991894e371f40</span></span> <span class="giallo-l"><span>01188,</span><span class="z-keyword">0xa8eec3288b23734dd343db2bf518380753dd2f602d80584c1a8247f2e2e3466f</span></span> <span class="giallo-l"><span>01189,</span><span class="z-keyword">0x0912534018135146db16c094d6a7a067062a455ba846f44be4d79e2c47094417</span></span> <span class="giallo-l"><span>01190,</span><span class="z-keyword">0x13085b0bb2b86b44d0fd7ea1476bee11b641b11dba8005afbf167cd3526855eb</span></span> <span class="giallo-l"><span>01191,</span><span class="z-keyword">0xe8d4138f22d8fb0fcb988bbded449ceb966203228554022e6e0564b9ed6ea1e4</span></span> <span class="giallo-l"><span>01192,</span><span class="z-keyword">0x7a4ee2172c8081d3f6dddf4bb6c561c8ce3f1af703ac6b591e448c762b8f1d9b</span></span> <span class="giallo-l"><span>01193,</span><span class="z-keyword">0x7c6dae3a659f3b4fad0b797c457a546ef174569dd60a71b6a4fc1e66d1e1f268</span></span> <span class="giallo-l"><span>01194,</span><span class="z-keyword">0x7d063ead7a3d4d51dc59256b72738faf2171d7844da6d5be42af7023f690d979</span></span> <span class="giallo-l"><span>01195,</span><span class="z-keyword">0x68a0b792e3b448d4c36f26611d9b7652585f23f216785bb73d5c27c0c0aed493</span></span> <span class="giallo-l"><span>01196,</span><span class="z-keyword">0x94c969763e706d0e7fba95c4c357b0e855c68be2dbed2e9a7cf7b5daaac5a08b</span></span> <span class="giallo-l"><span>01197,</span><span class="z-keyword">0xa6c39440cf6d60b35b0ebc651ab80a101b0f57d9163379474ccbeac8827d5fd2</span></span> <span class="giallo-l"><span>01198,</span><span class="z-keyword">0xf7a5ab53c462dba797a3b06ab177ba42b11a370240ce077b03fc1fa2b107f4ea</span></span> <span class="giallo-l"><span>01199,</span><span class="z-keyword">0x84b9e12ab6e9c0e7f41dcd01aae0ae2357ed252b3ebd78c0b2d95fff5e032724</span></span> <span class="giallo-l"><span>01200,</span><span class="z-keyword">0xa6b6a963488c4633e7f3af99047954e1c15fab24793fe43a4c9ec2c933031f01</span></span> <span class="giallo-l"><span>01201,</span><span class="z-keyword">0x4a0c7f03de3cfd31752d5100b70f028c31856efa2fd1a3b5a8cec4a342500d34</span></span> <span class="giallo-l"><span>01202,</span><span class="z-keyword">0x5486c645e895bc1bdc91291f74d5ce702e1c2c4d37f005c6c1968c96c4798a0c</span></span> <span class="giallo-l"><span>01203,</span><span class="z-keyword">0x08a5313b986a0428d49ab7b7f6cda4ede434efa3f6a69c5140ee7c46c977c30f</span></span> <span class="giallo-l"><span>01204,</span><span class="z-keyword">0x975103710d4d4cc0c9b337decbad38e6dd42449ad533b3c464801bf10a0f7f8d</span></span> <span class="giallo-l"><span>01205,</span><span class="z-keyword">0x7bbd5580e1faf3394083ed3a12ecc3efeec75b71b52f3c5d2527306d47d46c9c</span></span> <span class="giallo-l"><span>01206,</span><span class="z-keyword">0x61e11a8ca3db52b16ec4c025165e73542fea9eaed696dc528b1fc7d08bab6871</span></span> <span class="giallo-l"><span>01207,</span><span class="z-keyword">0x3745949046134c86ab95f8da5fac1e0b96e9146b8dfe976b95ea8adfdeb10fb0</span></span> <span class="giallo-l"><span>01208,</span><span class="z-keyword">0x4d0cc348ca8825a306f854475c04b618a82336c06150b936407f793bb132e1d9</span></span> <span class="giallo-l"><span>01209,</span><span class="z-keyword">0x2008dcc12d9eee29e24645e17c3a32c8b0fa82423b230b1bca74982ff32499ca</span></span> <span class="giallo-l"><span>01210,</span><span class="z-keyword">0x842d419500195cf77644f8d7f656e9e0c7044c7c0227eef116f0b54bd52b8456</span></span> <span class="giallo-l"><span>01211,</span><span class="z-keyword">0xa9c1369756e021602515ee071013086b92c4050c767db4f6952a5e875dc74415</span></span> <span class="giallo-l"><span>01212,</span><span class="z-keyword">0xa6435d49ee936444ea5411227769e4e92c9bdc5e353fb90feda369d0b357ca32</span></span> <span class="giallo-l"><span>01213,</span><span class="z-keyword">0x71e5659c8984140dac3efdb27964e2e36dabdf863d34d9a44509ab28ff76d3bf</span></span> <span class="giallo-l"><span>01214,</span><span class="z-keyword">0x1791e683cadd2556b588f262ed01f10dec8a17d0fac17264cde17dc821d61444</span></span> <span class="giallo-l"><span>01215,</span><span class="z-keyword">0xb250520d667d2585a11f8515bbc942dde5271dee48bb2079e94fdefb4cd12db7</span></span> <span class="giallo-l"><span>01216,</span><span class="z-keyword">0xa13eb7c2b5320556bec64b033af8d17d73880423b1aeefd6befe0a80516cfff9</span></span> <span class="giallo-l"><span>01217,</span><span class="z-keyword">0x5c83a392daf6735cbd58715ddad8b5ee5ffab29f0d90e9529cca55f1e5a9bf65</span></span> <span class="giallo-l"><span>01218,</span><span class="z-keyword">0xc13220ead135c3a3c44eb1f623db0231af2a830eba39328d3b0eeddba6590b32</span></span> <span class="giallo-l"><span>01219,</span><span class="z-keyword">0x5f56b030ea9674db988e0e19b92ca4f4d0172eddb66b88d1421b761f43f430fb</span></span> <span class="giallo-l"><span>01220,</span><span class="z-keyword">0x512900cbb649da6361f264485c211c79688543284d48129d978f50ee9110ed54</span></span> <span class="giallo-l"><span>01221,</span><span class="z-keyword">0x90c06f460cbaed5f47e45d4761dc4860400fcefcf38a4adc8dac265798ea82d6</span></span> <span class="giallo-l"><span>01222,</span><span class="z-keyword">0x096acd8679ab399726890ee06192292f292205150e75a75d8dbc24fb5b5c4e95</span></span> <span class="giallo-l"><span>01223,</span><span class="z-keyword">0x1a1baa666116d37631224699f89e17da92ae1d5df34857e3429b0eca71f473c2</span></span> <span class="giallo-l"><span>01224,</span><span class="z-keyword">0x34f529a2f72e1e83cd12adeb4dea7f2bdf3d7c96ff50249b27a0c6a65cadca90</span></span> <span class="giallo-l"><span>01225,</span><span class="z-keyword">0xad7198e0def6e143734a5dc947221958a8e506274daa782383fbe833e664d60c</span></span> <span class="giallo-l"><span>01226,</span><span class="z-keyword">0x2d858029db92532563a3dd2e05e63de9600abd032bc3402b598df65b03b96f45</span></span> <span class="giallo-l"><span>01227,</span><span class="z-keyword">0xbb9ed6f343eb8d8aac3a7190c4327752c136b8d2d7a9cc4cd58ce619f2541c50</span></span> <span class="giallo-l"><span>01228,</span><span class="z-keyword">0x024d8b0934652fece1c1009e992ffcd5a39c0bfaf4b9e464b492368fcae0b44e</span></span> <span class="giallo-l"><span>01229,</span><span class="z-keyword">0x4fbd23d89d82ef4034f1bdd888e2b20cd2338e5430326039cc82a8ee32242e3f</span></span> <span class="giallo-l"><span>01230,</span><span class="z-keyword">0xb70e3603aa922716ba38abca5dc445639eff218cbc2ace3e2352be344588676c</span></span> <span class="giallo-l"><span>01231,</span><span class="z-keyword">0x76e468cbc19d282a6075b218eafd19f63234beae51e46b0c2b81bb0b707b0632</span></span> <span class="giallo-l"><span>01232,</span><span class="z-keyword">0x7cd7b651d63b2e5a4f6684ae77ab9d3d913449a92eef5a716ecc947ba553b724</span></span> <span class="giallo-l"><span>01233,</span><span class="z-keyword">0xd077ca788a7927c7d2f8ca57710139fccb6e387c563fdc34aa9c8ca05ae0bf35</span></span> <span class="giallo-l"><span>01234,</span><span class="z-keyword">0xccf5a0f7216ad6bb2ddc6f59917c9d33ef237a7813b09052ce349a26bb21fb10</span></span> <span class="giallo-l"><span>01235,</span><span class="z-keyword">0xd7666847f3b02e9a581f7bbd41e906b894136b4f98503c2e2458718f08d319b3</span></span> <span class="giallo-l"><span>01236,</span><span class="z-keyword">0x3d10b1757feee8ce9ee56ab7d3e36b34895674fa7c6c90b2636e85f0a9e16368</span></span> <span class="giallo-l"><span>01237,</span><span class="z-keyword">0xcfc709d64aefa7fcd84780a576f8d229f3f093993a38b6271826efaba6b55b46</span></span> <span class="giallo-l"><span>01238,</span><span class="z-keyword">0xf6f1e083e51e96a0b399e5878186085e9ca7d12512822558c2ed1e156a72404b</span></span> <span class="giallo-l"><span>01239,</span><span class="z-keyword">0xcbeef9b07ca5099aa5f6bf79fb7d58a0e8418af292e992b4c1f1d9bf43f12aec</span></span> <span class="giallo-l"><span>01240,</span><span class="z-keyword">0x02688fe8520ef9c0a4bc424936bc9b710a973517598bf394274c2a44cc848289</span></span> <span class="giallo-l"><span>01241,</span><span class="z-keyword">0x20ebd6528acd0d0e507af27f82db0aef20556c9dd36f482dd78e12a39cf5855f</span></span> <span class="giallo-l"><span>01242,</span><span class="z-keyword">0xceb89cc1fff1a05d00b8cb8049f5ba68b4e0fc338a5b7593e1bbbbbf4fe7c3b1</span></span> <span class="giallo-l"><span>01243,</span><span class="z-keyword">0x6ca6a14a6edb58aa90fc386305b46048d24dd9b525e204b503970cad8c8864e3</span></span> <span class="giallo-l"><span>01244,</span><span class="z-keyword">0x40769f6cedf1218dd656126546473cdb24657724170f0bd71c0ccdac1edb3e97</span></span> <span class="giallo-l"><span>01245,</span><span class="z-keyword">0xf2f56ea6ddf8226f222ae389816836c60e8fe9bc55e630c93e8d6634a2babbe2</span></span> <span class="giallo-l"><span>01246,</span><span class="z-keyword">0xc0e897c05df5e53027934987158c81a2dab1a62638db704cbacc8a2eb0c3931f</span></span> <span class="giallo-l"><span>01247,</span><span class="z-keyword">0x58d2fe58f1fc86b6ed0e2f210e13723c8ed644dc8d32ffa4e55cc176b7bcbc3a</span></span> <span class="giallo-l"><span>01248,</span><span class="z-keyword">0xe2cdcc7c61fe867dcef5ed3854538fecccc3ee1501b6e66f3132596c79c41a93</span></span> <span class="giallo-l"><span>01249,</span><span class="z-keyword">0x379da93b0902e34eca8296446820ad2e24d3e4feebf1f0faa061e099bcca3366</span></span> <span class="giallo-l"><span>01250,</span><span class="z-keyword">0xafede008f90c6812f90e9cb5a5462e3dad70fe5f0d0fb383f833845659bf25e4</span></span> <span class="giallo-l"><span>01251,</span><span class="z-keyword">0xeeede50f94cb63b7e19cfddbcc3f25e3c06dc4c3a83b001804ca440540d37d43</span></span> <span class="giallo-l"><span>01252,</span><span class="z-keyword">0xc5b81847b51e4e59f89d6cf2361c42f64dc760fce9f0bbd332653de1f7474ef7</span></span> <span class="giallo-l"><span>01253,</span><span class="z-keyword">0x96748f6773bb94d740ab82734c26ffc9daeb4c87606403add65897512864e693</span></span> <span class="giallo-l"><span>01254,</span><span class="z-keyword">0x5c3badc9304a265385eba2afff786a1f9464737b71d9301035b758820354da66</span></span> <span class="giallo-l"><span>01255,</span><span class="z-keyword">0x2599ae05afdf5e1b2be57990d21f985c0133406a8141639dbf33d46e632bf6e7</span></span> <span class="giallo-l"><span>01256,</span><span class="z-keyword">0x2b44aee4e83d46ed4a02abb9ca11c1630073fc6b233c5aac3730f8d28e695859</span></span> <span class="giallo-l"><span>01257,</span><span class="z-keyword">0x4952c5127010c24a46460214617a2cd34a5430ec398ba635392762668b21a64f</span></span> <span class="giallo-l"><span>01258,</span><span class="z-keyword">0x713aba14cadeaaf4ac33853d6a33ae19c0ec40e02821d467577b61e371a53ce1</span></span> <span class="giallo-l"><span>01259,</span><span class="z-keyword">0x1ae7b5ef37e8a2151263bd517645f1336e0907ef1c840b41e8732369ef1d3cff</span></span> <span class="giallo-l"><span>01260,</span><span class="z-keyword">0x6f90c321b6915a06965c7804e6e28aed175cd6d62162eff3fea564fda50fced4</span></span> <span class="giallo-l"><span>01261,</span><span class="z-keyword">0x61d416a84d212bea9580d2eba99ca6cdb0a45ea809d540b49ae52e6a2d9c5f84</span></span> <span class="giallo-l"><span>01262,</span><span class="z-keyword">0xaee21385dd0720113fea63062d20dc69e979bfcb5f295131694752dbfff3dc97</span></span> <span class="giallo-l"><span>01263,</span><span class="z-keyword">0x9fa06b72e89a042853139708961c7114d3197bd3c98c1cef71ca0b34c01652bc</span></span> <span class="giallo-l"><span>01264,</span><span class="z-keyword">0x53a8cc3b6aac658c3b80f92e99521056c4035fc053b6abbd4068e5339dca35dc</span></span> <span class="giallo-l"><span>01265,</span><span class="z-keyword">0x1366aabf8693566d39e974a595eb7e681f57170fa8d98c68e1f7a4397a6f4cf7</span></span> <span class="giallo-l"><span>01266,</span><span class="z-keyword">0x2631621efb6f486a6c82b58c7cba7c37dda933bee528d982b1c25570a45df03e</span></span> <span class="giallo-l"><span>01267,</span><span class="z-keyword">0x3dd94158da7fecd20d03095ac40774de44befb72fcedb2f94ca801619b5aaef6</span></span> <span class="giallo-l"><span>01268,</span><span class="z-keyword">0xed99cb91c4babc2b4eefa48bfc1ab03f710aa2bd4c6e12c60e0bfe78e6a774e4</span></span> <span class="giallo-l"><span>01269,</span><span class="z-keyword">0x3e65584f39c73ae662991d6d27dcfe9563830c5210ea07a12bae36dfeec36436</span></span> <span class="giallo-l"><span>01270,</span><span class="z-keyword">0x69ccf142f770f0bc36ec796d3893b895d9b602100a30528dafa20e5a2c28da1d</span></span> <span class="giallo-l"><span>01271,</span><span class="z-keyword">0x66fbd4f182ada36bac2d86fbdb791807f55f3c2c010c79d8fab7abaa404fb002</span></span> <span class="giallo-l"><span>01272,</span><span class="z-keyword">0x7f448c5eace75539049635435d61193beca590922f7255ef040ebe6da1f29306</span></span> <span class="giallo-l"><span>01273,</span><span class="z-keyword">0x3db6b5ee4daeb3747abef5998ae0ec1def30f96ff98043bc40dfce86966fde81</span></span> <span class="giallo-l"><span>01274,</span><span class="z-keyword">0x63adf378c2182a75a6bbec3cba265ead7a1d31cfc37324a5cfbd44e70d3e2392</span></span> <span class="giallo-l"><span>01275,</span><span class="z-keyword">0x0c89bb3e1a35dd2748bec8ed667b9345d50726cff25f170637c86382abd82135</span></span> <span class="giallo-l"><span>01276,</span><span class="z-keyword">0x399bff6479203b0d07b9409e2adbe174c602acc5f4c2368b4fb399dae9227b5f</span></span> <span class="giallo-l"><span>01277,</span><span class="z-keyword">0x1b14df373ee827661a2c07e3796b21ae8879dbb62ee89588bb43e2843c70b624</span></span> <span class="giallo-l"><span>01278,</span><span class="z-keyword">0x7bb5b29535784cb002cef2e3e34d518d7baa14aa2242dd3cdfd9e6e2801faadb</span></span> <span class="giallo-l"><span>01279,</span><span class="z-keyword">0x4ba003f31b565407c69e13af897dd4acc225a71ca04599415f68ee839e34d799</span></span> <span class="giallo-l"><span>01280,</span><span class="z-keyword">0x2ab6865f17d91c52d0fe177d6b465575f83380ecd7d8c7f9bf31b2377ca0a1f2</span></span> <span class="giallo-l"><span>01281,</span><span class="z-keyword">0xa55982471099400711214ced393e9909d0e04c35e862b6319ada8e63fe9c5457</span></span> <span class="giallo-l"><span>01282,</span><span class="z-keyword">0x8357bfd95a67b8e01b0530b10daa926d6368de1f37ebb787a24893a1813d61b3</span></span> <span class="giallo-l"><span>01283,</span><span class="z-keyword">0xb502eea2d534a1d9646b8cdf01a0021a2fac7b298ae298adfcb18a8adb51bf09</span></span> <span class="giallo-l"><span>01284,</span><span class="z-keyword">0xf9cc24977a6a162a4f21fea4c588d8586d5cb96298a95364e3cb1b50f1878fd0</span></span> <span class="giallo-l"><span>01285,</span><span class="z-keyword">0x5ad4fdc89fbf4b2817a64648f37a14ec2908b58b24a621a12f941d7e3d4e6a66</span></span> <span class="giallo-l"><span>01286,</span><span class="z-keyword">0x4de64a70d6df12d28fcaa8d4fed874f5aab3f070552189ce5e24582539c9f875</span></span> <span class="giallo-l"><span>01287,</span><span class="z-keyword">0x1cd8e301efbf3554bee4a3699272b01033f3a1087a8ea789132a07e1d08bd20f</span></span> <span class="giallo-l"><span>01288,</span><span class="z-keyword">0x461721aa1fba0486391f01c6b60ec368e021573fcef4c62a0d91204470a732b5</span></span> <span class="giallo-l"><span>01289,</span><span class="z-keyword">0xd776cb85c9b392f75696d6bb5733b4aac5f1e83a73719620efaf40a385468200</span></span> <span class="giallo-l"><span>01290,</span><span class="z-keyword">0x873eb969707feb65aa18bb94c3bd32f40fd891708a0977ede54d80ebab7e17a6</span></span> <span class="giallo-l"><span>01291,</span><span class="z-keyword">0x3466a3703a10207162520e73c9350cc646eec8158a0f5913345e0232ec37fd44</span></span> <span class="giallo-l"><span>01292,</span><span class="z-keyword">0xf7c7ef3af85eb27ace55a2b8174ed8d5616f3d6d8457c51678f8c5ce5ff6df2b</span></span> <span class="giallo-l"><span>01293,</span><span class="z-keyword">0xeab36fbdb3f08b469d02903085a59c455c1f8693e76b7005832a872fc19bfc3d</span></span> <span class="giallo-l"><span>01294,</span><span class="z-keyword">0xd38b96b71d18f88b5eee096a8affaeae086170fa9636dbd6d81b7f0bf03d34da</span></span> <span class="giallo-l"><span>01295,</span><span class="z-keyword">0x9a8e547ac87505373cd0a850b2dbcf87fd17a958e86b91f431dfacf8faa1cf9c</span></span> <span class="giallo-l"><span>01296,</span><span class="z-keyword">0x044263f35cee7bbd103e6537a34ef16fa8075121c6b2ac6cb9ccc932de47261d</span></span> <span class="giallo-l"><span>01297,</span><span class="z-keyword">0x2a6fa8404ebef74fb534dd65a52008d9c451c8e133a111118c38b238963d8c60</span></span> <span class="giallo-l"><span>01298,</span><span class="z-keyword">0x25e8cecf4a4009a8a3dfcb6e414a52939dd8f0fec0cdfa43fbb88f6d93e84d90</span></span> <span class="giallo-l"><span>01299,</span><span class="z-keyword">0x4783a5b474945636c48b35187b5236790a932a6688eb9d57663cedbfcc35e96b</span></span> <span class="giallo-l"><span>01300,</span><span class="z-keyword">0x05128f5669874610a201918ac659f325cadd39c596246a946c95c17899f4525c</span></span> <span class="giallo-l"><span>01301,</span><span class="z-keyword">0xf8ad3107c0c201f6c9c855fa7fe31ace8ea37cf483e4466de7ee0cd8d4a1961e</span></span> <span class="giallo-l"><span>01302,</span><span class="z-keyword">0x564f335c0b20dae960b81c7fa6715da2a7a1f32186ee0d0fe6fc162f36a3630d</span></span> <span class="giallo-l"><span>01303,</span><span class="z-keyword">0x0dd93fff7d2ebb6031ca921ae529ff7f0fa881b0b64d0fde89b532250afcb3ff</span></span> <span class="giallo-l"><span>01304,</span><span class="z-keyword">0x20eaa74f7d74b90dd75bf7750d80ce428e75745d60b92500549b4039163e674f</span></span> <span class="giallo-l"><span>01305,</span><span class="z-keyword">0xd00fc022fe14cd175a8a593bd0fc6cf8076872c16fc3672313415760c659de09</span></span> <span class="giallo-l"><span>01306,</span><span class="z-keyword">0x1f67a41c83d8ba9d5206bd10389cc97b98c2b2b50d46c845728f67421c9a8b7d</span></span> <span class="giallo-l"><span>01307,</span><span class="z-keyword">0x2f77e7c868bfd36ad2e2b0864b665ab2ecd6671d8be22c1738d3c01376d0b34a</span></span> <span class="giallo-l"><span>01308,</span><span class="z-keyword">0x8eaf029a66086147ba2206ecdbea385029fa3ea27ae9d93be466ef702f9ef909</span></span> <span class="giallo-l"><span>01309,</span><span class="z-keyword">0x0e9134c94db5ca1f3f8df20c06242afcbc7c099282c1b5662b7528344fd49f83</span></span> <span class="giallo-l"><span>01310,</span><span class="z-keyword">0x36d0712a3ad4551da02c8fbcf6ffb7fc9105d8b651095af88f9168884fec0ae8</span></span> <span class="giallo-l"><span>01311,</span><span class="z-keyword">0xb196f52df231958730a92a4cf0468e2648750cb5665142e160d881bc14e37bfe</span></span> <span class="giallo-l"><span>01312,</span><span class="z-keyword">0x052a3539fc9f8bc4d117b49c1e06b3c2f6ff129297b39d25174c8f0b8144001a</span></span> <span class="giallo-l"><span>01313,</span><span class="z-keyword">0xed3d98e8ee4b3ac94e1bf4f158c783a8415ba5f497f9e33a32f1800d60cc524c</span></span> <span class="giallo-l"><span>01314,</span><span class="z-keyword">0x6711d975c455a06ffe37404f2c044b0212d05580535f0b696e01c40a38ed2e15</span></span> <span class="giallo-l"><span>01315,</span><span class="z-keyword">0xc90257ccd4b09a7a0b1cfafa86eae19b648f0f9ff4d5f9d935b45179c45679d2</span></span> <span class="giallo-l"><span>01316,</span><span class="z-keyword">0xd23ae50b11a0b68e4233b0743b3ba73f087d2e8d9e73f74c100faec8838bf4b4</span></span> <span class="giallo-l"><span>01317,</span><span class="z-keyword">0xb2c5b1b5c44801e3d93702395326af0a9e333f6faa72ec9836bc0c6da90af82c</span></span> <span class="giallo-l"><span>01318,</span><span class="z-keyword">0x803d224bcaa3b2d5d0ba2de2837b8b808215de356282c671fd92e94b4970bd37</span></span> <span class="giallo-l"><span>01319,</span><span class="z-keyword">0xf7082c225833a231427c3a2809a4f77fd79ddf88a94991e251336feba0eeeb89</span></span> <span class="giallo-l"><span>01320,</span><span class="z-keyword">0x66c7f0046df871f8a674e08f13d66ace77969519f44ad0eedf44bee0a543036f</span></span> <span class="giallo-l"><span>01321,</span><span class="z-keyword">0x04af06fa9d5d1b4d162b96a9e979d61028b349d2c474a34d16d0c62761252504</span></span> <span class="giallo-l"><span>01322,</span><span class="z-keyword">0x44c4c046785d0a1596bfa34133b74b47e16a4eea6607b7633d84e90ed816d4b4</span></span> <span class="giallo-l"><span>01323,</span><span class="z-keyword">0x570d0caa96bbae3e4b2afc7f01b62f3d90fe232cb3797cfe54b52c3840bba0be</span></span> <span class="giallo-l"><span>01324,</span><span class="z-keyword">0xd4cb7a0d9740bace6d20e145e01f654c3388393fbc655b41d8693de6bb960506</span></span> <span class="giallo-l"><span>01325,</span><span class="z-keyword">0xb10b22ec3ae6d7252bd04d9bd6f2aeb5759cd1c33df99d43230b5dc2812fb5cf</span></span> <span class="giallo-l"><span>01326,</span><span class="z-keyword">0xea52129a4b82c6183fc1713117ed5d1803135642c2544612dbdaa6fd06be1b25</span></span> <span class="giallo-l"><span>01327,</span><span class="z-keyword">0x4f88b08507b8fb608565635faa36f8b09902017b2dfefd8091b05cc698e072a5</span></span> <span class="giallo-l"><span>01328,</span><span class="z-keyword">0x83f1204e20b3770edb57289e7f64401d79365d0c0e02a84c9c2c33ffdc496693</span></span> <span class="giallo-l"><span>01329,</span><span class="z-keyword">0x572dcecfe36d6a5159f90810209186d900bd940b27e56a8d1150aa4760e5b99b</span></span> <span class="giallo-l"><span>01330,</span><span class="z-keyword">0x45db98fb860512b9cbfce82e225581bc15103e772c385102f63aecc98b3053ce</span></span> <span class="giallo-l"><span>01331,</span><span class="z-keyword">0x79ac113e80705dc36acef32fd3d844dcda82fde0962d92da38a07e585edfaf40</span></span> <span class="giallo-l"><span>01332,</span><span class="z-keyword">0x2e02ff938a46434155167db8bc7aab30bb1380b9e3e7a61605bb4b98312305be</span></span> <span class="giallo-l"><span>01333,</span><span class="z-keyword">0x1c8da535daab62298766c9eedb38110eeafe1d6c2fc0a6fe344486e50d23d57e</span></span> <span class="giallo-l"><span>01334,</span><span class="z-keyword">0x9983596d69c4ca9358001d6e1569a17f8c35a885ba9dc1629aca595c0475af7a</span></span> <span class="giallo-l"><span>01335,</span><span class="z-keyword">0x4143f16c56cdd171e39f8a54a3bb2d2dea69490672df9fa7e30378def8867730</span></span> <span class="giallo-l"><span>01336,</span><span class="z-keyword">0x2c80acab236f71b43e253b5268c172dc3f413cf145e0216d7f6c13065422a2bc</span></span> <span class="giallo-l"><span>01337,</span><span class="z-keyword">0x70afebf06271380039afba9d7b5157f905d89598d03042f4bf4cc827f1d7b200</span></span> <span class="giallo-l"><span>01338,</span><span class="z-keyword">0x0d957f43c8483a069456ccdf1c44cfbb355796198e5b35eb365d66189c934b07</span></span> <span class="giallo-l"><span>01339,</span><span class="z-keyword">0xa954d4bbfb037a0e8f081be2b609544df79fc5f84f346fe687c83055e86b785f</span></span> <span class="giallo-l"><span>01340,</span><span class="z-keyword">0xd259e3dbd24e5d08dbc1cf127159be9095f93cb2e035fc12cd4dd9df06ce4d91</span></span> <span class="giallo-l"><span>01341,</span><span class="z-keyword">0xa393c46b554c380371d5f395f99c878959168fb83b010ee586dd627ea5ac81f3</span></span> <span class="giallo-l"><span>01342,</span><span class="z-keyword">0xfebdbdcdc98e1286f41f504e2457d4b9ad17d1747bfd60a3b16fba723620efda</span></span> <span class="giallo-l"><span>01343,</span><span class="z-keyword">0xc205cffc694cd333edf5deb8023b04a96ae6563e1de4acb4d93f34ce095a50aa</span></span> <span class="giallo-l"><span>01344,</span><span class="z-keyword">0xe55d1bc51b81c62134e654fd69d9c13dc329454cef1328f1579d034178625187</span></span> <span class="giallo-l"><span>01345,</span><span class="z-keyword">0x18129517d6e589a3e497f93dbad3e63b013dae40ec88ef3e1f3910b655442848</span></span> <span class="giallo-l"><span>01346,</span><span class="z-keyword">0x62600923c76a890ebe7b693e545c5f316a329cc622325ff9159159322ba772f7</span></span> <span class="giallo-l"><span>01347,</span><span class="z-keyword">0xb7bc048ba653fbc6fa6590215174988a56bd0615952242f026700ae0ed9e44d0</span></span> <span class="giallo-l"><span>01348,</span><span class="z-keyword">0x63f08fbe35edc8666cd54f8b313029ccc744b622842266a11085320771a781f5</span></span> <span class="giallo-l"><span>01349,</span><span class="z-keyword">0xd8f90a763e74c5cbcc2f745cd41dfc34742eb9d91665d71b201e8f8d4cdde52a</span></span> <span class="giallo-l"><span>01350,</span><span class="z-keyword">0x3b7ca4efb889b761f25df46f30cb916074f5f80e5bfb4a500896747da243b54a</span></span> <span class="giallo-l"><span>01351,</span><span class="z-keyword">0xa5aeba3be9d1c93c5d8cf0ec419893fc0d2fd193cc9d60b52d2fd7abe6cf4820</span></span> <span class="giallo-l"><span>01352,</span><span class="z-keyword">0x75faba094a42b7e78000daf1ed774e8ed6ecf34bd142470238d1d16741003ae4</span></span> <span class="giallo-l"><span>01353,</span><span class="z-keyword">0x53743d70a74f3b85815f71200d6c3c044df0ffc75fe8dc56a8f9a3ad106d880c</span></span> <span class="giallo-l"><span>01354,</span><span class="z-keyword">0xdcc29cd5c2804269d16f68f212fa4318cd10f686761ba1e012a2bea667d8ed2b</span></span> <span class="giallo-l"><span>01355,</span><span class="z-keyword">0x73301488b070bb8268c358f07b89b07cb19d2ec612edbd30c10c7c83349f0439</span></span> <span class="giallo-l"><span>01356,</span><span class="z-keyword">0xc5358154fa2c30230dcb62a3ae16f03ddd07e3fb9ecb53b0813ba432aeaa6743</span></span> <span class="giallo-l"><span>01357,</span><span class="z-keyword">0x6ae35c6d816695c2e73892ddb5fa55282a108796ddfc1059a60d14ee87ed06ba</span></span> <span class="giallo-l"><span>01358,</span><span class="z-keyword">0x40401985fc52c0c38cc1951a0079728513e34711517fb89e8c8893f889f834a7</span></span> <span class="giallo-l"><span>01359,</span><span class="z-keyword">0x4f6b265815c3a8d1595aeb9e2039c9c73e06a69e746d06d3e4adbd09ade7ddfa</span></span> <span class="giallo-l"><span>01360,</span><span class="z-keyword">0xd0b1559c6907e19eec7b32ccf02f63bfe932f3ec95d28de33250f0e2929b18dc</span></span> <span class="giallo-l"><span>01361,</span><span class="z-keyword">0xef5b459d7ac7c2743f4c0fe6adee0d06a89971dcfb7d959f087b7b57f12c5d1e</span></span> <span class="giallo-l"><span>01362,</span><span class="z-keyword">0x08dfe9e3cf1e444d51c5a61d42a03d90f974513c237d2f9684995f399ce35d56</span></span> <span class="giallo-l"><span>01363,</span><span class="z-keyword">0x80f7dfd0b5347cde3ebd66b78dcb3cf55cfcdbbc019c75e2f69bf9f97e393263</span></span> <span class="giallo-l"><span>01364,</span><span class="z-keyword">0x4b47710e8532de589c562f34bfa75a8333a26937ba10f86d7327afcbf0514cfb</span></span> <span class="giallo-l"><span>01365,</span><span class="z-keyword">0xcc79e6c613537fdc17caef5f69d705741d3ea81e4bb6d277304d243aaae7f3c4</span></span> <span class="giallo-l"><span>01366,</span><span class="z-keyword">0xd76553f60e2e468719e30bd8cbfb967a00cf6841fc520c86d0aaf400db5defc5</span></span> <span class="giallo-l"><span>01367,</span><span class="z-keyword">0xd7efc68f4fdd73317255edf40a2be339ce739e5f0911f447511c763a494160b8</span></span> <span class="giallo-l"><span>01368,</span><span class="z-keyword">0x17ea70afa701eca1af56e1a15f3d1604a3fa7f9f32e8a60b52d41708d15d8020</span></span> <span class="giallo-l"><span>01369,</span><span class="z-keyword">0xf4a498dff013a59d243cfc41a176d2e7584d686d4ae44f6dfdde575d88529fe3</span></span> <span class="giallo-l"><span>01370,</span><span class="z-keyword">0x027e2a2d5bbcb6fd1867eebf440e44ac1f7ded4acd265d97ab1db0e5a1169cfb</span></span> <span class="giallo-l"><span>01371,</span><span class="z-keyword">0xb90ef17e2d9981a11ef0cd0a735c7116d9a233a825903096e2cb07ea8597ef0b</span></span> <span class="giallo-l"><span>01372,</span><span class="z-keyword">0xb47194832a5dc01344496c495b28e1d202ee22841c8ffa1857d05ce0944424cb</span></span> <span class="giallo-l"><span>01373,</span><span class="z-keyword">0xb999269e83d06f6df620c6f5f94964f5a643fbb64dd2c4d7f58eed88798cbd6c</span></span> <span class="giallo-l"><span>01374,</span><span class="z-keyword">0x662f1591b37f2982f426f3003ed9147f96014bb12963e49e63ad1b55e2cd78dc</span></span> <span class="giallo-l"><span>01375,</span><span class="z-keyword">0x108ccbefa9906c080c5115f77f9ecd63381b9ffb0930227cb2630f4b08d8a090</span></span> <span class="giallo-l"><span>01376,</span><span class="z-keyword">0x54d2962953fce8d8a641bb8cd1c9eaafe89f9ac9546b8b277d9b535fb35a0097</span></span> <span class="giallo-l"><span>01377,</span><span class="z-keyword">0x6d7bcae503db8d3f3771cf9e8038a1fdf3987beb6212755704560a0404118063</span></span> <span class="giallo-l"><span>01378,</span><span class="z-keyword">0xfd477f0bf18d87a2bd3ae3c329e468a7bb16a363ec3fbf658f55ecb98fc16d17</span></span> <span class="giallo-l"><span>01379,</span><span class="z-keyword">0x57b72b9a11da9b25c2bb52b648db7870e039a64439fd271fa320bd2fe789775b</span></span> <span class="giallo-l"><span>01380,</span><span class="z-keyword">0xbeacd779ff788ab12f79382ea205b1b180c7e43302e902c32fa577c0925144ce</span></span> <span class="giallo-l"><span>01381,</span><span class="z-keyword">0x4b6c00275a131aa994d1e86e9246196299930ad5fc218d09d0b66265234e32c6</span></span> <span class="giallo-l"><span>01382,</span><span class="z-keyword">0x485b0ed3728e693a618ca77659c55114a8f602ccd71fa6138e87e11b49814289</span></span> <span class="giallo-l"><span>01383,</span><span class="z-keyword">0x402cc664b8b4b8dcac9aeba636f3c902a713874d9fc6bd6c7dc338817c1eac76</span></span> <span class="giallo-l"><span>01384,</span><span class="z-keyword">0x547da0f4446ebbba63eba970ec761c7a08451eb11251c91cd6427cdf475bf00c</span></span> <span class="giallo-l"><span>01385,</span><span class="z-keyword">0x058c55b0a6a077ed8882d135e4cb364b250d392eba6ad4e578fe910c8c9f340d</span></span> <span class="giallo-l"><span>01386,</span><span class="z-keyword">0x951ddf6cc9c8cae358c63a8a8b5037a970cc5a3e9ad55fca7e4c85bf86c935a9</span></span> <span class="giallo-l"><span>01387,</span><span class="z-keyword">0x85a7797dd4dae08cae7218cc8c2497b580ad037427bf7e351f20f1edfd695d57</span></span> <span class="giallo-l"><span>01388,</span><span class="z-keyword">0x64376e672282c2691f4dd0a88ccdb12d561cd88612d689f2802744490e275e10</span></span> <span class="giallo-l"><span>01389,</span><span class="z-keyword">0x58445b6bcd79648c107c45ccfa2c2246b0bffbfc0c9c8750b934894144105f87</span></span> <span class="giallo-l"><span>01390,</span><span class="z-keyword">0x6a2d6ce478b520818b85e08d1beb56fb4d6d656aef8f26020cc9a1781a4cd96d</span></span> <span class="giallo-l"><span>01391,</span><span class="z-keyword">0x330e88ac3fd46d3b66946b2bd2e342e0906769ba42be06f01ed224dc7ae90640</span></span> <span class="giallo-l"><span>01392,</span><span class="z-keyword">0x3bf42cf0cd0e8199fffa9b453dea46a65409ec5430638e189e8f60132fbd19b0</span></span> <span class="giallo-l"><span>01393,</span><span class="z-keyword">0x239fa3d0c11c26d29efac03c04735050e83c55686975a8753bbbc83349316a48</span></span> <span class="giallo-l"><span>01394,</span><span class="z-keyword">0x76707dbf2c1a10e6f1aaa37be9374185d3eaa2253594e5ff3482e436841e6b50</span></span> <span class="giallo-l"><span>01395,</span><span class="z-keyword">0x4bcaea6c1d0723bab48d33acf6e6bcbb6016c405f710f19e8542290568510ec4</span></span> <span class="giallo-l"><span>01396,</span><span class="z-keyword">0xcc5b5c9a71d2e0b16153477cdb827aaf6feb3f0758218dccddebcf0e0f0bfb1b</span></span> <span class="giallo-l"><span>01397,</span><span class="z-keyword">0xce3fa54e8a5338bf4a395b0d522e35d60b473c9f8507d6def5dd7da739aa5317</span></span> <span class="giallo-l"><span>01398,</span><span class="z-keyword">0xd06c9a048e07da77ad07dfd45f48cdcab8eac2cd6ab44fe9db7778498d1200ac</span></span> <span class="giallo-l"><span>01399,</span><span class="z-keyword">0xe131599e0fa8cb136a8425b02becb4d42888bde686d9d88b6248216a583dbc87</span></span> <span class="giallo-l"><span>01400,</span><span class="z-keyword">0x1a628757bb1610b0c239ae56df58324c7cf5b5f3f18bbccea4dd67b1ff9be9a7</span></span> <span class="giallo-l"><span>01401,</span><span class="z-keyword">0xe7d4a88015acd605be12a616c899590059d306c69aff9a1876d47c276ea96231</span></span> <span class="giallo-l"><span>01402,</span><span class="z-keyword">0x85d3f3038ba81ba3c5c5a86cec0e55ecd3865f4bcb2e7bd9fb8390e06278ea2d</span></span> <span class="giallo-l"><span>01403,</span><span class="z-keyword">0xe1e41aa6c6d1cc5313c8f2a0ba5c50098c30f49b4a8ba5ea8d89e334be0ffd96</span></span> <span class="giallo-l"><span>01404,</span><span class="z-keyword">0xeba27a233d1a0b76360d1ec6793544482a197f01a47d29474b64982d043c9807</span></span> <span class="giallo-l"><span>01405,</span><span class="z-keyword">0xb0ddf49dcc80359d5bbbd56b5a1e53a8fa78fbb3563c806f1a8a91b51cc8d082</span></span> <span class="giallo-l"><span>01406,</span><span class="z-keyword">0x651ac24a55b66ed30dc6b260af6a9b6aff2c1e0e8433534a353d2b9463d650ee</span></span> <span class="giallo-l"><span>01407,</span><span class="z-keyword">0xa76ac2e092a5e5db97ef6af6656dff4aa47fbf036bfb5ca2dea8fe0dea9635e1</span></span> <span class="giallo-l"><span>01408,</span><span class="z-keyword">0x209624ba6ce8936b8a37223a76d35394b8a3e1c55f0e23dadd60da82e867fc81</span></span> <span class="giallo-l"><span>01409,</span><span class="z-keyword">0xaf729a25d80ddd3c0688e76207ff9ee0ef4960a696061fc1e32c39e69b40289a</span></span> <span class="giallo-l"><span>01410,</span><span class="z-keyword">0xa53b25ca9678e87be1fcef929c93d97ac456308f8405be0910fc8e917f264042</span></span> <span class="giallo-l"><span>01411,</span><span class="z-keyword">0x00cba9ae4ebb3a6e3876f16c22db9914e07a4a175b582fdeefbb60001dae465d</span></span> <span class="giallo-l"><span>01412,</span><span class="z-keyword">0xda3d50bfc90ee547701ab1777f4cc626aae0183fe5d1f42df31048ea85c2a626</span></span> <span class="giallo-l"><span>01413,</span><span class="z-keyword">0xfe77f727e1f01d1287955db0e75a11f8f1077ebe78a7c96ecaf808e22009fa9e</span></span> <span class="giallo-l"><span>01414,</span><span class="z-keyword">0x1053d23c71dc7e09a2250926009b353ea3f44a599953e347de0fd8347d677762</span></span> <span class="giallo-l"><span>01415,</span><span class="z-keyword">0x1f9ee40833afefffc10bd0f240252f1fc70ebd6bd9fe7894816a369f78f40940</span></span> <span class="giallo-l"><span>01416,</span><span class="z-keyword">0x162769df545470c247d848320910bb169a9c95859e676d531bcae4ff4eaac292</span></span> <span class="giallo-l"><span>01417,</span><span class="z-keyword">0x6904f50508e80bc3f8fd40550fb06c98df9da1f1fce47c95e81e47a030917002</span></span> <span class="giallo-l"><span>01418,</span><span class="z-keyword">0x668379548128b70fe1b31b174c6daa8a0915557d1769beb2bcfab9f95884baaa</span></span> <span class="giallo-l"><span>01419,</span><span class="z-keyword">0x55bb8c9a8b55e224e139cd6f93893700ac261f27a2eab8f2d493d734366d1749</span></span> <span class="giallo-l"><span>01420,</span><span class="z-keyword">0x37cb2c92be70871a49bcea2f3d90a6215a72609ef728c8e46922cbd6737c2c86</span></span> <span class="giallo-l"><span>01421,</span><span class="z-keyword">0x05b6cf1bb6f912a9a46dd729ba1ea392e517ad277bb69b758dc88ffb08313288</span></span> <span class="giallo-l"><span>01422,</span><span class="z-keyword">0xcf2496163a204528e56831eb7cad31b71b85aee9c8d584270c9728154e6a0bd1</span></span> <span class="giallo-l"><span>01423,</span><span class="z-keyword">0x8500cec01a3af6600559bd3f68e2607eeacf62fc773fe4ea467c0592c9cf650f</span></span> <span class="giallo-l"><span>01424,</span><span class="z-keyword">0xf9b23ca9378f773d6ce3ab66eee7f70e84b52cb82be13876d2cb7073dfc765c6</span></span> <span class="giallo-l"><span>01425,</span><span class="z-keyword">0x2e9e77d2e086db1a3b04a73d17cc79247012b93c4aead1462d688857c983b16c</span></span> <span class="giallo-l"><span>01426,</span><span class="z-keyword">0x8c07100577d5a565f3962df52798a8e7c74eded7237c57b6287308e30693fc31</span></span> <span class="giallo-l"><span>01427,</span><span class="z-keyword">0x53b8caf6ce7524bd3161dabdee75a7948cb6813045b9422f0243b91d1a8046d5</span></span> <span class="giallo-l"><span>01428,</span><span class="z-keyword">0x68be6c9f0b492c78b2598baf1e5a8d8c45a7738d41afd795fc57a6b9e5acf34c</span></span> <span class="giallo-l"><span>01429,</span><span class="z-keyword">0x12a34f393f9f0f3e7630b128ba992bcb8bd211f817a4e14869d78cf465aebfcc</span></span> <span class="giallo-l"><span>01430,</span><span class="z-keyword">0xff0a7be97f4019b220ec1afd81839cc10dc9c9d897a7131fc805393f82f998e8</span></span> <span class="giallo-l"><span>01431,</span><span class="z-keyword">0x64d4fc5bc06327b48928cfcfa93581a8f840c950551365ab35029583fed9b421</span></span> <span class="giallo-l"><span>01432,</span><span class="z-keyword">0x2205cdfc0fa6fd60df16cad0281d1321bb0727e0d9dda4e5695a415f8b0d25bc</span></span> <span class="giallo-l"><span>01433,</span><span class="z-keyword">0xe4ccf7437255286798c6e3c8181f1d4981ea17ba6560bd9e25a86a4a558ec60c</span></span> <span class="giallo-l"><span>01434,</span><span class="z-keyword">0x7720205861646892f7d4f654cbfb82e1efed9fa75fa779614a2d7f71a6a3546d</span></span> <span class="giallo-l"><span>01435,</span><span class="z-keyword">0x467addf009150a231cbf58b439c8ee6859807d2cc444b5391288e84b73437e78</span></span> <span class="giallo-l"><span>01436,</span><span class="z-keyword">0x8bd916a854e374573059266dd6eccc83a260c544a246cd8df022c12864d00a4a</span></span> <span class="giallo-l"><span>01437,</span><span class="z-keyword">0x332b343d821178fd9f67670662e7d60926135fbc724ac83e15f76ac77fada151</span></span> <span class="giallo-l"><span>01438,</span><span class="z-keyword">0x595d9cbeefcaf6ef0d0ca2e5b5e221777f7fb99a07f07f398759960a16ffedc4</span></span> <span class="giallo-l"><span>01439,</span><span class="z-keyword">0xaed3cc6afce54a6dd6c0b6a68532d860d99ad64abb3550594166f2a5d1086b58</span></span> <span class="giallo-l"><span>01440,</span><span class="z-keyword">0x41f0520f9167d87677b563d4652b1929a1cc45d49f59803bf30d288a1be2b06d</span></span> <span class="giallo-l"><span>01441,</span><span class="z-keyword">0xe2a38fbc4c762ce28ad95fcd0b38b461fc43cf005e1c0efaa1a95e8b08496fd1</span></span> <span class="giallo-l"><span>01442,</span><span class="z-keyword">0xef37dd9b1d91abce595f8e07f4b8200ff75af7d59811d7c222ddd0dcd5657b8b</span></span> <span class="giallo-l"><span>01443,</span><span class="z-keyword">0x145a661e91fd5f7e7004a06124642067355ac94d3812c17dd7e28ab63e2b3bef</span></span> <span class="giallo-l"><span>01444,</span><span class="z-keyword">0x9821beb8f5dcea100a98816920637fc5644bb4aae4d43e14056546177db2d2ff</span></span> <span class="giallo-l"><span>01445,</span><span class="z-keyword">0x728597bdf315ebb1b2ab95a2cc6bf7b4b4740e6e6cb73be78c0827c9791d614b</span></span> <span class="giallo-l"><span>01446,</span><span class="z-keyword">0x5ad80991f59ab3c3f5d9e4b0a64a0d1622a6f7201e6b4c9ab17425ef0e9c6328</span></span> <span class="giallo-l"><span>01447,</span><span class="z-keyword">0x6b884caccbb53424351a0707fd38ec1780332432704f637261d061ce81669fb0</span></span> <span class="giallo-l"><span>01448,</span><span class="z-keyword">0x869cb3c70c4fbab00ea39f9b8954bd0efc32ff9386d347d7731b482ea2fa1035</span></span> <span class="giallo-l"><span>01449,</span><span class="z-keyword">0x5cac1bcb33f6344780d0ae7effa537b4597e788655c7f0ca76f6427ee6951593</span></span> <span class="giallo-l"><span>01450,</span><span class="z-keyword">0xb92784114f94f68de5bc7ea7ff301e8123ad1ae21211d9fb843a809198f34732</span></span> <span class="giallo-l"><span>01451,</span><span class="z-keyword">0x32f5e0e5826dcafa56e2102e122b65f91f47edbe4fd164774c5db7b3163d749f</span></span> <span class="giallo-l"><span>01452,</span><span class="z-keyword">0xb43138d20c9f3a4ad12f1c6a14975528e934c45e0821fbbf924bd0e97c7ce091</span></span> <span class="giallo-l"><span>01453,</span><span class="z-keyword">0x34bcded8fb20b97fb638a8f0b0b88da53ee9e9ab8e31c2ffcecd7cd172532e20</span></span> <span class="giallo-l"><span>01454,</span><span class="z-keyword">0x11f80fd32648f792ece5e55a241f473f2733f6b2801df8be9679896d18947871</span></span> <span class="giallo-l"><span>01455,</span><span class="z-keyword">0x18ea77d047b2a9fb5aabac87543ec56952c28aac11ecee3af95a4aa559bfed49</span></span> <span class="giallo-l"><span>01456,</span><span class="z-keyword">0xf1aadb7cf016bd145d3abaaf1a285545e331a9878f8291692df22fa7ceb34ec6</span></span> <span class="giallo-l"><span>01457,</span><span class="z-keyword">0xd00e9e6ffbb61a46cb574900034b3ee2e8ab614b1182d29fb228603016385094</span></span> <span class="giallo-l"><span>01458,</span><span class="z-keyword">0x7ffab11d609947e556ac0f0aa0e92c8d1b7daae7c691e159e31bc2de3090e2d0</span></span> <span class="giallo-l"><span>01459,</span><span class="z-keyword">0x6039b280fddd6ba4e398335bf0fabb83cd421c12d6a18f18b9f60249e3456e65</span></span> <span class="giallo-l"><span>01460,</span><span class="z-keyword">0x8e889e14bc66328b31238cec0e5ca5de362bf8d995519de91c4c14a4f6dfd6db</span></span> <span class="giallo-l"><span>01461,</span><span class="z-keyword">0x773c0e114f7bb0a7cdca0a604b930a3c77b35d4033a7eebaa8d380121a2441f9</span></span> <span class="giallo-l"><span>01462,</span><span class="z-keyword">0xdf1babfea1ab0a8d9ae94988ffd97916576340ee9f76a697b4d783074a15cba8</span></span> <span class="giallo-l"><span>01463,</span><span class="z-keyword">0x6d328022fe6152777777c85775f267864398abdd880baa956659469fee4c22ec</span></span> <span class="giallo-l"><span>01464,</span><span class="z-keyword">0x1c7eb43c12aa64d6dbebe5f9946254cb7d4960e919112034b25cd78ba4c7fbf4</span></span> <span class="giallo-l"><span>01465,</span><span class="z-keyword">0x10ffef9e33b607326adbb5aabb35e832952a99fca4662af142510332b9033a16</span></span> <span class="giallo-l"><span>01466,</span><span class="z-keyword">0x7785bbd4cc92a53101de632d4335e09d7e3a7f8b8a2e5263d884c2e02f3541df</span></span> <span class="giallo-l"><span>01467,</span><span class="z-keyword">0xb09a9b8e7e62a4ec64bef12e9b6467b0f7276db516b270cfee9b8f30b59e9349</span></span> <span class="giallo-l"><span>01468,</span><span class="z-keyword">0x1919baf88fb35ea864c6e86c74db4a93ba81d8c573d53716fe6cb56804bb4c8d</span></span> <span class="giallo-l"><span>01469,</span><span class="z-keyword">0x6338bf7f5a36a7559ab4b7abf0b3882c81aa369425bcf4718ac690d237d6e53d</span></span> <span class="giallo-l"><span>01470,</span><span class="z-keyword">0x46fb7a9b26b5de93dfe8027aef0949cc8f81c523fcf3e578e6ac296acd396296</span></span> <span class="giallo-l"><span>01471,</span><span class="z-keyword">0x18fb7c8f934ec0bd79726a6dbcf9b1949eae47eb8e8a59fc60821d374e5cad5b</span></span> <span class="giallo-l"><span>01472,</span><span class="z-keyword">0x47a32b9d02c3f8fe8780885803d922d76e5ba346335f99c8b46bff9d33530a57</span></span> <span class="giallo-l"><span>01473,</span><span class="z-keyword">0x333b7e8665b4aa205cc4136efce2add43fb3803b43a7f33e9386790b0846dab2</span></span> <span class="giallo-l"><span>01474,</span><span class="z-keyword">0xfe24e3c1483ac948bb8e3ec3ace550f72726f2025abaf97dbee5997a2d7798f0</span></span> <span class="giallo-l"><span>01475,</span><span class="z-keyword">0x81c78370e6f8e1054f5492a086f354fdbbdee13fc5eb433d5b70f6bde808feea</span></span> <span class="giallo-l"><span>01476,</span><span class="z-keyword">0x857187a16d206dcf5ab6d0f375defe4689f638952e7be7e214a18ef95f612588</span></span> <span class="giallo-l"><span>01477,</span><span class="z-keyword">0xad00e0b4f49ca226ba794de114b83f21049c9678d956ecd0a9456509a4d33b65</span></span> <span class="giallo-l"><span>01478,</span><span class="z-keyword">0x8994eaa1d20c7865333115069f8f9b5d500b0ac5b77759a7938c4a9817e8a864</span></span> <span class="giallo-l"><span>01479,</span><span class="z-keyword">0xcf4abf0e245ee8096e0a34974636acedc772135d2f99a493e78e84171c30d4fe</span></span> <span class="giallo-l"><span>01480,</span><span class="z-keyword">0xae5f5367ea0f5fcae4b0cb50813b16611d4348211979e922c039849237dc7e0b</span></span> <span class="giallo-l"><span>01481,</span><span class="z-keyword">0xa121c10e9e5b9ebfd54ddf768c22b1f9a0d99b1d002f0c14133b9069271a577d</span></span> <span class="giallo-l"><span>01482,</span><span class="z-keyword">0x2110d171195a2de44d08df4b38a9ec39242e74e177a9a330137d2cfad24f0e6e</span></span> <span class="giallo-l"><span>01483,</span><span class="z-keyword">0x56ec2844150d5baf181784999e0f12eedab61b6d106be33e2e5f4ae7cd9923c7</span></span> <span class="giallo-l"><span>01484,</span><span class="z-keyword">0xba8ad4f1b96b86c81781dcd63aea4d8c817762f8950ad31b7b516ec86dbf9c56</span></span> <span class="giallo-l"><span>01485,</span><span class="z-keyword">0xc56c3ef61383b31fe0426d4e7e6101b3ee93e36f8743513d6f2827f6dc7443e2</span></span> <span class="giallo-l"><span>01486,</span><span class="z-keyword">0x57bc41042e73f44a9ffe5ad0ef0ed6a750b254d6174182d31210ec154bd5a6a2</span></span> <span class="giallo-l"><span>01487,</span><span class="z-keyword">0x122d8e0fb38045e75447d5d4b098ded50d3519ab133f407f16ce80b7811f59f9</span></span> <span class="giallo-l"><span>01488,</span><span class="z-keyword">0x42b25fd38e95b67a02cf2d2420f3baf74baf05cd3daa21c7d8422dd4ef082073</span></span> <span class="giallo-l"><span>01489,</span><span class="z-keyword">0xb1acea4e751f8ab84a1701a3810b7425d7bd25b9a11191b8439d9ef021a0ae99</span></span> <span class="giallo-l"><span>01490,</span><span class="z-keyword">0x34280f11add3d4fbc26f35a2bc3163e20bd68b0b2c5f5c977b3c5515f7f89c78</span></span> <span class="giallo-l"><span>01491,</span><span class="z-keyword">0x503bfdfdf60af3f68c00940ce18790b5a4b27708860b9397c247b65ea306f9ac</span></span> <span class="giallo-l"><span>01492,</span><span class="z-keyword">0x1b74997d1c74b3925d68bfb59f89532c82f8d40442462a20b8f8a247223217ee</span></span> <span class="giallo-l"><span>01493,</span><span class="z-keyword">0xedfb26fba9e0f118447e4f1a2f427cbfe9b42bf74c74c8c347718c2bb25de638</span></span> <span class="giallo-l"><span>01494,</span><span class="z-keyword">0xda405d1305cbe42530cf2a03f23706e2c2f0d5c4a8e3fe402026ac7cb9e00c7f</span></span> <span class="giallo-l"><span>01495,</span><span class="z-keyword">0x3efe0cdadae9231c400665a65dee22fccf36020f991fbc5fc80a692a15e04100</span></span> <span class="giallo-l"><span>01496,</span><span class="z-keyword">0x809b00b05e0da5745ec980caa06cd88004cd61873bee830f9da8d9cee061c0ce</span></span> <span class="giallo-l"><span>01497,</span><span class="z-keyword">0xc6923521f989fdf033fef5f95561230bf2bc872c3be7088a3a0986f40417cbc2</span></span> <span class="giallo-l"><span>01498,</span><span class="z-keyword">0x2ef9dbc94aeec86917f3545afcf139cb1092ae35566cb03667d71fa7b4a413e6</span></span> <span class="giallo-l"><span>01499,</span><span class="z-keyword">0x23a65ef9fa71a5631cb9be2f1108a6ae5a52fd9123102d43b167267c5c0b6d86</span></span> <span class="giallo-l"><span>01500,</span><span class="z-keyword">0x17e97c499981088f01ee7fd4110bc4e39552c70c535b2c01bfb825288c652cd1</span></span> <span class="giallo-l"><span>01501,</span><span class="z-keyword">0x38815f395760557cb4ceaf43f9bd59d7f3ae3438d98e2e8e89a1a985d77def48</span></span> <span class="giallo-l"><span>01502,</span><span class="z-keyword">0xc31ef6bf0361e3147b5cfa201a4296245cb801a4933e6e3c7c4040789fe39ebc</span></span> <span class="giallo-l"><span>01503,</span><span class="z-keyword">0xc5393ba2406bc0b84edc863f36c63116e6f3ce5b3af9063cda7516ed664feddf</span></span> <span class="giallo-l"><span>01504,</span><span class="z-keyword">0xb478f53b462aecc80018fc12f270409c9c21616d076a98f26dbb6bc76171fc03</span></span> <span class="giallo-l"><span>01505,</span><span class="z-keyword">0xb8013f87cc39daaafdcd88f6338920b22c471bf7d7b589963a6ada06bfaea470</span></span> <span class="giallo-l"><span>01506,</span><span class="z-keyword">0xf23ee99501bb670f523caf0761c956324dc590fed811bc4f6471b6c458805e5f</span></span> <span class="giallo-l"><span>01507,</span><span class="z-keyword">0x21b534cf9c9af1ea839aad996558e17bf8698d1c0b6d1ccdb858fb19bf78fdc9</span></span> <span class="giallo-l"><span>01508,</span><span class="z-keyword">0x9fbff7e7dce3188b5c5503deaa65b47c43c304c52f3f1f4fa5e8221759c75330</span></span> <span class="giallo-l"><span>01509,</span><span class="z-keyword">0xe5141a21f39698a7b78ffce400c185d65fc6145c08b97e5630b16fef5cfea317</span></span> <span class="giallo-l"><span>01510,</span><span class="z-keyword">0x87aec91b6b6a9b92dba7163b403a463f001693df580b79d1b630413de7c62540</span></span> <span class="giallo-l"><span>01511,</span><span class="z-keyword">0xb041bb19cce32e94aba5ab72f8b325fe14088e933331cb81c090dd64628e3276</span></span> <span class="giallo-l"><span>01512,</span><span class="z-keyword">0xe41b5ac2f66221e3e7486d2513c67051afc5530af04715e37c144c198240eb5e</span></span> <span class="giallo-l"><span>01513,</span><span class="z-keyword">0x56a669268cf40b4111afe73a823da07e8a09f6304f8ab890b4645d2dfd7cbb24</span></span> <span class="giallo-l"><span>01514,</span><span class="z-keyword">0x898d4f37bcd23ab1762aec11fd937e9b9843e74b3aa9c0b4ed5645b03fcbaf98</span></span> <span class="giallo-l"><span>01515,</span><span class="z-keyword">0x935b5d7aeec407a6cd83f7d0dc160edc53cc8b7f5f2e019c05fe619226a5b67a</span></span> <span class="giallo-l"><span>01516,</span><span class="z-keyword">0x4ad5c3e371e953f644173a234e019d8e14993f21100068a439bc901b164b0713</span></span> <span class="giallo-l"><span>01517,</span><span class="z-keyword">0xbe94d5d09346e617ac54ff3494a7923b43d7ea91d61fdfa4a1185af83e73fee0</span></span> <span class="giallo-l"><span>01518,</span><span class="z-keyword">0x40fa62d3a1d198625a85eb1afaea58c9644194914293db1246869aa4b7fcf547</span></span> <span class="giallo-l"><span>01519,</span><span class="z-keyword">0x110e8af3acb590972a4f633434221317d3ac98b9fba73452c02e9a88e9de32f2</span></span> <span class="giallo-l"><span>01520,</span><span class="z-keyword">0x6e412e20bae396e80928f28ec0179a1be7765947bd7e4765fe3b20524f60f2ca</span></span> <span class="giallo-l"><span>01521,</span><span class="z-keyword">0x8ffe28ad29fdd6e42ccae7faf81b1715fd4df21451ddeb305a3eead7a514a17c</span></span> <span class="giallo-l"><span>01522,</span><span class="z-keyword">0xe93cd0a078a29332cbd05e1570a988ad748db4a2b2f2dbc2c6bbab0bd3c8302b</span></span> <span class="giallo-l"><span>01523,</span><span class="z-keyword">0x77f19add028523159fac380f499a2193f29ffde2ae2eb043719b798e272d2b3b</span></span> <span class="giallo-l"><span>01524,</span><span class="z-keyword">0xf583c72783c0c5b90ab3a01c84eaf9ef04620259b4c1ccf074c9e74a22c98460</span></span> <span class="giallo-l"><span>01525,</span><span class="z-keyword">0x326bed4654c8a2f1bf96d345ef7ac8eb3868861e561603b5dc50c8f623cf6333</span></span> <span class="giallo-l"><span>01526,</span><span class="z-keyword">0x558f5bae98e6ad2e383096f2c381c126bdccfaa0c90cbbffb7480426f5803396</span></span> <span class="giallo-l"><span>01527,</span><span class="z-keyword">0x17af0f4e322b322401ff5f1c360a93aa4c14babc71203e78a3f9df4cf56f8f02</span></span> <span class="giallo-l"><span>01528,</span><span class="z-keyword">0xb3d28e9ba92278e4be3110b7813b95e05243fb026f3442e6961e686576399e5f</span></span> <span class="giallo-l"><span>01529,</span><span class="z-keyword">0x6ce3df5c684e6d291db88d672af9848f1c597d58ad4aeb154d7d812d69878e22</span></span> <span class="giallo-l"><span>01530,</span><span class="z-keyword">0x70b295e43e231b6edfb2ba45b14964ca609d06e596f65438c816a8919a141d38</span></span> <span class="giallo-l"><span>01531,</span><span class="z-keyword">0x5694754d0ac3a99b57cfa34aa9a6f37d7749675127deb9dd45d920a767104724</span></span> <span class="giallo-l"><span>01532,</span><span class="z-keyword">0xb7d62fb8035796a876d44ec6b484ecafb225782c12885d4cbd8768bfcc8648c5</span></span> <span class="giallo-l"><span>01533,</span><span class="z-keyword">0x1c4ea22b6b5b40c697b2048c59cec06701c032ef4fc245402d68ab614ef4749f</span></span> <span class="giallo-l"><span>01534,</span><span class="z-keyword">0x3f50bd7f0574c667cf8d6e4d96e8375e845f1bb58b5458a96fa4f13400978139</span></span> <span class="giallo-l"><span>01535,</span><span class="z-keyword">0x56e96bf3a208e13326e3ae64501a9f8aa2a2306551a22729f4cdc632a316dc37</span></span> <span class="giallo-l"><span>01536,</span><span class="z-keyword">0x4c0b5a25c4a9f692cb2d1d97cc2ed3a9c6be0263543702df9cfa818e67792ad1</span></span> <span class="giallo-l"><span>01537,</span><span class="z-keyword">0xb84376f6b504ac6eee8eb390c9431dce6d21ba91bf66860488b267e140503df9</span></span> <span class="giallo-l"><span>01538,</span><span class="z-keyword">0xa859e797a3880fcd290e20193e80d4cd6aac09cbe285520972863a0496ba9e5e</span></span> <span class="giallo-l"><span>01539,</span><span class="z-keyword">0xb8f7332814753428b30912ab8eca0e635d4060a7ef66fecc91b9963f0d2a9b5b</span></span> <span class="giallo-l"><span>01540,</span><span class="z-keyword">0x5075b4c47e8e56e7f17022c6c00170a30cdd7cf257d893dd917b6ae8725ef044</span></span> <span class="giallo-l"><span>01541,</span><span class="z-keyword">0xd9a68897ad38b7a6b7948e66b75312956c32f2d8e2b27fdf3df27bb1e523587c</span></span> <span class="giallo-l"><span>01542,</span><span class="z-keyword">0x4c44c323f56a00e42c55f8e08134019f4cfa635e945aab057be327146e41b193</span></span> <span class="giallo-l"><span>01543,</span><span class="z-keyword">0xba0d8406b4b7bdb1f2a3c8bf6cc79c49d1a1ecb99e9a289ac2febb3f062a31db</span></span> <span class="giallo-l"><span>01544,</span><span class="z-keyword">0xb730d9fb4712957266c8134e8ad45e064e9dde91be74a4bdba289dd2c1cd3b7f</span></span> <span class="giallo-l"><span>01545,</span><span class="z-keyword">0x2a36dd0adc9b0a8ed517b92ef73ee18072f2ad87d992eac9b163ed13701c2d40</span></span> <span class="giallo-l"><span>01546,</span><span class="z-keyword">0xcb6390d20de04adf9ca127b68f73fbbdde1ae451d3d5dd2e9deebed712c49122</span></span> <span class="giallo-l"><span>01547,</span><span class="z-keyword">0x7be294479d6f126c3da2e73d6ae008ba912d377135e43eefcc6ca65e4e2d9770</span></span> <span class="giallo-l"><span>01548,</span><span class="z-keyword">0xd42b2e596c43feb99b1a292cb65108e4d159699ce5399331ceedd101b37e8aa3</span></span> <span class="giallo-l"><span>01549,</span><span class="z-keyword">0x3259acc6ebca1ee7695b4748c89145bfb0962571f616b5e2da44ac571746369f</span></span> <span class="giallo-l"><span>01550,</span><span class="z-keyword">0x15c4efe66e352107540d4c8ce5d800c117a599da83ad34388cd17510682942bf</span></span> <span class="giallo-l"><span>01551,</span><span class="z-keyword">0x2d99a1dc1815eff9f0d697fb3c79a078645b573ad228ebe569384ec8f747fc98</span></span> <span class="giallo-l"><span>01552,</span><span class="z-keyword">0xccd34c1ecb8f3444c21ad2f645b5909fe2c44e9f282706205f45c102d68bd3b8</span></span> <span class="giallo-l"><span>01553,</span><span class="z-keyword">0x0f3371da1271d47e61ed8a04772fd68751b8c7ef16c316b8f4b1491449354a47</span></span> <span class="giallo-l"><span>01554,</span><span class="z-keyword">0x6acbe79cf6301c23a1202198de9abad6c1cf67718f48928176459a2e195839a3</span></span> <span class="giallo-l"><span>01555,</span><span class="z-keyword">0x975db585f0f663c6e62d41199c823b48e1be2f596effa9c56222d3b7fdd48d40</span></span> <span class="giallo-l"><span>01556,</span><span class="z-keyword">0xf8d968d981abe306802686c870f2d6071547604228bc7c8a9e26600cc13fc18f</span></span> <span class="giallo-l"><span>01557,</span><span class="z-keyword">0x5250d82f1f9476a10e99a6b6c8d4664c52d206286eb62e544c4d93b6c8141608</span></span> <span class="giallo-l"><span>01558,</span><span class="z-keyword">0x8817dc1dc6343f42591204b1036b8e8b9ac90aa6be40647b3c13fc48256b865f</span></span> <span class="giallo-l"><span>01559,</span><span class="z-keyword">0x16cbfdacbf89ab417c81734171a541d1ebf55b17e4d62474a9883f9aa3b9d992</span></span> <span class="giallo-l"><span>01560,</span><span class="z-keyword">0xcbaf55ad5cf0f88bfa5be589394b6a7ae0907116fdee9b447b4110ad76356049</span></span> <span class="giallo-l"><span>01561,</span><span class="z-keyword">0xa12fc593dbc327d7a61fa0e695f2e6bbd10b70ae3dd87d32802487380d67334e</span></span> <span class="giallo-l"><span>01562,</span><span class="z-keyword">0x310c6496b06f98c1553f27b9ef878db3e6b540a4008fb4de7d65cbb7b431f324</span></span> <span class="giallo-l"><span>01563,</span><span class="z-keyword">0x5345e3d4fb9fb5cfc1e3ab07b7963c5185b3758583fce54826b59c8f59fc2bb9</span></span> <span class="giallo-l"><span>01564,</span><span class="z-keyword">0x2280e4c1f8c9444f8a85a63a744b4d9cdaaaeec6c27a100b704c36ba1b27607a</span></span> <span class="giallo-l"><span>01565,</span><span class="z-keyword">0x893942f1ae02af922386a011d94aea458b000e6ae58ac5105469f15ef5ccb00b</span></span> <span class="giallo-l"><span>01566,</span><span class="z-keyword">0x237ef759964133b24b7d50fb860d3ef49f5b5473a5dfbb4deb12a9ee75e9d3c4</span></span> <span class="giallo-l"><span>01567,</span><span class="z-keyword">0x1aec3b6ed606a370df07ff07933d708e4b30892c5b34eb27a3c179089ff70c24</span></span> <span class="giallo-l"><span>01568,</span><span class="z-keyword">0xfc92fcf640f5c001fe4c37de77755ff442f5753d9500aba5636cad6cef432cba</span></span> <span class="giallo-l"><span>01569,</span><span class="z-keyword">0xeacd9d2bc6090407814082b59e363afa47cb9148ffa584c065136e11c62413e9</span></span> <span class="giallo-l"><span>01570,</span><span class="z-keyword">0xa22bf28892d91ec239139c3c7bb07a32887d7d42f9a097ee919e8f1333abe8be</span></span> <span class="giallo-l"><span>01571,</span><span class="z-keyword">0x1a439d0701e901619bf55f220dd81ad945b75883f0832eb9d1ffad360225825f</span></span> <span class="giallo-l"><span>01572,</span><span class="z-keyword">0x947ddced110265caee947bc7d343bafd17bafff910a68db5bcc0f46f0aee6fc7</span></span> <span class="giallo-l"><span>01573,</span><span class="z-keyword">0x3a831bed82ec33cfb63e2489ca28d1dabcab3326a310e117ed3ff4d91893ad5e</span></span> <span class="giallo-l"><span>01574,</span><span class="z-keyword">0x9028d18bb6a6f17c7d25c2c76c6faf7a9df0913107ee429b1cfa9e865cf3118a</span></span> <span class="giallo-l"><span>01575,</span><span class="z-keyword">0x598f030e236f72cf6eff6d43fb7f974f911b9fc603980b37f15614ec3cd779c5</span></span> <span class="giallo-l"><span>01576,</span><span class="z-keyword">0xf904329742dc4ffc14c96a9917c54d18a6fde0cb98c47d211e7f7ffb83956ae4</span></span> <span class="giallo-l"><span>01577,</span><span class="z-keyword">0x8a587dfcf7eaa992e28ff6c3504df916cd4e01fe66fd293129ae957fb4426425</span></span> <span class="giallo-l"><span>01578,</span><span class="z-keyword">0x43c1dcc3d038599b653d4863c7c9bb7cad97e7b7961695e8956e9bd42f2dc0b2</span></span> <span class="giallo-l"><span>01579,</span><span class="z-keyword">0x92a983f23849ce276e11172312cf40a7aee0e9bd34c92f66f95a2b55ea9f3cba</span></span> <span class="giallo-l"><span>01580,</span><span class="z-keyword">0x1c243107c6f0b4ef1b64cb91a8d1abe0dff736faf40a28e01448477799d7223b</span></span> <span class="giallo-l"><span>01581,</span><span class="z-keyword">0x1f943824eeb9f6e597dd06662f22d72c259fe15ca30f79f85108fce6f9465c80</span></span> <span class="giallo-l"><span>01582,</span><span class="z-keyword">0xde1cad895c807ccbc04c98614864decb0b4f438b79772508210e542de31a80d6</span></span> <span class="giallo-l"><span>01583,</span><span class="z-keyword">0x2d72b6e45e90548bead586dbbe36d30832196b923fc15981b7a75b4635835cad</span></span> <span class="giallo-l"><span>01584,</span><span class="z-keyword">0x393498cdb070387b507967acb20ca81ac651fc0112e6f8bf4275a998e87be113</span></span> <span class="giallo-l"><span>01585,</span><span class="z-keyword">0xfa098e6dd3f968cc805e7e32e67beb12ee8d5791c9ad3f4c4f97d8090c5d7532</span></span> <span class="giallo-l"><span>01586,</span><span class="z-keyword">0x379cb7fe8047796010944629cbaa6009c131882ada4df80b344f674a209a02ee</span></span> <span class="giallo-l"><span>01587,</span><span class="z-keyword">0x62641130ea31f0236a9a003332e891538e45fa7190e93f9af17f15fdaa0f73e5</span></span> <span class="giallo-l"><span>01588,</span><span class="z-keyword">0x63224c34401bb9cfd504b6527d4005cbe3d274af04571902b23f4623b177a276</span></span> <span class="giallo-l"><span>01589,</span><span class="z-keyword">0xa972b2e4d5472258ad38813f7ab77a0daac4a0796875b562a65a989c1cb57dfb</span></span> <span class="giallo-l"><span>01590,</span><span class="z-keyword">0x1370376c417b6f988efc6de15723eb81354087bb24b5be9affdd536f7eb5e878</span></span> <span class="giallo-l"><span>01591,</span><span class="z-keyword">0x3c5940a5c4b1ced8cfba620ef392e3bcaea154dd3ec56371ebb50f7d3955488b</span></span> <span class="giallo-l"><span>01592,</span><span class="z-keyword">0xfdcf0f058fd21fd4db98eec51153f4bc489fb41e08c1a8dbf8f1d7f3ffe01a0e</span></span> <span class="giallo-l"><span>01593,</span><span class="z-keyword">0x7779354bd2845311c515a0f22e8f032d09e69f3d10a14a013152ae46000edfd5</span></span> <span class="giallo-l"><span>01594,</span><span class="z-keyword">0xfc12f95bb18ce0bce9db6efa93b555b6108fc6f3241d56a25a2c07d8e18d4e6d</span></span> <span class="giallo-l"><span>01595,</span><span class="z-keyword">0x2118c3d09fa86752bd92dd89053b9afb26337edcf84098361d149f3d9a8eb9d2</span></span> <span class="giallo-l"><span>01596,</span><span class="z-keyword">0xf94bdd17711158be2e5aba2f31d933bca8e1d608a0aaee8d611255e5822072bb</span></span> <span class="giallo-l"><span>01597,</span><span class="z-keyword">0xaeb7c436d1407307f9daa397e49a35bb39d2b7612dcf4a40639643fdd06185cd</span></span> <span class="giallo-l"><span>01598,</span><span class="z-keyword">0xf56b793b792ea72e3e3f8c92ac085de3c0b6e2a04a11486599b92a86c6abd4f2</span></span> <span class="giallo-l"><span>01599,</span><span class="z-keyword">0x6cf982a28fdaf8ff3086f2ab622848b9a1cc92e347202b0c3b5bc8da8669ad9a</span></span> <span class="giallo-l"><span>01600,</span><span class="z-keyword">0xc6a9ee35cb2a1e7ace08025884a30c605db736d1b026cbca495b623cef531c78</span></span> <span class="giallo-l"><span>01601,</span><span class="z-keyword">0x0497bfd92c28ce3e12442ae4bafb6b8bb950448933fbfa5faf307a908385990b</span></span> <span class="giallo-l"><span>01602,</span><span class="z-keyword">0x9a50fff5ebacea0ef3d7d163034333d6c0c133718fae765896cc19513d0e3ed1</span></span> <span class="giallo-l"><span>01603,</span><span class="z-keyword">0xa1d88a2633e02e2c4e08d94c97fd1b76d7003800f78dc3323f9bcc5af6d00bb2</span></span> <span class="giallo-l"><span>01604,</span><span class="z-keyword">0x00e0c17d808088777af62a97fe1e63d0a1ea1433c5368c5e7427bde3e7677589</span></span> <span class="giallo-l"><span>01605,</span><span class="z-keyword">0x8fec155e0c69236d83d2c7039e0e904d800eba28c739bad9bfc5b4c3e616b1a5</span></span> <span class="giallo-l"><span>01606,</span><span class="z-keyword">0x7642a7d34a91eb38072e60a0b44d304de3f84d42928c44891b8768a2255696de</span></span> <span class="giallo-l"><span>01607,</span><span class="z-keyword">0x0a337fdbd42c275522b604f3cf7eebe86a7876ba0e93ad89fc725fa37bffa4b1</span></span> <span class="giallo-l"><span>01608,</span><span class="z-keyword">0x2b8f0227d5c0605529146c4b66cefdef9fded753b2f496b5d2232de3f0f0ff0d</span></span> <span class="giallo-l"><span>01609,</span><span class="z-keyword">0xceafb20105e86dad0aea7a8cd971d4960c6e675d677a4ff5b467c57072e1c324</span></span> <span class="giallo-l"><span>01610,</span><span class="z-keyword">0x99fdde4b6905f88a904c45a0fae519384c35cbf770ac691cc2f972bc91c9e92a</span></span> <span class="giallo-l"><span>01611,</span><span class="z-keyword">0x0d642ed657bd7c7bad338118f728552422e9d918fc5a6d45b276be73ee489fb6</span></span> <span class="giallo-l"><span>01612,</span><span class="z-keyword">0x01a109f9c1765421c41b740a0beeada7ec1527a116e075768051a865688abc4a</span></span> <span class="giallo-l"><span>01613,</span><span class="z-keyword">0x409c216ecee281bfa9d2292d1483c07a83af57ede1d306c3ef1357e6207bbc38</span></span> <span class="giallo-l"><span>01614,</span><span class="z-keyword">0x608abfc5fdaed326966359b7494e26fad1a0897d36404404cdd1e9d760a2cc63</span></span> <span class="giallo-l"><span>01615,</span><span class="z-keyword">0x546296f9bdd48f7a10748c5685047652d24ee0f5d9d5d39d00c138b5b72963a3</span></span> <span class="giallo-l"><span>01616,</span><span class="z-keyword">0x210f4a03fc1ad41169c1a2110e9881cb518e3a91920784a93790ec49b14ca899</span></span> <span class="giallo-l"><span>01617,</span><span class="z-keyword">0xf300016daf617180a864891d6e395a1d693586922d87b42012be8d01f21a08c6</span></span> <span class="giallo-l"><span>01618,</span><span class="z-keyword">0xd126355b8481e0ce290bcd7d8e59ea88d84464af126c0711c4aace2295d81ec6</span></span> <span class="giallo-l"><span>01619,</span><span class="z-keyword">0xfccf39eec398431f05ecebc058d0f7451b0601e47c8a32403f430fee1fa91b4b</span></span> <span class="giallo-l"><span>01620,</span><span class="z-keyword">0x62719ac2f5906f11574a39f6235b3d12052d2df36855880901e99ab7dc7671da</span></span> <span class="giallo-l"><span>01621,</span><span class="z-keyword">0xd410e2d782f4489c884bfca0410d81ec6376b2558e2fdaa4329d57739155b4e2</span></span> <span class="giallo-l"><span>01622,</span><span class="z-keyword">0x3a2643d146858acc75041baf09f47c0f2d25d4f102c12fc7d3db22f670be350f</span></span> <span class="giallo-l"><span>01623,</span><span class="z-keyword">0xb86b68f188d4f0d56f35bd8df010b9154c282c78ea9604ef6e94084e9c851b8d</span></span> <span class="giallo-l"><span>01624,</span><span class="z-keyword">0x79abcea66a1e7adfb03c8c047ccc1823881335a68f7221a13f057b9b812fa6eb</span></span> <span class="giallo-l"><span>01625,</span><span class="z-keyword">0x9d2445ad11ecdc91945bf0507eb97181e1a8d7373c3f68b0760959a45a32fd05</span></span> <span class="giallo-l"><span>01626,</span><span class="z-keyword">0xa0719f0293eda9efab5b6cd4fbe9be45f707761d77e089ab27c965058eed2737</span></span> <span class="giallo-l"><span>01627,</span><span class="z-keyword">0x3825eb62719002200fd1b8ece3f1fdcf80705657d68e418366eeae57b14acfbd</span></span> <span class="giallo-l"><span>01628,</span><span class="z-keyword">0x49d1a71da4a7a27348aefd008cc5227b28544ee604eb242e1c2b037f67c3abdb</span></span> <span class="giallo-l"><span>01629,</span><span class="z-keyword">0x1ec93093a36a54010ad1302caf7c5c24188c3d668ccfe895972a57ff6587850d</span></span> <span class="giallo-l"><span>01630,</span><span class="z-keyword">0xd52d9f3e99b17ef53cb1045db3488f149feb348547eaaa57f54bf7aaf6d18957</span></span> <span class="giallo-l"><span>01631,</span><span class="z-keyword">0x438a5c23f506d979268a2884664886c208526d050df78870f68c331625ee95d0</span></span> <span class="giallo-l"><span>01632,</span><span class="z-keyword">0xb811a1ab572962105e233bc72569ef1ef980ffaec0c58c62c0e08744fdb23a7d</span></span> <span class="giallo-l"><span>01633,</span><span class="z-keyword">0x2dba253d07386a24dac2fc5c78c557e25f4e521c2c5c37ebf514b9bbabd9f4f2</span></span> <span class="giallo-l"><span>01634,</span><span class="z-keyword">0xc0975217f67c73ea0f22c7475233b64524f228a7da61e6c531cfd932cee27109</span></span> <span class="giallo-l"><span>01635,</span><span class="z-keyword">0x926f0429fd3f751c428e5501e7ffbb006ad7048930e1820455b6fe404b7d8a17</span></span> <span class="giallo-l"><span>01636,</span><span class="z-keyword">0x88bc22af6003d122e5ac2b7981aefe48cc5e787777a77364dc12530b35d33397</span></span> <span class="giallo-l"><span>01637,</span><span class="z-keyword">0xd10229ae7c392518d3bcaa15f43ed0c2cca4f235cbe009e1aa711b109cded52c</span></span> <span class="giallo-l"><span>01638,</span><span class="z-keyword">0xf60a479f9ebd1a81e807ddaa404c8cc9b855eb08efa4481810529674214b8c84</span></span> <span class="giallo-l"><span>01639,</span><span class="z-keyword">0x45574d293ed9b0ade09f8b041efd0f9be629979743111520a7c0224e41c36213</span></span> <span class="giallo-l"><span>01640,</span><span class="z-keyword">0xf4d925c6aaeb0d96944b66a46324fd09815af73338fe9c58c332f77869473fff</span></span> <span class="giallo-l"><span>01641,</span><span class="z-keyword">0x055616453b16d6ff8caa12ea67e2543aa0fe47cb5c610699d5aded16ccdb72d2</span></span> <span class="giallo-l"><span>01642,</span><span class="z-keyword">0xbffe5d04ec76b2d00ec35af8ed488116f1d3d454b1476db9c68bc62590b91b62</span></span> <span class="giallo-l"><span>01643,</span><span class="z-keyword">0xdb04ce690ea5b0472a5f3d630336a0977e19517bb6c8443876e76d49f5876c98</span></span> <span class="giallo-l"><span>01644,</span><span class="z-keyword">0x836dd3c2e51dd27fdfc1aca4839218e9a40390bb8966c257d470c5e13d610d09</span></span> <span class="giallo-l"><span>01645,</span><span class="z-keyword">0xccdd4d3758c1b860176290f80a588cf9f8f257ee6a094019968b645969039e52</span></span> <span class="giallo-l"><span>01646,</span><span class="z-keyword">0xdf78d1aa527997f2f34dcc3df048e8273d4c2147867b13f009fff3fabe1227e6</span></span> <span class="giallo-l"><span>01647,</span><span class="z-keyword">0xbc1a2596d167f86f145df1c74a4ce5cdeb09e21c4f9077a7b7a75a026a9cd7e0</span></span> <span class="giallo-l"><span>01648,</span><span class="z-keyword">0xba4445506249f1cd7510b1159ba679867a8a721810502db35b871131a52f6e9b</span></span> <span class="giallo-l"><span>01649,</span><span class="z-keyword">0xc772985ee13356a7519f619cba370e0d30b2b17faac8e8779b34e77f319c2f21</span></span> <span class="giallo-l"><span>01650,</span><span class="z-keyword">0x0cd44f84d292e1d1a88b51fb885b084cb2e3e4e9ab284c6174e1277fdc808c12</span></span> <span class="giallo-l"><span>01651,</span><span class="z-keyword">0x108b81392c28178c4f4fb98ed3e03860ebad588e089fbf85a87ba9988e27c055</span></span> <span class="giallo-l"><span>01652,</span><span class="z-keyword">0x92dc53a4408de761c673c56bf0c52c88cd2cd65777b47f65ba27265dcf5a4b2e</span></span> <span class="giallo-l"><span>01653,</span><span class="z-keyword">0xac1c8ccb958d598d2591f82adcbce06cd05c5bc8c7714195f2808a42602cbd55</span></span> <span class="giallo-l"><span>01654,</span><span class="z-keyword">0x2f466ff62e6b2eb3193683dca7c0af52da1825c22cae69cfda8b187d2d719bfd</span></span> <span class="giallo-l"><span>01655,</span><span class="z-keyword">0x4dc5edd2150d175af8dd28927a1529a52080d0e0d2075d0c6f703ec2a527ef03</span></span> <span class="giallo-l"><span>01656,</span><span class="z-keyword">0x72d321b5204000c80fd39ccf2fe72a17cac0eea2195133632b987461a4939c1d</span></span> <span class="giallo-l"><span>01657,</span><span class="z-keyword">0xd0684723c2fcb39b6536736b92d24f7ca1bbb6b64c51c69ed69eae1ab22c83c7</span></span> <span class="giallo-l"><span>01658,</span><span class="z-keyword">0x651f1c70b5bd5638c095aeaee6313f1d4d2e28471ce7ce98aed045cec480d016</span></span> <span class="giallo-l"><span>01659,</span><span class="z-keyword">0x0013c08b64bf7e3afab80ad4f8ea9423f1a7d8b31a149fc3b832d7980719c60c</span></span> <span class="giallo-l"><span>01660,</span><span class="z-keyword">0x7825d5b222a31cadf8cc345ae34eff92e4d617659c3f630037821d5acf6a5cfa</span></span> <span class="giallo-l"><span>01661,</span><span class="z-keyword">0x84e21383079e4674dd0c63cb29cd89f0726ed8895aa83aa99febd249dc9620a4</span></span> <span class="giallo-l"><span>01662,</span><span class="z-keyword">0xa5681587c34c7e8d143b6332a98804a6940655b08c9764ee13f8362b929f15eb</span></span> <span class="giallo-l"><span>01663,</span><span class="z-keyword">0xc84283fad5c6405f6c9d51c0597b9908406ff09772233255fe61a1494e09cb2c</span></span> <span class="giallo-l"><span>01664,</span><span class="z-keyword">0xab3af7a0e7c174b428f865f4fbe6d49aab50b91a0cb5555687f2769c6c874836</span></span> <span class="giallo-l"><span>01665,</span><span class="z-keyword">0xd0adeec06347b843d108e4d349b50156dcaa131bc27c7752a1cc3c3035b230d2</span></span> <span class="giallo-l"><span>01666,</span><span class="z-keyword">0x827de27e4fa09f2ddd98223a7393881100fd9c533b55416b3839ad8f3b6835ec</span></span> <span class="giallo-l"><span>01667,</span><span class="z-keyword">0x558e21250bc559d5e9cbf0b5c9787f4607cd769a3d96d4c174b769907b8032f2</span></span> <span class="giallo-l"><span>01668,</span><span class="z-keyword">0x8d75bc100e6afde488e081895914ea1c5658115a0e028b439e2cb2d52c02a29c</span></span> <span class="giallo-l"><span>01669,</span><span class="z-keyword">0x84ccda7e5a2f253fee50e47559bdd8db96026897cec18ac128409ec405979de1</span></span> <span class="giallo-l"><span>01670,</span><span class="z-keyword">0x3490d679757169a0132ca44b3c408b53e9dbb23dfde34a6c8ad34ddd0f88ce78</span></span> <span class="giallo-l"><span>01671,</span><span class="z-keyword">0x4533f7b3dc71406ffa10a0af1fbb9b2d5cf61f7ae1d7a58c57734680984ef875</span></span> <span class="giallo-l"><span>01672,</span><span class="z-keyword">0xabf106295d76c72cbcc2b778712a1b954319d1b4a1365e19cbbf9ed0c39d7445</span></span> <span class="giallo-l"><span>01673,</span><span class="z-keyword">0xd67018bd3f840799601c348f8d2a55eb0d46ece00688a3ae5d7a699de71817a0</span></span> <span class="giallo-l"><span>01674,</span><span class="z-keyword">0x16b9e8771fd65164ad5b4344b67bbc519da70ca263c562c0088a9c30dde29cb9</span></span> <span class="giallo-l"><span>01675,</span><span class="z-keyword">0x35b0af7b1dfac60196dec285536cee1ff48d20579fe0df117be9566c78fd9404</span></span> <span class="giallo-l"><span>01676,</span><span class="z-keyword">0x2753d9cd14ed65494895baf136feef1f4c0096ac569e856a0b858c43046dbaf5</span></span> <span class="giallo-l"><span>01677,</span><span class="z-keyword">0xe40b2ea438c3da468e62d736f576e9c6bf89e7b2079569b11b7b63ab6b859e53</span></span> <span class="giallo-l"><span>01678,</span><span class="z-keyword">0xfcbdf0e3790abaa1ed31b64333b348ecdc15a15a213488f46d753ea77659d1b9</span></span> <span class="giallo-l"><span>01679,</span><span class="z-keyword">0xe5f342e28cd6a85862e29a8bc6ededb8ce9e5252f02db387ca6b27f234a1c8c4</span></span> <span class="giallo-l"><span>01680,</span><span class="z-keyword">0xaf511202a03e86af88d1a53657068bad1682ed4d3c3d446e4e553313c4183f91</span></span> <span class="giallo-l"><span>01681,</span><span class="z-keyword">0xd0e6d3d3842257da332754ff2e0ee2f28b630041e206da98093d60fd29cb2494</span></span> <span class="giallo-l"><span>01682,</span><span class="z-keyword">0x66ddcfa8295f3681fe0dc6fa254f4a86cd25127f247cde63ea7b310f8934f163</span></span> <span class="giallo-l"><span>01683,</span><span class="z-keyword">0x8887a5b6add7aad0916907bf209931a98364a7c2a74162ccbea586d2c95fc4fb</span></span> <span class="giallo-l"><span>01684,</span><span class="z-keyword">0xbb0ab38ced9c5de37409997ef703c79d0d0273d0599436d79c86fb19710f0580</span></span> <span class="giallo-l"><span>01685,</span><span class="z-keyword">0x64bf045d836bd1a99dd127859286752a1c09c20fb5b8a70d2c238c86d6565640</span></span> <span class="giallo-l"><span>01686,</span><span class="z-keyword">0x7a8fba5b00f60ce646da4ffa64981c334b927fbbbfa037890aab81f2ae5c65fc</span></span> <span class="giallo-l"><span>01687,</span><span class="z-keyword">0x26481dad4204488c03b357ab61f70c3e214800bd461be5b14a758caacbac5a94</span></span> <span class="giallo-l"><span>01688,</span><span class="z-keyword">0x05f0a17478f22868e8c1442a512807f1ba0f0ba7d2452c2ada4b0626b23b6019</span></span> <span class="giallo-l"><span>01689,</span><span class="z-keyword">0xac53e2ecad8e9ff6a20cd863627056469d0fe53c1e5ec3b590dffc853f36576e</span></span> <span class="giallo-l"><span>01690,</span><span class="z-keyword">0x9dbcd976d813101a23ea057a561d714c26264f42fec6b5f3dd2f06708423867a</span></span> <span class="giallo-l"><span>01691,</span><span class="z-keyword">0xbb315f50f96b903776ae3f1e1cac5b683d34104953c62bae500aa4b2a29d8a4e</span></span> <span class="giallo-l"><span>01692,</span><span class="z-keyword">0xb877548bc73b777200804316b2cf7081152f0fa8923908b8ce8715126fbb3963</span></span> <span class="giallo-l"><span>01693,</span><span class="z-keyword">0x3d2c2aad64a353e2400dd1141f9bd7bab23dfa8aec7c2e5c42a1c52c58fd7cd5</span></span> <span class="giallo-l"><span>01694,</span><span class="z-keyword">0xd42cdf89f6ddbc2f8a8bcd4f6786cf73b985399c41328fd76c08821dcb2cb39a</span></span> <span class="giallo-l"><span>01695,</span><span class="z-keyword">0x8d97b21795f44f7c853891c4f8007e2b9eeb7999c16ff0d81e744742f758dc7c</span></span> <span class="giallo-l"><span>01696,</span><span class="z-keyword">0x49e0b594a63361d8cb35b386558238731b5b206702a2b68050290948b97a2b90</span></span> <span class="giallo-l"><span>01697,</span><span class="z-keyword">0x01b23d087a4adf659d9a5f4c65eaf4a3164b46a7398dc516a52efd4f2f8ca77c</span></span> <span class="giallo-l"><span>01698,</span><span class="z-keyword">0x9c316b67ce5ae45a6ba25c46c1720b77741ce1bd7631e5da01fb509ca50ace2f</span></span> <span class="giallo-l"><span>01699,</span><span class="z-keyword">0xcea5c210e2ef00d919631ccb5e68b178fb9b480062d13cc8604ce3845d950362</span></span> <span class="giallo-l"><span>01700,</span><span class="z-keyword">0x3d9833e9df7243daa3904d9a41d3808841ba7ea07998eb140d63ad0b82f49d5f</span></span> <span class="giallo-l"><span>01701,</span><span class="z-keyword">0x073ad3dcaef6a4e5c3deec4d10a9795592dca55108e7fd3cf274ada351c290ae</span></span> <span class="giallo-l"><span>01702,</span><span class="z-keyword">0x9c454cbcd610aa388489e7db1f4849677840ce1f0a3679e88d9e102e2b646aa7</span></span> <span class="giallo-l"><span>01703,</span><span class="z-keyword">0x0d424bdb826419a44bbe1435dbf09f15e33b105a97d0c11741401fb5e151f306</span></span> <span class="giallo-l"><span>01704,</span><span class="z-keyword">0xc842662446daaba43a5dbc82bb9bc5735a21aba5fa7c6a0642a2a645d2fb06a9</span></span> <span class="giallo-l"><span>01705,</span><span class="z-keyword">0x850425a72ebd6cac965b15c5411581bb261a58e2e9f304fbbcc1f6ec56a3689a</span></span> <span class="giallo-l"><span>01706,</span><span class="z-keyword">0x5f7468d23fbeed676fe8188c346cc24453860c8e265373880ee3ca128e9f98b9</span></span> <span class="giallo-l"><span>01707,</span><span class="z-keyword">0x68199dcdf8d631885b4e264ef8160a64551e500f2f49aaac4e2966d6b42143fb</span></span> <span class="giallo-l"><span>01708,</span><span class="z-keyword">0x1bc39088aff2c8759c5f61190c8af3aeb48cc644a57ec061b6547c97395754a4</span></span> <span class="giallo-l"><span>01709,</span><span class="z-keyword">0xac6bdf4cbd7c785c68ed288da6c280a6d1b7340e882e1a71688e56b31d237970</span></span> <span class="giallo-l"><span>01710,</span><span class="z-keyword">0x616a421395c539814d92259f0dbdccc436b6be78d1ad264305abc632fae12c63</span></span> <span class="giallo-l"><span>01711,</span><span class="z-keyword">0x675a2efc56ef5c385bc82bd826482cd8247801e0556f38182d2d396d7af13474</span></span> <span class="giallo-l"><span>01712,</span><span class="z-keyword">0xb3466ce1c9c6c1f1c5c8681c13442c053bd73443ebd60b0443cccf95717fb756</span></span> <span class="giallo-l"><span>01713,</span><span class="z-keyword">0xefe87a15350ae4b7ea6136f27efba4c610f7d260cad4188771530e46a85d96ca</span></span> <span class="giallo-l"><span>01714,</span><span class="z-keyword">0x8a93b06d9b9e80fc6e21443ec976bbd3de80fa2ca50768e728598d44c6fce197</span></span> <span class="giallo-l"><span>01715,</span><span class="z-keyword">0xc53f6fe8560e2c1f79a629b335139dff42a166dba3a3f3cdd8b9f3c45c482cef</span></span> <span class="giallo-l"><span>01716,</span><span class="z-keyword">0xbeebbc85402356009b2eecfc3e808aa7d6b671ce58430bada153e2678890476a</span></span> <span class="giallo-l"><span>01717,</span><span class="z-keyword">0x2daba19a743ea4ca797c5c20fffea6f79979ebd83d0606fa86a38c02709d0425</span></span> <span class="giallo-l"><span>01718,</span><span class="z-keyword">0x69ddf701e288b58796af67a303745d123486204a9a7e0ac18b2afb25c4c9b61d</span></span> <span class="giallo-l"><span>01719,</span><span class="z-keyword">0xac2ebcf440ba3a2ef280e8004918a9b6d849e19b321823a57132d7799c21a147</span></span> <span class="giallo-l"><span>01720,</span><span class="z-keyword">0xc428eb527615d3acc4dbd68d2052fe6db27152c73bb2b22edfe4d9f13fd67ecf</span></span> <span class="giallo-l"><span>01721,</span><span class="z-keyword">0x940116cedc675ccdecfc2ace0d21817c7e13d57154dfbabd0ac759cb68fc7aed</span></span> <span class="giallo-l"><span>01722,</span><span class="z-keyword">0x1aff873b75f990bea4c06fd212d2862a06d28047e47592b8809eeb164826bdf8</span></span> <span class="giallo-l"><span>01723,</span><span class="z-keyword">0xf19dc7c143cd5aac499bab456496409958bc496ed1b807c209069e5fb78089a6</span></span> <span class="giallo-l"><span>01724,</span><span class="z-keyword">0x50ba9e2446defbca234aba740d15221152d261f9987e24f6e9ff3833d2422c88</span></span> <span class="giallo-l"><span>01725,</span><span class="z-keyword">0x6244c9ba553c0a9fdd9985673ec8dc94558b1208ea0b2c09cae8baec14ef04ef</span></span> <span class="giallo-l"><span>01726,</span><span class="z-keyword">0xd9ca0531bdadeb4a42bbbe600161d3bc0c29f6de35c37b584d463c87cc8929be</span></span> <span class="giallo-l"><span>01727,</span><span class="z-keyword">0x019f04b76df87f056d3e85bf6100ad35611dce5c332f9c885cf4ddf9e4b0df05</span></span> <span class="giallo-l"><span>01728,</span><span class="z-keyword">0x0bd9139ddae4c9e202aa11614fbe037609445363727e6057db969600bc442615</span></span> <span class="giallo-l"><span>01729,</span><span class="z-keyword">0xa85a5ebec5a89cea73285765cd253a54806b53af28dd7577198839114fc037a3</span></span> <span class="giallo-l"><span>01730,</span><span class="z-keyword">0xe07d8fc1ad730fc509989b081ff643430c4d25396853553dde4bc01e0a5c774c</span></span> <span class="giallo-l"><span>01731,</span><span class="z-keyword">0xcdeae685f4d356e7c5cd458638103aa02069a6ca2d8c459bbc49b9e3ac9f302f</span></span> <span class="giallo-l"><span>01732,</span><span class="z-keyword">0xd4b05748bb2981bff1958a4dba0b0f59559bfd5f8fd4e32b1d6c94d0902e1087</span></span> <span class="giallo-l"><span>01733,</span><span class="z-keyword">0x2b75c3c9e417a3ee775e3f6d8b333588c4c8eb482ad9c611c73b8de9fff3403c</span></span> <span class="giallo-l"><span>01734,</span><span class="z-keyword">0x0b51aa4b64600138e09022ba4fcd58449faf43f4b1f8a5e82d9450fec703516c</span></span> <span class="giallo-l"><span>01735,</span><span class="z-keyword">0x5b7da9fdc48dac8163f0a2620536639c95e1f3c35f5d09442cd077900ba3397e</span></span> <span class="giallo-l"><span>01736,</span><span class="z-keyword">0x2d581b4305c5b54aa72fbb2dea7f95fcd7ecd06dbafa7d1f52197cbb86cd7275</span></span> <span class="giallo-l"><span>01737,</span><span class="z-keyword">0x053468cbce94fcb5f0170028e0a585bb98000c005cbb0f9d8cdc0274cc3fdcf4</span></span> <span class="giallo-l"><span>01738,</span><span class="z-keyword">0xc4ea73550a711a24cdb631632d8b9826098f572e1dd0f5d338a7d571e40a0670</span></span> <span class="giallo-l"><span>01739,</span><span class="z-keyword">0x390296d239ff8e7ba83108c01143904890332e29c7fb89f287be70d9e446a4af</span></span> <span class="giallo-l"><span>01740,</span><span class="z-keyword">0x0bc99a43bd74f339e60b6cb7235925e6bd78a56014979d6dd161ad9e2f65c9db</span></span> <span class="giallo-l"><span>01741,</span><span class="z-keyword">0x831ca1406a51f08d9e8b7f9b4ae4e9b1562ec6b3a965e648f5fba403985d7c5f</span></span> <span class="giallo-l"><span>01742,</span><span class="z-keyword">0x6ea854bc3a2a1cad0e25a07bc1a13146837088263c4b906a86f3aff87748a250</span></span> <span class="giallo-l"><span>01743,</span><span class="z-keyword">0xcbe74e160ce637284edac7282156fd9a04638631e32dde566ef91abe19e9d7db</span></span> <span class="giallo-l"><span>01744,</span><span class="z-keyword">0xafde3d1a0a5c90a5b6a8ace6e0c51f287a7baa6cd52fbb530d5cd30d77d1a9e1</span></span> <span class="giallo-l"><span>01745,</span><span class="z-keyword">0x265425af9916bed0dd62a2456e7c7da2c9c0f07a25c8974425dc0f116865942f</span></span> <span class="giallo-l"><span>01746,</span><span class="z-keyword">0xffa83edd16de7ec3db737cea195c255b9711b59c21b1497e26747bed2e13f943</span></span> <span class="giallo-l"><span>01747,</span><span class="z-keyword">0x2d7f0f5ad114008c8bcb0c95c1368739149923d73651da238d74d6e4f2e3acb7</span></span> <span class="giallo-l"><span>01748,</span><span class="z-keyword">0x7b69dcfeced3aa613f02ad7933e543e8dd53bfaeee20d90f4f1bd38429dfacf0</span></span> <span class="giallo-l"><span>01749,</span><span class="z-keyword">0xc08c96110c4d40c906c9f31d2d959c22201f86eade534578a58c391900fa278f</span></span> <span class="giallo-l"><span>01750,</span><span class="z-keyword">0x6067e2dac2ea8b7d928570e0b358cb2bde6a09b5169325a6d553e6215ab5b5c6</span></span> <span class="giallo-l"><span>01751,</span><span class="z-keyword">0x50262a09aa1822e9da30e2dfd935d89e012d1d336a88f24d8db38e4ec1608284</span></span> <span class="giallo-l"><span>01752,</span><span class="z-keyword">0x0488926e04563f273a6ad741c30908764e8dac6e38d7032eb8d398a39b6e0f42</span></span> <span class="giallo-l"><span>01753,</span><span class="z-keyword">0x7477c0a14e3afe6b1210829b4fd571ddba704e062565ee06f8fc00631cc348ba</span></span> <span class="giallo-l"><span>01754,</span><span class="z-keyword">0x646def35e15739fb4e6b897511c4a71c34b323e0107a079a03ffe1be11480962</span></span> <span class="giallo-l"><span>01755,</span><span class="z-keyword">0x84f4fc01aa6c9e739865d63f71d6860875ba166ea67b4aa068de28cb1adffc8f</span></span> <span class="giallo-l"><span>01756,</span><span class="z-keyword">0x308e058035fe5998006d16d2b6f6fb289d120e402b96d10100c98e92efc86619</span></span> <span class="giallo-l"><span>01757,</span><span class="z-keyword">0x8b98854f27b4a6d80d520f8fe71c52fafbe55252d3df554a907a9c0c90f1de89</span></span> <span class="giallo-l"><span>01758,</span><span class="z-keyword">0x7c7bd9920cdb8efaed244a333152b7f205bfee6f2eff4e0da455d882b070ab6c</span></span> <span class="giallo-l"><span>01759,</span><span class="z-keyword">0xef9dd1ae52176b521f99f60ae0a16baa1832aec7ce2b95c0e6b20cbd0943b218</span></span> <span class="giallo-l"><span>01760,</span><span class="z-keyword">0xc908c0cba78857bee8eaac7c241106164154782cf8c712987f4b6eb687161ed5</span></span> <span class="giallo-l"><span>01761,</span><span class="z-keyword">0x4c223079fd963774b68c0c75835a4f73a591a7f6647c09fa5def8021344fd209</span></span> <span class="giallo-l"><span>01762,</span><span class="z-keyword">0x58e9482fe6e25ceccb977c5945db92bc2ff9fd044336dbfd13714e6f84d9c99a</span></span> <span class="giallo-l"><span>01763,</span><span class="z-keyword">0xe9b64e4399b811a832bea55ce15fb1a55718352899e8fed5cba324e196b4004e</span></span> <span class="giallo-l"><span>01764,</span><span class="z-keyword">0x69d58dfd877a727ac73429279bd99ba2562eb358598d6c7f2941cdac9f3307bb</span></span> <span class="giallo-l"><span>01765,</span><span class="z-keyword">0x565089600e60764e78b07382ce1e0acc93b255ac0d9e20b4ad585767be9e8ab4</span></span> <span class="giallo-l"><span>01766,</span><span class="z-keyword">0xe47ad77ca6b9d30cefda397443229cb1df5561c9a436fa9d94d3752dbab1b8cd</span></span> <span class="giallo-l"><span>01767,</span><span class="z-keyword">0xc92526a4d2bacdc047f4e86f6a2b159f6c72df8157178c4ca89cda1780245b1b</span></span> <span class="giallo-l"><span>01768,</span><span class="z-keyword">0x0f318bcdb0e0d78f54276c87b5be9aa21919381bf2e82205072e8c10cb8cbc21</span></span> <span class="giallo-l"><span>01769,</span><span class="z-keyword">0xcc56b7c7ff7ead6cf9f72199ed9ae0a94d5afcd7fc25ad93275a37cdde487e62</span></span> <span class="giallo-l"><span>01770,</span><span class="z-keyword">0x8a0d9bcdcf18b4038a4df3f96e0782f2bb1d4d84ef4932b73dd0f2655f1c9187</span></span> <span class="giallo-l"><span>01771,</span><span class="z-keyword">0x8c0c7922138320604c1287c6c0f87fdb37566752373a62c150c06653189cf070</span></span> <span class="giallo-l"><span>01772,</span><span class="z-keyword">0x490072e141e5099852008eb31e3b432bbc2d71cd988dd62a6872bd723f4464a9</span></span> <span class="giallo-l"><span>01773,</span><span class="z-keyword">0x441a3c8c2fe28eede2b4ed609cf3fca8740cac9638c5962e2214c00365a3a787</span></span> <span class="giallo-l"><span>01774,</span><span class="z-keyword">0x9d3c41ed132dc44de0d39c9d3dd4cc11c1e8a7f8f0316eb774991a9999c0f372</span></span> <span class="giallo-l"><span>01775,</span><span class="z-keyword">0x6023b5ad4e7a8f918fefab880f48288bd8e0da6b9e2e3880f17ab96e3ebcd618</span></span> <span class="giallo-l"><span>01776,</span><span class="z-keyword">0x848902b06524297d54f30c1ddb0c7629c03fb1ba49464244cfe8b198ff99dc26</span></span> <span class="giallo-l"><span>01777,</span><span class="z-keyword">0x56f9c62bb1fb7eb1575c94cf34a37b136b82db0979412504812d7bd21990d5a2</span></span> <span class="giallo-l"><span>01778,</span><span class="z-keyword">0x01a7fc06f4248e48ece709e46292bb7e0a69317fefbd38215c4c093a0d42e425</span></span> <span class="giallo-l"><span>01779,</span><span class="z-keyword">0x9ff0b05413db15b73284db1b8d1702ff095cce5810d44c6457693516ac3e4d65</span></span> <span class="giallo-l"><span>01780,</span><span class="z-keyword">0x0601be62d83f52db2fd5baa50940e9efb464596f0ed80d11722d2944f56bc38b</span></span> <span class="giallo-l"><span>01781,</span><span class="z-keyword">0xc73b916a7b1049230c965741275142bf554805f395feeddf9a8a84934fefce35</span></span> <span class="giallo-l"><span>01782,</span><span class="z-keyword">0x4ff9deb85b08cc30d36d12e391e9ee9bb72a7db2cb52679b62cbae6059a67a46</span></span> <span class="giallo-l"><span>01783,</span><span class="z-keyword">0x6dcf0704c8afbf5b87adf316a01ebff4f641cefff7ba33d672ed51f477a2cf8a</span></span> <span class="giallo-l"><span>01784,</span><span class="z-keyword">0x37725e0bd787534538108e890787fd1606569bd4db127d22da37f2a4f2373fde</span></span> <span class="giallo-l"><span>01785,</span><span class="z-keyword">0xbb264cc368c6866747b9a711e14933f8d96f905bdb0b25a07cfcfd2b094a5fa4</span></span> <span class="giallo-l"><span>01786,</span><span class="z-keyword">0x8f3dccda34ec0838afc97c36da3b66c7a3c804709ed64b4725809ede5248dbbf</span></span> <span class="giallo-l"><span>01787,</span><span class="z-keyword">0x8cae5bdc47bc087d43c41f973c4711ea0af9e5ae53fc5a2fa3ff104070524401</span></span> <span class="giallo-l"><span>01788,</span><span class="z-keyword">0x7e1c1704cf56b2e8cdf4ec7af790cdffcc0cfb3fa840a43ffd46d4fa0d0458a1</span></span> <span class="giallo-l"><span>01789,</span><span class="z-keyword">0xdb34d4b8ff52ebaaca16e0ee46cc56669773768e2c2473470d055004825f6024</span></span> <span class="giallo-l"><span>01790,</span><span class="z-keyword">0x0e2fc599445336cd593fe78469762a0eaef058edc4f9a10a7083b42578eb6b18</span></span> <span class="giallo-l"><span>01791,</span><span class="z-keyword">0x0dabc8f4f2cc029e70b238f3ba3f2478038729cbdab741e25e934f3828891e60</span></span> <span class="giallo-l"><span>01792,</span><span class="z-keyword">0x648d0dd207d0201595e12a8a30b247f7d51ee8385935ba68393db91c846459b6</span></span> <span class="giallo-l"><span>01793,</span><span class="z-keyword">0x77485ef35b5343f0b16fab3492a9565a3fabb6b97d3076f2877c489b0a808ad5</span></span> <span class="giallo-l"><span>01794,</span><span class="z-keyword">0xe291673e64217556218b47874f5d9d4c6bf392894f6cabd9f572cf4750bd4d47</span></span> <span class="giallo-l"><span>01795,</span><span class="z-keyword">0xd1d496b1a49c1b8f9e5a7e1146dca4e3c28ac4be22ec0d8764f56ff3ccda0e69</span></span> <span class="giallo-l"><span>01796,</span><span class="z-keyword">0x33a5546bb26b46559e6b72502faf6dfa1060fb41a69bf9fff988c463f6132aa0</span></span> <span class="giallo-l"><span>01797,</span><span class="z-keyword">0x34123297e57b8a075114c3698558387086e3a4b2acfdd54041901f952e7afb91</span></span> <span class="giallo-l"><span>01798,</span><span class="z-keyword">0x3ca0aeadff3449302ce20766cc4dc0b1628f85cbd26665a40b0f509493428f08</span></span> <span class="giallo-l"><span>01799,</span><span class="z-keyword">0xe949b50c73fe40ff59ab7e8b460a5c81a411b02931151d95eba96ba7e422b731</span></span> <span class="giallo-l"><span>01800,</span><span class="z-keyword">0x07cb6fc533ed260b5b01e470e4d874270270fc5332f423e620be1dd92b06ff6a</span></span> <span class="giallo-l"><span>01801,</span><span class="z-keyword">0x8edf5827b93f9dd727c25e4cdf558bdef0c8d1962c993666fb469082ae607e6e</span></span> <span class="giallo-l"><span>01802,</span><span class="z-keyword">0xf95306bb3bc429f9229f80e3fd50446435e98eb615bffdb379d202abcad65f98</span></span> <span class="giallo-l"><span>01803,</span><span class="z-keyword">0x4e1d05e25890a1b0b1f301452321893b91ec09ca755dea16b16fd8eb0d02a39d</span></span> <span class="giallo-l"><span>01804,</span><span class="z-keyword">0xa24b5a4a59adcc97ac586cf83a7314357ae74c48d9099ca9463954f8ca24db24</span></span> <span class="giallo-l"><span>01805,</span><span class="z-keyword">0x81d9a9522808c36c1845abcc5a080b237f69ec54c4f263c31c3fb2738bddbf38</span></span> <span class="giallo-l"><span>01806,</span><span class="z-keyword">0x66534ad9878fc2792c46d45c62a93320cdbd40c276025bcfb786dda3b53e775c</span></span> <span class="giallo-l"><span>01807,</span><span class="z-keyword">0x37ac18016b4a26060dde93000fe2b5614ae011c506725b391bdafaf9d613f8fa</span></span> <span class="giallo-l"><span>01808,</span><span class="z-keyword">0x3f1a883d82a05988793b449444221a6baa67a0975a8bdc20bd5c8044fb059bd7</span></span> <span class="giallo-l"><span>01809,</span><span class="z-keyword">0x45d0f53f5567f627b64e808129a7730badce39d542584ac3b4e392e549eebe9b</span></span> <span class="giallo-l"><span>01810,</span><span class="z-keyword">0x6ccaab76edecb5af607c5f4a741d30e9b9762ac77bfcac89b087ac9fdb51727f</span></span> <span class="giallo-l"><span>01811,</span><span class="z-keyword">0x9ab98ad907f0df327b31733e17eca703d44c5315e0f3f381dee38a6716e9bbb6</span></span> <span class="giallo-l"><span>01812,</span><span class="z-keyword">0x80d86e96ae3c138cb93d8b83e1aca9930c3aef9845f19e164076a319c12b3d29</span></span> <span class="giallo-l"><span>01813,</span><span class="z-keyword">0x1b4ae400e53cfcfe9027f84324909f496fdba244a748a8786a8b6f30126bedb6</span></span> <span class="giallo-l"><span>01814,</span><span class="z-keyword">0xe0064cce975cf20b2bf11f501c61e1cfc5df450c0231fea9b29df7d134b1b5cd</span></span> <span class="giallo-l"><span>01815,</span><span class="z-keyword">0xa2d0424093b6f41d5bc9c2d6bc63596e722f91e214f3453d692e27404d58cb31</span></span> <span class="giallo-l"><span>01816,</span><span class="z-keyword">0x9a493dd73536b40fe784e7710b23ead682163b5c2873d06fb634b41821df1d12</span></span> <span class="giallo-l"><span>01817,</span><span class="z-keyword">0xf534c5f3151aba70c4902307fd1d8cb8a9227ea3bfe00099879f9af4458f7cca</span></span> <span class="giallo-l"><span>01818,</span><span class="z-keyword">0xc34b86c65e0db470eb8f644fc648b5520546535adecff743126a2bb394fb474a</span></span> <span class="giallo-l"><span>01819,</span><span class="z-keyword">0x918b86fa5fabcbe1535ff25b9cc6bf18399033a10feab07b1b2a44e652c890c7</span></span> <span class="giallo-l"><span>01820,</span><span class="z-keyword">0x17e7111cf764fe48d55ae33eb9992d4fa0c443e17aba5ed8121665d09e719642</span></span> <span class="giallo-l"><span>01821,</span><span class="z-keyword">0xe118ce724863baafe5822a6df3eb6322f52b0efac93df5ce30f2890249a5301b</span></span> <span class="giallo-l"><span>01822,</span><span class="z-keyword">0xd7b7b15d51895e067d217712e532f4c1ca318bec69483371d584eca1fcd35dd9</span></span> <span class="giallo-l"><span>01823,</span><span class="z-keyword">0x3fe7a945dc87c69c3c018c68cc45a5ad9d5c76a9623a615305eb03b30bde5286</span></span> <span class="giallo-l"><span>01824,</span><span class="z-keyword">0x6ad87d358fe720d6207c7189c458f01246ef8fdbcebe5bf977590c5053395226</span></span> <span class="giallo-l"><span>01825,</span><span class="z-keyword">0x7f98124406ff6a0ac572d6cbedd187c905ab77a2957904ba9df742ddd37616d9</span></span> <span class="giallo-l"><span>01826,</span><span class="z-keyword">0xc17dc5a387763a48690eeff9f15e2c8a17d46585c0330f855207bf83db5ba7ca</span></span> <span class="giallo-l"><span>01827,</span><span class="z-keyword">0xfa5fbccba9509f70ed5a39bbc8148708230e37f26fb18b7a74aea1616e3e4609</span></span> <span class="giallo-l"><span>01828,</span><span class="z-keyword">0x540009e54254fad311b1b69490c7587db7dbf71ce7a15e62f94d49eaf22525e6</span></span> <span class="giallo-l"><span>01829,</span><span class="z-keyword">0x41ed6fe79b33dc5a32a019496131ea6805aef33a6aaf93982d37dd7653decb41</span></span> <span class="giallo-l"><span>01830,</span><span class="z-keyword">0x2afebfecd0c3c447d920747a1346c865aa846b0ae6f7eb900e25606c8d9ed725</span></span> <span class="giallo-l"><span>01831,</span><span class="z-keyword">0x7289db8d2960f6402252c8699465253d4e3efdc31c832a9ba82b535bbe39dfa1</span></span> <span class="giallo-l"><span>01832,</span><span class="z-keyword">0xb1198d248f79e07609cf29ef8984e2786258b474c17a982d2e4e9219af3d6592</span></span> <span class="giallo-l"><span>01833,</span><span class="z-keyword">0x0bef12618bd2905629f0c9d7427431884e203e70d78f5c9308a3215d79a28556</span></span> <span class="giallo-l"><span>01834,</span><span class="z-keyword">0xfdca337f0afcb8f508449dcfebafb6de99c44f1a468a0c162785b36b20c01446</span></span> <span class="giallo-l"><span>01835,</span><span class="z-keyword">0xa45d06eca259ea9bf79a23c0a8a50cd784fa072330050f7da63a0e4acd14b4f6</span></span> <span class="giallo-l"><span>01836,</span><span class="z-keyword">0x87fe297ba8e996cf2b1fdb854e86b043f485149eea31c3c74187402b58892cce</span></span> <span class="giallo-l"><span>01837,</span><span class="z-keyword">0xe26e40bdb2425b55bd59c814f5839f7ff9f74aa1aa86d23e95988048d319e64c</span></span> <span class="giallo-l"><span>01838,</span><span class="z-keyword">0xec6b0c035002b5d12e30ff8e3f97f281f562593eff842cf8905468c3d9c9777e</span></span> <span class="giallo-l"><span>01839,</span><span class="z-keyword">0x07950048304ce616f23f40789e4f7995ce30e164dc5e35d97ab241998924b825</span></span> <span class="giallo-l"><span>01840,</span><span class="z-keyword">0xe287972bf569570a6f2f8d3dd01ceebff3c9c849706e2ebe133ce72dbbbadcec</span></span> <span class="giallo-l"><span>01841,</span><span class="z-keyword">0x2a6039e5b858d952e07cbc9057a4506b30edd01944b253c0bb68fdc9e4616b6b</span></span> <span class="giallo-l"><span>01842,</span><span class="z-keyword">0x5567d80f36494b4f26232e2a26f06fc382bdddf8b9eb7a20d56087f13e1cd561</span></span> <span class="giallo-l"><span>01843,</span><span class="z-keyword">0x3153e10ad6830573f85e149d79579aaa27e4161239b5bef085dfe1c86d2d04cf</span></span> <span class="giallo-l"><span>01844,</span><span class="z-keyword">0x03b0963dd2f6917a141dcb843dcdc7b8fe71ffc51a29cf86b7f909ba9ff178b2</span></span> <span class="giallo-l"><span>01845,</span><span class="z-keyword">0x03b93b158737ecadc1a498bbe78e247ec652f5707571512674bb231e4c35593f</span></span> <span class="giallo-l"><span>01846,</span><span class="z-keyword">0x3e05673eeaabb4293f6eba4fc8597b21e935e72e7d614665480e881bba552938</span></span> <span class="giallo-l"><span>01847,</span><span class="z-keyword">0x2de5f285569a2744c7dc3b94d992c655037d370f4f8d8ca04a26b4f30ccbf5ed</span></span> <span class="giallo-l"><span>01848,</span><span class="z-keyword">0x113a0599656907adc266ada978194806c922455ded32bdb8578ddedcc0e31d8b</span></span> <span class="giallo-l"><span>01849,</span><span class="z-keyword">0x71675e40a1ede46ed372c411541b1a66c4d76d33fbfd97db91b9a3a96a45e669</span></span> <span class="giallo-l"><span>01850,</span><span class="z-keyword">0xeb0e8dced91d0329228af294e8273236ae0a4e6f8590ed770ce6b8ecb9d4e9b2</span></span> <span class="giallo-l"><span>01851,</span><span class="z-keyword">0x27b488ec8baa7adbc492e5c2311f57d1bb025e42fb362933096f7dbf66112277</span></span> <span class="giallo-l"><span>01852,</span><span class="z-keyword">0xa405f5f3d7c35326f18a1a85fcd88a897d5e3a31867791cee9489042b950375b</span></span> <span class="giallo-l"><span>01853,</span><span class="z-keyword">0xde7294f59c86cf434f1b51c11d36eec758c73de3e0cfdfb0d88f7ef4e6aaf946</span></span> <span class="giallo-l"><span>01854,</span><span class="z-keyword">0x1b3a9f72ed4d4521657db928917a7abdd71f4ba2cf1fa4915b68d1c840fe3eb8</span></span> <span class="giallo-l"><span>01855,</span><span class="z-keyword">0xbb9869151522b5034619c9983d1c21d253a8a46dfc03bdb7c4e8771faa4cd31d</span></span> <span class="giallo-l"><span>01856,</span><span class="z-keyword">0x10e8b0ee7a9e05e342cbdf4cc408d4d207163bf652e9d45a715f63a14079b558</span></span> <span class="giallo-l"><span>01857,</span><span class="z-keyword">0xe0a70c38b92eb6cda8f9b7e2253b88bb8a25833d34f1174e9d5a3dc11d709fb0</span></span> <span class="giallo-l"><span>01858,</span><span class="z-keyword">0x96299d525632a3677163bc6f18e98439e410f1c3f0a0e561bcbb63ed8022b860</span></span> <span class="giallo-l"><span>01859,</span><span class="z-keyword">0x056f7f9b622e013fd1a31107cddb7843babb80ad494781ecc0408a4551a6a04c</span></span> <span class="giallo-l"><span>01860,</span><span class="z-keyword">0xbe17dd25f8ad8b238b69e317126128e379aa87af72ab99cac240b4d6362ef148</span></span> <span class="giallo-l"><span>01861,</span><span class="z-keyword">0x31641a0876c1fef62d170f84f2c6113d88d4d38ce90538e30bed4565fc6a3027</span></span> <span class="giallo-l"><span>01862,</span><span class="z-keyword">0xdeb651e11a7f6e50e2c2adc32ec89af247c4c71763ab3d213bfca70b0e26c311</span></span> <span class="giallo-l"><span>01863,</span><span class="z-keyword">0x500103a06c6cf65606e2c734912c6448844b87904ee9d68c7be782ac5f6188ca</span></span> <span class="giallo-l"><span>01864,</span><span class="z-keyword">0x168be6df9d2a7ba553609c9235d1cef41b783323f60f7c59ca210f3e9db4d764</span></span> <span class="giallo-l"><span>01865,</span><span class="z-keyword">0xd69771c57985c9c43d6195e8be9d199c3b3ca206a682a0c6c2a274b8294b644a</span></span> <span class="giallo-l"><span>01866,</span><span class="z-keyword">0x3cf6a306ef85f605b6b8610c42f3200bc04bf7cfd1b325b8574ed2c28d4ffb62</span></span> <span class="giallo-l"><span>01867,</span><span class="z-keyword">0x69891a16fc79a0e6fd885f23b106806ecf71ad7b3e5d51a579193c4f2583dc5e</span></span> <span class="giallo-l"><span>01868,</span><span class="z-keyword">0xfb7b596a80d0782f73d11fae09d7da314be8143b471193a28901a36d6b58d8f1</span></span> <span class="giallo-l"><span>01869,</span><span class="z-keyword">0xd864488dca9ec72930dbba8d9f554af78dacec003a6f58fbe05cbeeaa8eaca21</span></span> <span class="giallo-l"><span>01870,</span><span class="z-keyword">0x3dc73a6d1c0433c0d98800a9877d3e0e9651e6eace71413ae0f52a7bf58616c8</span></span> <span class="giallo-l"><span>01871,</span><span class="z-keyword">0xca53dc21977789285d08334ce43b0469a5bd54cf890a4ed1e0cf4543b1575457</span></span> <span class="giallo-l"><span>01872,</span><span class="z-keyword">0xd571c79ae2f0b29d334f8c33b14b21a83491d21da2650ccd9d7e3f1b307ca7a4</span></span> <span class="giallo-l"><span>01873,</span><span class="z-keyword">0xc71b3cef8fd89a79abb07c140f1cf9b90f4afaffa3d269ba2dcc9e2831cd0c3b</span></span> <span class="giallo-l"><span>01874,</span><span class="z-keyword">0xb43aeeecf3e3603fc7f82cc03948d50a9cab2c30d26a371afa8d7b0526c20853</span></span> <span class="giallo-l"><span>01875,</span><span class="z-keyword">0x24fb77820016a3b7ff7cd3ec7407364b0b660fb2a6bb0e26e4b8da1deb6275c2</span></span> <span class="giallo-l"><span>01876,</span><span class="z-keyword">0x41ac34f85491e5d80275e95298185b3df6bc6e522b1b6e18a81b4a954573d27d</span></span> <span class="giallo-l"><span>01877,</span><span class="z-keyword">0x54983d685feaa65ccbaed699e5c85a9cc5fb2275ee5ecc15295fa056f35dff42</span></span> <span class="giallo-l"><span>01878,</span><span class="z-keyword">0x56db2145e5e6ffb8f46ab7fd0bf8192af4b7ee8701fc92e3066697fc7fdab1c1</span></span> <span class="giallo-l"><span>01879,</span><span class="z-keyword">0x793c08df7c9a354e39b31fa213f2944ea8361ed33203f0e1e438351e185d241a</span></span> <span class="giallo-l"><span>01880,</span><span class="z-keyword">0x0412a89eb5bf0325ce228aa64f66dcab0855c002db872dd94f3ee97496d41a1f</span></span> <span class="giallo-l"><span>01881,</span><span class="z-keyword">0x8d9912853e99f373036df7a07e47eff4dba631f7456c6fee1bb79a292f530c13</span></span> <span class="giallo-l"><span>01882,</span><span class="z-keyword">0x44df0aab52827e4608b4fab902457682fa019ad5cbbdf7502bb1ba74607078b7</span></span> <span class="giallo-l"><span>01883,</span><span class="z-keyword">0xbd172681ef1b3e781763591809db8067a65590760a1a823716d2afffcd893492</span></span> <span class="giallo-l"><span>01884,</span><span class="z-keyword">0x5732d988076cc1fedf316e07aa3a8567fd55a04ca989876d4bdc63681cbcce48</span></span> <span class="giallo-l"><span>01885,</span><span class="z-keyword">0x5480f07444c8ba60faf8b853c77b72b2e0aee4894a176f920d0965eb92df90f9</span></span> <span class="giallo-l"><span>01886,</span><span class="z-keyword">0xb5e8b2b00ba1708ec31ca0a7e64540c1b02d837991d4e12cdb19d6c75ed0da6b</span></span> <span class="giallo-l"><span>01887,</span><span class="z-keyword">0xdededef33d83e607868d87e8f058511a152de71d8a04b12499d5f1666b89071d</span></span> <span class="giallo-l"><span>01888,</span><span class="z-keyword">0xcdbce5e36cfff749d0ee9ccb6dc344a822ed097e4b8eb812ada19521890d5663</span></span> <span class="giallo-l"><span>01889,</span><span class="z-keyword">0x4a09fe43bd97064993f18d214062005a1ffc76d03495b2b7c65c6137d3dd055e</span></span> <span class="giallo-l"><span>01890,</span><span class="z-keyword">0xff7a1b1127af6429b799637ff6cffb9169aa5000f01b67a54e2c7f9a155e7027</span></span> <span class="giallo-l"><span>01891,</span><span class="z-keyword">0x0f7bffdd015be88c78d30778d5bd66b75e86f9867e221f857352d0cb95c927a1</span></span> <span class="giallo-l"><span>01892,</span><span class="z-keyword">0x9671b1edc7dc58206e18de1e4d107bf2e8508483017749146ff5c82c674408e6</span></span> <span class="giallo-l"><span>01893,</span><span class="z-keyword">0x1b07973b9e818e0e014e52c587149c9775fd44bd5ccd095dee3221ba7c7a9efe</span></span> <span class="giallo-l"><span>01894,</span><span class="z-keyword">0x804008940c025a4e8a00ea42a659b484ba32c14dff133e9d3b7bf3685c1e54de</span></span> <span class="giallo-l"><span>01895,</span><span class="z-keyword">0x3f81607c8cb3f0448a11cab8df0e504b605581f4891a9a35bd9c0dd37a71834f</span></span> <span class="giallo-l"><span>01896,</span><span class="z-keyword">0xe6ebe562c89bc8ecb94dc9b2889a27a816ec05d3d6bd1625acad72227071e721</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>The accumulator root should be verified by community members before being accepted. Although the accumulator root can be verified at anytime by anyone in the future, it is likely clients and other tooling will begin relying on proofs against the aforementioned root in the near term.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-02-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Jamehttps://github.com/ZWJKFLC https://wg-eips.ritovision.com/7637/

Modify the output value of EXTCODEHASH for EOA accounts to `0x`

<h2 id="abstract">Abstract</h2> <p>This proposal is an optimization for <a href="https://wg-eips.ritovision.com/1052/">EIP-1052</a>, For addresses with a balance, but without code, the codehash should still be <code>0x</code>.</p> <p>When an address <code>add.code == 0x</code> and <code>add.balance != 0</code>, <code>add.codehash==0</code> is required instead of <code>add.codehash==keccak256("")</code></p> <h2 id="motivation">Motivation</h2> <p>EIP-1052 was proposed to save gas fees. However, due to some flaws in the set specifications, in actual applications, due to safety concerns, they will not actually be used. In order for EIP-1052 to be truly useful, it should be optimized.</p> <p>If someone uses it based on the proposal of EIP-1052 and does not notice the change when <code>add.balance != 0</code>, there may be security issues.</p> <h2 id="specification">Specification</h2> <p>The behaviour of <code>EXTCODEHASH</code> is changed in the following way:</p> <ol> <li>When calling <code>EXTCODEHASH</code>, the codehash of the address with balance but no code is still <code>0x</code></li> </ol> <h2 id="rationale">Rationale</h2> <p>EIP-1052 In order to include the function of <code>BALANCE</code>, let the <code>EXTCODEHASH</code> of the address without balance be <code>0x</code>, and the <code>EXTCODEHASH</code> of the address with balance be <code>keccak256("")</code>.</p> <p>The contract address can be calculated in advance. Whether it is <code>CREATE</code> or <code>CREATE2</code>, it is possible that the contract is not created but has a balance. For security, You can actually only use <code>keccak256(add.code) == keccak256("")</code> or <code>add.code.length ==0</code> instead of <code>add.codehash == 0</code>,, which makes the original intention of EIP-1052 meaningless.</p> <p>For example, uniswap V2 uses stored addresses to determine whether a contract exists. If this <code>EXTCODEHASH</code> is optimized, can save a huge amount of gas.</p> <p>If someone uses a <code>add.codehash==0</code> to determine whether a contract has been created, due to intuition and the lack of details in many documents, they will not think that the codehash of an address with a balance will change from <code>0x</code> to <code>keccak256("")</code>. If someone maliciously attacks at this time, it will cause some bad effects.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Using codehash to determine whether a non-contract address has a balance will not be available</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Code reference for execution-specs</p> <p>After modification</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> extcodehash</span><span>(</span><span class="z-variable z-parameter z-function">evm</span><span>:</span><span> Evm</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> address</span><span class="z-keyword"> =</span><span> to_address</span><span>(</span><span>pop</span><span>(</span><span>evm</span><span>.</span><span>stack</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> charge_gas</span><span>(</span><span>evm</span><span>,</span><span class="z-constant"> GAS_CODE_HASH</span><span>)</span></span> <span class="giallo-l"><span> account</span><span class="z-keyword"> =</span><span> get_account</span><span>(</span><span>evm</span><span>.</span><span>env</span><span>.</span><span>state</span><span>,</span><span> address</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> account</span><span class="z-keyword"> ==</span><span class="z-constant"> EMPTY_ACCOUNT</span><span>:</span></span> <span class="giallo-l"><span> codehash</span><span class="z-keyword"> =</span><span> U256</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> codehash</span><span class="z-keyword"> =</span><span> U256</span><span>.</span><span>from_be_bytes</span><span>(</span><span>keccak256</span><span>(</span><span>account</span><span>.</span><span>code</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> codehash</span><span class="z-keyword"> ==</span><span> U256</span><span>(</span><span class="z-variable">hexstr</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> codehash</span><span class="z-keyword"> =</span><span> U256</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span> push</span><span>(</span><span>evm</span><span>.</span><span>stack</span><span>,</span><span> codehash</span><span>)</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>pc</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span></code></pre> <p>Source code</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> extcodehash</span><span>(</span><span class="z-variable z-parameter z-function">evm</span><span>:</span><span> Evm</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> address</span><span class="z-keyword"> =</span><span> to_address</span><span>(</span><span>pop</span><span>(</span><span>evm</span><span>.</span><span>stack</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> charge_gas</span><span>(</span><span>evm</span><span>,</span><span class="z-constant"> GAS_CODE_HASH</span><span>)</span></span> <span class="giallo-l"><span> account</span><span class="z-keyword"> =</span><span> get_account</span><span>(</span><span>evm</span><span>.</span><span>env</span><span>.</span><span>state</span><span>,</span><span> address</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> account</span><span class="z-keyword"> ==</span><span class="z-constant"> EMPTY_ACCOUNT</span><span>:</span></span> <span class="giallo-l"><span> codehash</span><span class="z-keyword"> =</span><span> U256</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> codehash</span><span class="z-keyword"> =</span><span> U256</span><span>.</span><span>from_be_bytes</span><span>(</span><span>keccak256</span><span>(</span><span>account</span><span>.</span><span>code</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> push</span><span>(</span><span>evm</span><span>.</span><span>stack</span><span>,</span><span> codehash</span><span>)</span></span> <span class="giallo-l"><span> evm</span><span>.</span><span>pc</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Using codehash to determine whether a non-contract address has a balance will not be available</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-02-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 lightclienthttps://github.com/lightclient https://wg-eips.ritovision.com/7639/

Execution layer clients will no longer serve block data before Paris over p2p.

<h2 id="abstract">Abstract</h2> <p>Execution layer clients will no longer request or respond to p2p queries about block data before the Paris upgrade.</p> <h2 id="motivation">Motivation</h2> <p>As of 2024, historical data in clients has grown to around 500 GB. Nearly 400 GB of that is from block data before PoS was activated in the Paris upgrade. Long term, Ethereum plans to bound the amount of data nodes must store. This EIP proposes the first steps to achieve such goal.</p> <h2 id="specification">Specification</h2> <p>Add a new <code>eth</code> protocol capability with version <code>70</code>.</p> <p>Clients connected on this version must not make or respond to p2p queries about block bodies or receipts before block 15537393.</p> <p>The affected protocol messages are:</p> <ul> <li><code>GetBlockBodies (0x05)</code></li> <li><code>BlockBodies (0x06)</code></li> <li><code>GetReceipts (0x0f)</code></li> <li><code>Receipts (0x10)</code></li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="only-pre-pos-data">Only Pre-PoS data</h3> <p>One might ask why the distinction between pre and post PoS data is made in this EIP. The simple answer is that the at the moment of the merge, the block structure changed substantially. Although execution layer client software today continues on with block data on disk which remains similar to per-PoS data, the beacon chain is now the canonical chain definition. Therefore, a beacon block can be used to both record historical data for execution layer and beacon layer.</p> <p>Over the long term, the distinctions of "execution layer" and "consensus layer" may matter less. This EIP tries to be agnostic to client architecture and instead focuses on the shape of the data.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>After this EIP is activated, nodes will no longer be able to full sync from the devp2p network. To continue doing so, they must retrieve the data out-of-band.</p> <h2 id="security-considerations">Security Considerations</h2> <p>TODO</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-02-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast Andrei Maiborodahttps://github.com/gumb0 Piotr Dobaczewskihttps://github.com/pdobacz https://wg-eips.ritovision.com/7620/

Introduce `EOFCREATE` and `RETURNCODE` instructions

<h2 id="abstract">Abstract</h2> <p>EVM Object Format (EOF) removes the possibility to create contracts using <code>CREATE</code> or <code>CREATE2</code> instructions. We introduce a new/replacement method in form of pair of instructions : <code>EOFCREATE</code> and <code>RETURNCODE</code> to provide a way to create contracts using EOF containers.</p> <h2 id="motivation">Motivation</h2> <p>This EIP uses terminology from the <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> which introduces the EOF format.</p> <p>EOF aims to remove code observability, which is a prerequisite to legacy EVM contract creation logic using legacy-style create transactions, <code>CREATE</code> or <code>CREATE2</code>, because both the initcode and code are available to the EVM and can be manipulated. On the same premise, EOF removes opcodes like <code>CODECOPY</code> and <code>EXTCODECOPY</code>, introducing EOF subcontainers as a replacement to cater for factory contracts creating other contracts.</p> <p>The new instructions introduced in this EIP operate on EOF containers enabling factory contract use case that legacy EVM has.</p> <h2 id="specification">Specification</h2> <p>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>Wherever not explicitly listed, the rules of EOF contract creation, as well as the <code>EOFCREATE</code> instruction, should be identical or analogous to those of <code>CREATE2</code> instruction. This includes but is not limited to:</p> <ul> <li>behavior on <code>accessed_addresses</code> and address collision (<a href="https://wg-eips.ritovision.com/684/">EIP-684</a> and <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>)</li> <li>EVM execution frame created for the <code>EOFCREATE</code> initcode - memory, account context etc.</li> <li>nonce bumping of the account of newly created contract <a href="https://wg-eips.ritovision.com/161/">EIP-161</a></li> <li>balance checking and transfer for the creation endowment (<code>value</code> argument)</li> </ul> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>TX_CREATE_COST</code></td><td>Defined as <code>32000</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/0f9e4345b60d36c23fffaa69f70cf9cdb975f4ba/src/ethereum/shanghai/fork_types.py#L42">Ethereum Execution Layer Specs</a></td></tr> <tr><td><code>STACK_DEPTH_LIMIT</code></td><td>Defined as <code>1024</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/0f9e4345b60d36c23fffaa69f70cf9cdb975f4ba/src/ethereum/shanghai/vm/interpreter.py#L60">Ethereum Execution Layer Specs</a></td></tr> <tr><td><code>GAS_CODE_DEPOSIT</code></td><td>Defined as <code>200</code> in the <a rel="external" href="https://github.com/ethereum/execution-specs/blob/0f9e4345b60d36c23fffaa69f70cf9cdb975f4ba/src/ethereum/shanghai/vm/gas.py#L44">Ethereum Execution Layer Specs</a></td></tr> <tr><td><code>MAX_CODE_SIZE</code></td><td>Defined as <code>24576</code> in <a href="https://wg-eips.ritovision.com/170/">EIP-170</a></td></tr> </tbody></table> <p>We introduce two new instructions on the same block number <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> is activated on:</p> <ol> <li><code>EOFCREATE</code> (<code>0xec</code>)</li> <li><code>RETURNCODE</code> (<code>0xee</code>)</li> </ol> <p>If the code is legacy bytecode, any of these instructions result in an <em>exceptional halt</em>. (<em>Note: This means no change to behaviour.</em>)</p> <h3 id="execution-semantics">Execution Semantics</h3> <ul> <li>The instructions <code>CREATE</code>, <code>CREATE2</code> are made obsolete and rejected by validation in EOF contracts. They are only available in legacy contracts.</li> <li>If instructions <code>CREATE</code> and <code>CREATE2</code> have EOF code as initcode (starting with <code>EF00</code> magic) <ul> <li>deployment fails (returns 0 on the stack)</li> <li>caller's nonce is not updated and gas for initcode execution is not consumed</li> </ul> </li> </ul> <p>In the context of legacy bytecode execution any of these instructions (<code>EOFCREATE</code>, <code>RETURNCODE</code>) result in an <em>exceptional halt</em>. (<em>Note: This means no change to behaviour.</em>)</p> <h4 id="overview-of-the-new-contract-creation-flow">Overview of the new contract creation flow</h4> <p>In EOF EVM, new bytecode is introduced to the state by means of <code>InitcodeTransaction</code> delivering an EOF container (<code>initcontainer</code>). Such a container may include arbitrarily deeply nesting subcontainers. The <code>initcontainer</code> and its subcontainers are recursively validated according to all the validation rules applicable for the EOF version in question. Next, the 0th code section of the <code>initcontainer</code> is executed and may eventually call a <code>RETURNCODE</code> instruction, which will refer to a subcontainer to be finally deployed to an address.</p> <p><code>InitcodeTransactions</code> are defined in detail in <a href="https://wg-eips.ritovision.com/7873/">EIP-7873</a>.</p> <p><code>EOFCREATE</code> instruction is in turn a replacement of the <code>CREATE</code> and <code>CREATE2</code> legacy instructions allowing factory contracts to create other contracts. The main difference to the <code>InitcodeTransaction</code> is that the <code>initcontainer</code> is selected to be one of the subcontainers of the EOF container calling <code>EOFCREATE</code> (and not one of <code>transaction.initcodes</code>). It is worth noting that no validation is performed at this point, as it has already been done when the factory contract containing <code>EOFCREATE</code> was deployed.</p> <p>Details on each instruction follow in the next sections.</p> <h4 id="eofcreate"><code>EOFCREATE</code></h4> <ul> <li>deduct <code>TX_CREATE_COST</code> gas</li> <li>halt with exceptional failure if the current frame is in <code>static-mode</code>.</li> <li>read immediate operand <code>initcontainer_index</code>, encoded as 8-bit unsigned value</li> <li>pop <code>salt</code>, <code>input_offset</code>, <code>input_size</code>, <code>value</code> from the operand stack</li> <li>perform (and charge for) memory expansion using <code>[input_offset, input_size]</code></li> <li>load initcode EOF subcontainer at <code>initcontainer_index</code> in the container from which <code>EOFCREATE</code> is executed <ul> <li>let <code>initcontainer</code> be that EOF container</li> </ul> </li> <li>check that current call depth is below <code>STACK_DEPTH_LIMIT</code> and that caller balance is enough to transfer <code>value</code> <ul> <li>in case of failure return 0 on the stack, caller's nonce is not updated and gas for initcode execution is not consumed.</li> </ul> </li> <li>caller's memory slice <code>[input_offset:input_size]</code> is used as calldata</li> <li>execute the container and deduct gas for execution. The 63/64th rule from <a href="https://wg-eips.ritovision.com/150/">EIP-150</a> applies.</li> <li>increment <code>sender</code> account's nonce</li> <li>calculate <code>new_address</code> as <code>keccak256(0xff || sender32 || salt)[12:]</code>, where <code>sender32</code> is the sender address left-padded to 32 bytes with zeros</li> <li>an unsuccessful execution of initcode results in pushing <code>0</code> onto the stack <ul> <li>can populate returndata if execution <code>REVERT</code>ed</li> </ul> </li> <li>a successful execution ends with initcode executing <code>RETURNCODE{deploy_container_index}(aux_data_offset, aux_data_size)</code> instruction (see below). After that: <ul> <li>load deploy EOF subcontainer at <code>deploy_container_index</code> in the container from which <code>RETURNCODE</code> is executed</li> <li>concatenate data section with <code>(aux_data_offset, aux_data_offset + aux_data_size)</code> memory segment and update data size in the header if needed.</li> <li>if updated deploy container size exceeds <code>MAX_CODE_SIZE</code> instruction exceptionally aborts</li> <li>set <code>state[new_address].code</code> to the updated deploy container</li> <li>push <code>new_address</code> onto the stack</li> </ul> </li> <li>deduct <code>GAS_CODE_DEPOSIT * deployed_code_size</code> gas</li> </ul> <h4 id="returncode"><code>RETURNCODE</code></h4> <ul> <li>read immediate operand <code>deploy_container_index</code>, encoded as 8-bit unsigned value</li> <li>pop two values from the operand stack: <code>aux_data_offset</code>, <code>aux_data_size</code> referring to memory section that will be appended to deployed container's data</li> <li>cost 0 gas + possible memory expansion for aux data</li> <li>ends initcode frame execution and returns control to EOFCREATE caller frame where <code>deploy_container_index</code> and <code>aux_data</code> are used to construct deployed contract (see above)</li> <li>instruction exceptionally aborts if after the appending, data section size would overflow the maximum data section size or underflow (i.e. be less than data section size declared in the header)</li> </ul> <h3 id="code-validation">Code Validation</h3> <p>We extend code section validation rules (as defined in <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a>).</p> <ol> <li><code>EOFCREATE</code> <code>initcontainer_index</code> must be less than <code>num_container_sections</code></li> <li><code>EOFCREATE</code> the subcontainer pointed to by <code>initcontainer_index</code> must have its <code>len(data_section)</code> equal <code>data_size</code>, i.e. data section content is exactly as the size declared in the header (see <a href="https://wg-eips.ritovision.com/7620/#data-section-lifecycle">Data section lifecycle</a>)</li> <li><code>EOFCREATE</code> the subcontainer pointed to by <code>initcontainer_index</code> must not contain either a <code>RETURN</code> or <code>STOP</code> instruction</li> <li><code>RETURNCODE</code> <code>deploy_container_index</code> must be less than <code>num_container_sections</code></li> <li><code>RETURNCODE</code> the subcontainer pointed to <code>deploy_container_index</code> must not contain a <code>RETURNCODE</code> instruction</li> <li>It is an error for a container to contain both <code>RETURNCODE</code> and either of <code>RETURN</code> or <code>STOP</code></li> <li>It is an error for a subcontainer to never be referenced in its parent container</li> <li>It is an error for a given subcontainer to be referenced by both <code>RETURNCODE</code> and <code>EOFCREATE</code></li> <li><code>RJUMP</code>, <code>RJUMPI</code> and <code>RJUMPV</code> immediate argument value (jump destination relative offset) validation: code section is invalid in case offset points to the byte directly following either <code>EOFCREATE</code> or <code>RETURNCODE</code> instruction.</li> </ol> <h3 id="data-section-lifecycle">Data Section Lifecycle</h3> <p><strong>For an EOF container which has not yet been deployed</strong>, the <code>data_section</code> is only a portion of the final <code>data_section</code> after deployment. Let's define it as <code>pre_deploy_data_section</code> and as <code>pre_deploy_data_size</code> the <code>data_size</code> declared in that container's header. <code>pre_deploy_data_size &gt;= len(pre_deploy_data_section)</code>, which anticipates more data to be appended to the <code>pre_deploy_data_section</code> during the process of deploying.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pre_deploy_data_section</span></span> <span class="giallo-l"><span>| |</span></span> <span class="giallo-l"><span>\___________pre_deploy_data_size______/</span></span></code></pre> <p><strong>For a deployed EOF container</strong>, the final <code>data_section</code> becomes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pre_deploy_data_section | static_aux_data | dynamic_aux_data</span></span> <span class="giallo-l"><span>| | | |</span></span> <span class="giallo-l"><span>| \___________aux_data___________/</span></span> <span class="giallo-l"><span>| | |</span></span> <span class="giallo-l"><span>\___________pre_deploy_data_size______/ |</span></span> <span class="giallo-l"><span>| |</span></span> <span class="giallo-l"><span>\________________________data_size_______________________/</span></span></code></pre> <p>where:</p> <ul> <li><code>aux_data</code> is the data which is appended to <code>pre_deploy_data_section</code> on <code>RETURNCODE</code> instruction.</li> <li><code>static_aux_data</code> is a subrange of <code>aux_data</code>, which size is known before <code>RETURNCODE</code> and equals <code>pre_deploy_data_size - len(pre_deploy_data_section)</code>.</li> <li><code>dynamic_aux_data</code> is the remainder of <code>aux_data</code>.</li> </ul> <p><code>data_size</code> in the deployed container header is updated to be equal <code>len(data_section)</code>.</p> <p>Summarizing, there are <code>pre_deploy_data_size</code> bytes in the final data section which are guaranteed to exist before the EOF container is deployed and <code>len(dynamic_aux_data)</code> bytes which are known to exist only after. This impacts the validation and behavior of data-section-accessing instructions: <code>DATALOAD</code>, <code>DATALOADN</code>, and <code>DATACOPY</code>, see <a href="https://wg-eips.ritovision.com/7480/">EIP-7480</a>.</p> <h2 id="rationale">Rationale</h2> <h3 id="data-section-appending">Data section appending</h3> <p>The data section is appended to during contract creation and also its size needs to be updated in the header. Alternative designs were considered, where:</p> <ul> <li>additional section kinds for the data were introduced</li> <li>additional fields describing a subcontainer were introduced</li> <li>data section would be written over as opposed to being appended to, requiring it to be filled with 0 bytes prior to deployment</li> </ul> <p>All of these alternatives either complicated the otherwise simple data structures or took away useful features (like the dynamically sized portion of the data section).</p> <h3 id="keccak256-initcontainer-in-the-new-address-hashing-scheme"><code>keccak256(initcontainer)</code> in the <code>new_address</code> hashing scheme</h3> <p><code>new_address = keccak256(0xff || sender || salt || keccak256(initcontainer))[12:]</code> was originally proposed as the way to calculate the address of newly created contract, similar, but not exactly equal, to what <code>CREATE2</code> uses.</p> <p>This alternative however goes against code non-observability, because it locks in the contents of the initcontainer e.g. preventing re-writing it in some future upgrade. It also seems unnecessarily expensive: <code>EOFCREATE</code> can only pick up one of its subcontainers, yet the hash value would need to be recalculated on every execution of <code>EOFCREATE</code>.</p> <p>Other ways of removing code observability, yet keeping some form of witness of the code, were considered. However, keeping only <code>sender</code> and <code>salt</code> allows the implementer of the factory contract (i.e. one containing the <code>EOFCREATE</code> instruction) to include the code witness via the <code>salt</code> anyway, if that's necessary for the particular use case. Therefore, keeping the <code>new_address</code> formula minimal is the most flexible approach with better separation of concerns.</p> <p>Leaving the <code>keccak256(initcontainer)</code> out of the <code>new_address</code> hash has also the benefit of making the <code>new_address</code> independent of the metadata section (proposed for the EOF in a separate EIP), which is a desired property. Unfortunately, if a factory wants to opt into committing to a particular <code>initcontainer</code>, it needs to include it in the <code>salt</code>, and that will include the metadata section.</p> <h3 id="eofcreate-stack-argument-order"><code>EOFCREATE</code> stack argument order</h3> <p><code>EXT*CALL</code> instructions from <a href="https://wg-eips.ritovision.com/7069/">EIP-7069</a> have had their stack argument order changed, as compared to that of legacy instructions <code>*CALL</code>. We follow the same change to have <code>EOFCREATE</code> stack arg order match those of <code>EXTCALL</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change poses no risk to backwards compatibility, as it is introduced at the same time EIP-3540 is. The new instructions are not introduced for legacy bytecode (code which is not EOF formatted), and the contract creation options do not change for legacy bytecode.</p> <p><code>CREATE</code> and <code>CREATE2</code> calls with <code>EF00</code> initcode fail early without executing the initcode. Previously, in both cases the initcode execution would begin and fail on the first undefined instruction <code>EF</code>.</p> <h2 id="test-cases">Test Cases</h2> <p>Creation transaction, <code>CREATE</code> and <code>CREATE2</code> cannot have its <em>code</em> starting with <code>0xEF</code>, but such cases are covered already in <a href="https://wg-eips.ritovision.com/3541/">EIP-3541</a>. However, new cases must be added where <code>CREATE</code> or <code>CREATE2</code> have its <em>initcode</em> being (validly or invalidly) EOF formatted:</p> <table><thead><tr><th>Initcode</th><th>Expected result</th></tr></thead><tbody> <tr><td><code>0xEF</code></td><td>initcode starts execution and fails</td></tr> <tr><td><code>0xEF01</code></td><td>initcode starts execution and fails</td></tr> <tr><td><code>0xEF5f</code></td><td>initcode starts execution and fails</td></tr> <tr><td><code>0xEF00</code></td><td><code>CREATE</code> / <code>CREATE2</code> fails early, returns 0 and keeps sender nonce intact</td></tr> <tr><td><code>0xEF0001</code></td><td>as above</td></tr> <tr><td>valid EOFv1 container</td><td>as above</td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <p>It is the EOF <code>InitcodeTransaction</code> (specified in <a href="https://wg-eips.ritovision.com/7873/">EIP-7873</a>) which needs a detailed review and discussion as that is where external unverified code enters the state. Among others:</p> <ol> <li>Is its complexity under control, ruling out any DoS attempts</li> <li>Is it correctly priced and always charged for</li> <li>Is the validation comprehensive and not allowing problematic code to be saved into the state</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-02-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Charles Cooperhttps://github.com/charles-cooper James Prestwichhttps://github.com/prestwich brockelmorehttps://github.com/brockelmore https://wg-eips.ritovision.com/7609/

Improve the efficiency of TLOAD/TSTORE by decreasing the base cost and introducing a superlinear pricing model.

<h2 id="abstract">Abstract</h2> <p>Decrease the base cost of TLOAD/TSTORE while introducing a superlinear pricing model. This increases the efficiency of TLOAD/TSTORE for common use cases, while providing a pricing model to prevent DoS vectors.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a> introduces a new storage region, termed "transient storage". It behaves like storage (word-addressed and persists between call frames), but unlike storage it is wiped at the end of each transaction. During development of EIP-1153, the pricing was set to be the same as warm storage loads and stores. This was for two reasons: conceptual simplicity of the EIP, and it also addressed concerns about two related DoS vectors: being able to allocate too much transient storage, and the cost of rolling back state in the case of reverts.</p> <p>One of the most important use cases that EIP-1153 enables is cheap reentrancy protection. In fact, if transient storage is cheap enough for the first few slots, reentrancy protection can be enabled by default at the language level without too much burden to users, while simultaneously preventing the largest—and most expensive—class of smart contract vulnerabilities.</p> <p>Furthermore, it seems that transient storage is fundamentally overpriced. Its pricing does not interact with refunds, it only requires a new allocation on contract load (as opposed to memory, which requires a fresh allocation on every call), and has no interaction with the physical database.</p> <p>This EIP proposes a pricing model which charges additional gas per allocation, which is cheaper for common cases (fewer than ~95 slots are written per contract), while making DoS using transient storage prohibitively expensive.</p> <h2 id="specification">Specification</h2> <p>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>The gas cost for <code>TLOAD</code> is proposed to be 5 gas. The gas cost for <code>TSTORE</code> is proposed to be 8 gas + <code>expansion_cost</code>, where <code>expansion_cost</code> is calculated as <code>1 gas * len(transient storage mapping)</code> if the key is not yet in the transient storage mapping, and otherwise 0 gas.</p> <p>In pseudo-code:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">G_LOW</span><span class="z-keyword"> =</span><span class="z-constant"> 5</span></span> <span class="giallo-l"><span class="z-constant">G_MID</span><span class="z-keyword"> =</span><span class="z-constant"> 8</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant">SLOPE</span><span class="z-keyword"> =</span><span class="z-constant"> 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> gas_tload</span><span>(</span><span class="z-variable z-parameter z-function">_key</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> G_LOW</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> gas_tstore</span><span>(</span><span class="z-variable z-parameter z-function">key</span><span>,</span><span class="z-variable z-parameter z-function"> transient_mapping</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> cost</span><span class="z-keyword"> =</span><span class="z-constant"> G_MID</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> key</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> transient_mapping</span><span>:</span></span> <span class="giallo-l"><span> cost</span><span class="z-keyword"> +=</span><span class="z-constant"> SLOPE</span><span class="z-keyword"> *</span><span> transient_mapping</span><span>.</span><span>size</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> cost</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="gas">Gas</h3> <p>In benchmarking, <code>TLOAD</code> was found to cost a similar amount of CPU time as <code>MUL</code>, while <code>TSTORE</code> was found to cost about 1.5x that. The values <code>G_low</code> and <code>G_mid</code> were therefore chosen for <code>TLOAD</code> and <code>TSTORE</code>, respectively.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The maximum number of transient slots which can be allocated on a single contract given 30m gas is approximately 7,739 (solution to <code>x(x-1)/2*1 + 8*x = 30_000_000</code>), which totals 248KB.</p> <p>The maximum number of transient slots which can be allocated in a transaction if you use the strategy of calling new contracts (which each are designed to maximize transient storage allocation) once the cost of <code>TSTORE</code> is more than the cost of calling a cold contract (2600 gas), can be solved for as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>solve for SLOPE * &lt;num slots&gt; == 2600, =&gt; num_slots == 2600</span></span> <span class="giallo-l"><span>gas_used_by_contract = 2600 + SLOPE * num_slots * (num_slots - 1) / 2 + G_MID * num_slots == 3402100</span></span> <span class="giallo-l"><span>block_gas_limit = 30_000_000</span></span> <span class="giallo-l"><span>num_calls_per_txn = block_gas_limit // gas_used_by_contract ~= 8.8</span></span> <span class="giallo-l"><span>max_transient_slots = num_calls_per_txn * num_slots == 22927</span></span></code></pre> <p>Thus, the maximum number of transient slots which can be allocated in a single transaction with this method is roughly 23,000, which totals 736KB. Compared to the current gas schedule (which allows allocating approximately <code>30_000_000 / 100 * 32 == 9.6MB</code> worth of memory), this is a net <em>reduction</em> in the total memory which can be allocated on a client using transient storage, so this EIP presents a stronger bound on the resources which can be used by transient storage. As a comparison point, the total amount of memory which can be allocated on a client by <code>SSTORE</code>s in a given transaction is <code>30_000_000 / 20_000 * 32</code>, or 48KB.</p> <p>Note that this cap scales linearly with the gas limit, which is a useful property when considering future block gas limit increases.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-01-25T00:00:00+00:00 2026-02-11T14:49:28+00:00 Guillaume Ballethttps://github.com/gballet Ansgar Dietrichshttps://github.com/adietrichs Ignacio Hagopianhttps://github.com/jsign Gottfried Heroldhttps://github.com/GottfriedHerold Jamie Lokierhttps://github.com/jlokier Tanishq Jasoriahttps://github.com/tanishqjasoria Parithosh Jayanthihttps://github.com/parithosh Gabriel Rocheleauhttps://github.com/gabrocheleau Karim Taamhttps://github.com/matkt https://wg-eips.ritovision.com/7612/

Describes the use of an overlay tree to use the verkle tree structure, while leaving the historical state untouched.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a method to switch the state tree tree format from hexary Merkle Patricia Tree (MPT) to a Verkle Tree (VKT): the MPT tree is frozen, and new writes to the state are stored in a VKT “laid over” the hexary MPT. The historical MPT state is left untouched and its eventual migration is handled at a later time.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum state is growing, and VKTs offer a good mitigation strategy to stem this growth and enable weak statelessness. Owing to the difficulty of translating contracts with large storage while they are being accessed, proposals for migrating the current MPT state are complex and will require client teams to undergo a long process of refactoring their code to handle this conversion.</p> <p>The bigger the state, the longer any conversion process will take. This has an impact both while the conversion is happening, as well as when full-syncing the chain if the conversion is part of consensus. Fullsync is used extensively by core dev teams to test the performance of new code. A conversion longer than a month will impact the release schedule of client teams who typically release at this rate. Nodes that cannot follow the conversion will need to wait longer to rejoin. The conversion will also make reorgs slower, so reducing its duration is desirable.</p> <p>This current proposal suggests to stop the MPT state growth in its tracks by activating a new “overlay” VKT, that all new state updates are written to. The “base” MPT is frozen in place, until all execution clients are ready to perform the full transition. Data is read first from the overlay tree, and if not found there, from the MPT.</p> <p>Whenever the block that freeze the MPT is finalized, internal node data can be deleted, in order to free up disk space.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="constants">Constants</h3> <table><thead><tr><th>Parameter</th><th>value</th><th>Description</th></tr></thead><tbody> <tr><td><code>FORK_TIME</code></td><td><code>TBD</code></td><td>Time at which the overlay tree is activated.</td></tr> </tbody></table> <h3 id="helper-functions">Helper functions</h3> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Determine if `block` is the fork activation block</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> is_fork_block</span><span>(</span><span class="z-variable z-parameter z-function">block</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> block</span><span>.</span><span>parent</span><span>.</span><span>timestamp</span><span class="z-keyword"> &lt;</span><span class="z-constant"> FORK_TIME</span><span class="z-invalid z-illegal"> &amp;&amp;</span><span> block</span><span>.</span><span>timestamp</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> FORK_TIME</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Write an account in the verkle tree</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> verkle_set_account</span><span>(</span><span class="z-variable z-parameter z-function">tree</span><span>:</span><span> VerkleTree</span><span>,</span><span class="z-variable z-parameter z-function"> key</span><span>:</span><span> Bytes32</span><span>,</span><span class="z-variable z-parameter z-function"> account</span><span>:</span><span> Optional</span><span>[</span><span>Account</span><span>]</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> account</span><span class="z-keyword"> is</span><span class="z-keyword"> not</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> basicdata</span><span class="z-keyword"> =</span><span class="z-support"> bytes</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Version</span></span> <span class="giallo-l"><span> basicdata</span><span class="z-keyword"> +=</span><span class="z-support"> bytes</span><span>(</span><span class="z-constant">4</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Reserved</span></span> <span class="giallo-l"><span> basicdata</span><span class="z-keyword"> +=</span><span class="z-support"> len</span><span>(</span><span>account</span><span>.</span><span>code</span><span>)</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">3</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> basicdata</span><span class="z-keyword"> +=</span><span> account</span><span>.</span><span>nonce</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">8</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> basicdata</span><span class="z-keyword"> +=</span><span> account</span><span>.</span><span>balance</span><span>.</span><span>to_bytes</span><span>(</span><span class="z-constant">16</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> tree</span><span>.</span><span>set</span><span>(</span><span>key</span><span>,</span><span> basicdata</span><span>)</span></span> <span class="giallo-l"><span> ckkey</span><span class="z-keyword"> =</span><span> key</span></span> <span class="giallo-l"><span> ckkey</span><span>[</span><span class="z-constant">31</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> CODEHASH_LEAF_KEY</span></span> <span class="giallo-l"><span> tree</span><span>.</span><span>set</span><span>(</span><span>ckkey</span><span>,</span><span> account</span><span>.</span><span>code_hash</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Reads an account from the verkle tree</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> verkle_get_account</span><span>(</span><span class="z-variable z-parameter z-function">tree</span><span>:</span><span> VerkleTree</span><span>,</span><span class="z-variable z-parameter z-function"> key</span><span>:</span><span> Bytes32</span><span>)</span><span> -&gt;</span><span> Optional</span><span>[</span><span>Account</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> basicdata_leaf</span><span class="z-keyword"> =</span><span> tree</span><span>.</span><span>get</span><span>(</span><span>key</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> basicdata_leaf</span><span class="z-keyword"> is</span><span class="z-keyword"> not</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> cs</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>basicdata_leaf</span><span>[</span><span class="z-constant">5</span><span>:</span><span class="z-constant">8</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> nonce</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>basicdata_leaf</span><span>[</span><span class="z-constant">8</span><span>:</span><span class="z-constant">16</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> balance</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>.</span><span>from_bytes</span><span>(</span><span>basicdata_leaf</span><span>[</span><span class="z-constant">16</span><span>:</span><span class="z-constant">32</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">big</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> ckkey</span><span class="z-keyword"> =</span><span> key</span></span> <span class="giallo-l"><span> ckkey</span><span>[</span><span class="z-constant">31</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> CODEHASH_LEAF_KEY</span></span> <span class="giallo-l"><span> ck</span><span class="z-keyword"> =</span><span> tree</span><span>.</span><span>get</span><span>(</span><span>ckkey</span><span>)</span></span> <span class="giallo-l"><span> cskey</span><span class="z-keyword"> =</span><span> key</span></span> <span class="giallo-l"><span> cskey</span><span>[</span><span class="z-constant">31</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> CODE_SIZE_LEAF_KEY</span></span> <span class="giallo-l"><span> cs</span><span class="z-keyword"> =</span><span> tree</span><span>.</span><span>get</span><span>(</span><span>cskey</span><span>)</span></span> <span class="giallo-l"><span> account</span><span class="z-keyword"> =</span><span> Account</span><span>(</span><span class="z-constant">0</span><span>,</span><span> balance</span><span>,</span><span> nonce</span><span>,</span><span> ck</span><span>,</span><span> cs</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> account</span></span></code></pre><h3 id="changes-to-the-execution-spec">Changes to the execution spec</h3> <p>In the execution spec, modify the <code>State</code> class as such:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-entity z-name">@</span><span class="z-entity z-name">dataclass</span></span> <span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> State</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"><span class="z-string"> Contains all information that is preserved between transactions.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;&quot;&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _main_trie</span><span>:</span><span> Trie</span><span>[</span><span>Address</span><span>,</span><span> Optional</span><span>[</span><span>Account</span><span>]</span><span>]</span><span class="z-keyword"> =</span><span> field</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> default_factory</span><span class="z-keyword">=</span><span class="z-storage z-type">lambda</span><span>:</span><span> Trie</span><span>(</span><span class="z-variable">secured</span><span class="z-keyword">=</span><span class="z-constant">True</span><span>,</span><span class="z-variable"> default</span><span class="z-keyword">=</span><span class="z-constant">None</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> _storage_tries</span><span>:</span><span> Dict</span><span>[</span><span>Address</span><span>,</span><span> Trie</span><span>[</span><span>Bytes</span><span>,</span><span> U256</span><span>]</span><span>]</span><span class="z-keyword"> =</span><span> field</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> default_factory</span><span class="z-keyword">=</span><span class="z-support">dict</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> _snapshots</span><span>:</span><span> List</span><span>[</span></span> <span class="giallo-l"><span> Tuple</span><span>[</span></span> <span class="giallo-l"><span> Trie</span><span>[</span><span>Address</span><span>,</span><span> Optional</span><span>[</span><span>Account</span><span>]</span><span>]</span><span>,</span><span> Dict</span><span>[</span><span>Address</span><span>,</span><span> Trie</span><span>[</span><span>Bytes</span><span>,</span><span> U256</span><span>]</span><span>]</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> ]</span><span class="z-keyword"> =</span><span> field</span><span>(</span><span class="z-variable">default_factory</span><span class="z-keyword">=</span><span class="z-support">list</span><span>)</span></span> <span class="giallo-l"><span> _created_accounts</span><span>:</span><span> Set</span><span>[</span><span>Address</span><span>]</span><span class="z-keyword"> =</span><span> field</span><span>(</span><span class="z-variable">default_factory</span><span class="z-keyword">=</span><span class="z-support">set</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Added in this EIP</span></span> <span class="giallo-l"><span> _overlay_tree</span><span>:</span><span> VerkleTree</span><span>[</span><span>Address</span><span>,</span><span> Bytes32</span><span>]</span></span></code></pre> <p>And the state access functions are modified as such:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> get_account_optional</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> State</span><span>,</span><span class="z-variable z-parameter z-function"> address</span><span>:</span><span> Address</span><span>)</span><span> -&gt;</span><span> Optional</span><span>[</span><span>Account</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> account</span><span class="z-keyword"> =</span><span> verkle_get_account</span><span>(</span><span>state</span><span>.</span><span>_overlay_tree</span><span>,</span><span> get_tree_key_for_version</span><span>(</span><span>addr</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> account</span><span class="z-keyword"> is</span><span class="z-keyword"> not</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> account</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> trie_get</span><span>(</span><span>state</span><span>.</span><span>_main_trie</span><span>,</span><span> address</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> set_account</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> State</span><span>,</span><span class="z-variable z-parameter z-function"> address</span><span>:</span><span> Address</span><span>,</span><span class="z-variable z-parameter z-function"> account</span><span>:</span><span> Optional</span><span>[</span><span>Account</span><span>]</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> verkle_set_account</span><span>(</span><span>state</span><span>.</span><span>_overlay_tree</span><span>,</span><span> get_tree_key_for_nonce</span><span>(</span><span>addr</span><span>)</span><span>,</span><span> account</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> get_storage</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> State</span><span>,</span><span class="z-variable z-parameter z-function"> address</span><span>:</span><span> Address</span><span>,</span><span class="z-variable z-parameter z-function"> key</span><span>:</span><span> Bytes</span><span>)</span><span> -&gt;</span><span> U256</span><span>:</span></span> <span class="giallo-l"><span> value</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>_overlay_tree</span><span>.</span><span>get</span><span>(</span><span>get_tree_key_for_storage_slot</span><span>(</span><span>addr</span><span>,</span><span> slot</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> value</span><span class="z-keyword"> is</span><span class="z-keyword"> not</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> value</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> trie</span><span class="z-keyword"> =</span><span> state</span><span>.</span><span>_storage_tries</span><span>.</span><span>get</span><span>(</span><span>address</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> trie</span><span class="z-keyword"> is</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> U256</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> value</span><span class="z-keyword"> =</span><span> trie_get</span><span>(</span><span>trie</span><span>,</span><span> key</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> isinstance</span><span>(</span><span>value</span><span>,</span><span> U256</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> value</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> set_storage</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-parameter z-function"> state</span><span>:</span><span> State</span><span>,</span><span class="z-variable z-parameter z-function"> address</span><span>:</span><span> Address</span><span>,</span><span class="z-variable z-parameter z-function"> key</span><span>:</span><span> Bytes</span><span>,</span><span class="z-variable z-parameter z-function"> value</span><span>:</span><span> U256</span></span> <span class="giallo-l"><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>_overlay_tree</span><span>.</span><span>set</span><span>(</span><span>get_tree_key_for_storage_slot</span><span>(</span><span>addr</span><span>,</span><span> slot</span><span>)</span><span>,</span><span> value</span><span>)</span></span></code></pre> <p>Add the following function which is used when storing a contract in the tree:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> state_set_codechunk</span><span>(</span><span class="z-variable z-parameter z-function">state</span><span>:</span><span> State</span><span>,</span><span class="z-variable z-parameter z-function"> addr</span><span>:</span><span> Address</span><span>,</span><span class="z-variable z-parameter z-function"> chunk_num</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> chunk</span><span>:</span><span> Bytes</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> state</span><span>.</span><span>_overlay_tree</span><span>.</span><span>set</span><span>(</span><span>get_tree_key_for_code_chunk</span><span>(</span><span>addr</span><span>,</span><span> chunk_num</span><span>)</span><span>,</span><span> chunk</span><span>)</span></span></code></pre><h3 id="changes-to-the-block-header">Changes to the block header</h3> <p>At <code>FORK_TIME</code> the block header state root is changed from the MPT root to the VKT root.</p> <h2 id="rationale">Rationale</h2> <p>This approach doesn't convert the state, which is left to a subsequent EIP. This is meant as a stopgap in case we decide to push the conversion itself to a later time. It has the advantage of simplicity, which means that the Verge fork could happen at the same time as other, simpler EIPs. It also requires no change at the consensus layer.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <!-- This section is optional for non-Core EIPs. The Test Cases section should include expected input/output pairs, but may include a succinct set of executable tests. It should not include project build files. No new requirements may be introduced here (meaning an implementation following only the Specification section should pass all tests here.) If the test suite is too large to reasonably be included inline, then consider adding it as one or more files in `../assets/eip-####/`. External links will not be allowed TODO: Remove this comment before submitting --> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li><code>transition-post-genesis</code> branch in <code>github.com/gballet/go-ethereum</code> implements this when setting <code>--override.overlay-stride=0</code> on the command line.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <!-- All EIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. For example, include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. EIP submissions missing the "Security Considerations" section will be rejected. An EIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers. The current placeholder is acceptable for a draft. TODO: Remove this comment before submitting --> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2024-01-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Marius van der Wijdenhttps://github.com/MariusVanDerWijden https://wg-eips.ritovision.com/7591/

Introduces a new transaction type signed with BLS signatures

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction type that is signed with BLS signatures.</p> <h2 id="motivation">Motivation</h2> <p>The BLS signature scheme allows for easy aggregation and verification of aggregated signatures. If a substantial number of transactions on mainnet were BLS signed transactions, we can aggregate signatures in a block and batch-verify them. This will reduce growth of the chain history.</p> <h2 id="specification">Specification</h2> <p>BLS_TX_TYPE = Bytes1(0x04)</p> <h3 id="transaction-type">Transaction Type</h3> <p>The transaction type will have the following format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, value, data, access_list, sender, signature]</span></span></code></pre> <p>with <code>sender</code> being the BLS public key of an account with address <code>address = [0:20](keccak256(sender))</code>.</p> <p>The signature value <code>signature</code> is calculated by constructing a BLS signature over the following digest:</p> <p><code>tx_hash = keccak256(BLS_TX_TYPE || rlp([chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, value, data, access_list, sender]))</code>.</p> <h3 id="header-changes">Header changes</h3> <p>The block header will be amended with the <code>aggregated_sig</code> field, containing an aggregated signature of all BLS transactions in the block.</p> <p>The resulting RLP encoding of the header is therefore:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>rlp([</span></span> <span class="giallo-l"><span> parent_hash,</span></span> <span class="giallo-l"><span> 0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347, # ommers hash</span></span> <span class="giallo-l"><span> coinbase,</span></span> <span class="giallo-l"><span> state_root,</span></span> <span class="giallo-l"><span> txs_root,</span></span> <span class="giallo-l"><span> receipts_root,</span></span> <span class="giallo-l"><span> logs_bloom,</span></span> <span class="giallo-l"><span> 0, # difficulty</span></span> <span class="giallo-l"><span> number,</span></span> <span class="giallo-l"><span> gas_limit,</span></span> <span class="giallo-l"><span> gas_used,</span></span> <span class="giallo-l"><span> timestamp,</span></span> <span class="giallo-l"><span> extradata,</span></span> <span class="giallo-l"><span> prev_randao,</span></span> <span class="giallo-l"><span> 0x0000000000000000, # nonce</span></span> <span class="giallo-l"><span> base_fee_per_gas,</span></span> <span class="giallo-l"><span> withdrawals_root,</span></span> <span class="giallo-l"><span> blob_gas_used,</span></span> <span class="giallo-l"><span> excess_blob_gas,</span></span> <span class="giallo-l"><span> aggregated_sig,</span></span> <span class="giallo-l"><span>])</span></span></code></pre><h3 id="block-changes">Block changes</h3> <p>The block building algorithm needs to be changed in order to built the aggregated signature of all BLS signed transactions in the block. All transactions in the block will be added without the signature field set.</p> <p>Blocks with transactions containing the <code>signature</code> field MUST be rejected.</p> <p>On block verification, the <code>verifyAggregate</code> algorithm is used as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>valid = verifyAggregate(sender_1, ... sender_n, tx_hash_1, ... tx_hash_n, aggregated_sig)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Removing the ECDSA signature from a transaction saves 65 bytes. The BLS public key is 48 bytes, the aggregated signature is 96 bytes. Thus we save <code>-96 + (65-48)* #transactions</code> bytes per block. With ~7000 blocks per day, 1.000.000 transactions per day, the average block contains roughly 150 transactions.</p> <p>Thus we would save 2454 bytes or 2.4KB per block. This would equate to ~1.5% saving given an average block size of 160KB.</p> <p>In addition to the (admittedly meager) size savings for full nodes, the ability to add a new transaction type to utilize a different signature scheme does have some merit to it. This proposal shows that it would be possible to add for example a quantum safe signature scheme to ethereum.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backward incompatible changes to the block validation rule set on the execution layer and introduces a new transaction type and a new header field. Thus a hardfork is needed.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The messages signed via BLS are distinct (no hash collisions on the txhash), thus the aggregation is secure even without a proof-of-possession. The public keys are not distinct which is not a problem in BLS.</p> <p>We assume that keccak256 and ECDSA and BLS are working as intended. Suppose we have two addresses <code>address_1 = keccak256(pk_ecdsa)</code> and <code>address_2 = keccak(pk_bls)</code> with <code>address_1 == address_2</code>. We know that <code>pk_ecdsa</code> must be equal to <code>pk_bls</code> (follows from keccak). This would mean that we would either be able to find <code>x</code> with <code>g_bls^x = y</code> for a given <code>y</code> (violates the security of BLS) or find <code>z</code> with <code>d_ecdsa^z = y</code> (violates the security of ECDSA).</p> <p>Thus it would be impossible (with greater than negligble probability) to find two private keys, one in ECDSA and one in BLS that control the same account.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-12-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 danceratopzhttps://github.com/danceratopz Ahmad Bitarhttps://github.com/smartprogrammer93 https://wg-eips.ritovision.com/7577/

Use a versioning scheme for EIPs based on changes made to their Specification section.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a versioning scheme for <a href="https://wg-eips.ritovision.com/1/#eip-types">Standards Track</a> EIPs by applying <a href="https://wg-eips.ritovision.com/7577/assets/semver/">Semantic Versioning 2.0.0</a> based on changes made to the EIP's Specification section once its status has changed from <code>Draft</code> to <code>Review</code>.</p> <h2 id="motivation">Motivation</h2> <p>EIP specifications often receive increasing modifications as more people review them, which is generally the case as client teams start implementing the specifications and the community gains a better understanding of their interaction with the rest of the protocol. These changes can be difficult to track. In particular, as EVM reference tests are often not maintained (and generally not released) by client teams or the EIP's authors, it can be difficult to ascertain whether a release of reference tests is sufficient, or even valid, to test the latest version of an EIP's specifications or the specification as currently implemented by a client.</p> <p>This EIP proposes a semantic versioning scheme and an addition of a CHANGELOG section for EIPs that enables clearer communication within the community and allows the scope of a change to be ascertained at first glance. Furthermore, client implementation and testing toolchains can query EIP changes and automatically flag incompatibilities between the EIP's current specification and between client and test implementations.</p> <h2 id="specification">Specification</h2> <p>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>Once an EIP has moved out of "Draft" status, it MUST use the EIP versioning scheme outlined below. It MAY already use the versioning scheme in "Draft" status, which could be useful if the specification is actively being implemented. If more than one team is implementing the specification, it is RECOMMENDED to change the EIP's status to "Review".</p> <p>The EIP versioning scheme MUST apply the following semantic versioning scheme of <code>MAJOR.MINOR.PATCH</code>, based on <a href="https://wg-eips.ritovision.com/7577/assets/semver/">Semantic Versioning 2.0.0</a>:</p> <ol> <li><code>MAJOR</code>: A breaking change to the specifications that requires an implementation change and a change to the reference tests.</li> <li><code>MINOR</code>: An addition to the specifications that requires additional implementation and additional test coverage to be added to the reference tests.</li> <li><code>PATCH</code>: Any cosmetic change to, or a reformulation of, the EIP without specification change.</li> </ol> <p>Before the EIP has moved out of Draft status and is being versioned, the version number MUST initially have <code>MAJOR</code> version <code>0</code>.</p> <p>For every change made to an EIP via a pull request (PR) made to ethereum/EIPs, a new entry MUST be added to the CHANGELOG section of the EIP that outlines the changes made within the PR. This CHANGELOG entry MUST include the following:</p> <ol> <li>A new version number that follows the semantic versioning scheme outlined above.</li> <li>The date when the changes were introduced.</li> <li>The ethereum/EIPs PR number that implements the changes.</li> <li>A line for each change made to the EIP's specifications that includes a short description of the change.</li> </ol> <p>Additionally, the new version MUST be added to the metadata header of the EIP's markdown file (to a new "version" field), so that it may be easily parsed.</p> <p>Tooling MUST be added to the ethereum/EIPs repository to help EIP authors apply the versioning scheme. This tooling SHOULD automatically:</p> <ol> <li>Update the EIP version in the metadata header of the EIP's markdown file. If the EIP's status is changed from "Draft" to "Review", the version MUST be updated to <code>1.0.0</code>.</li> <li>Add a new CHANGELOG entry based on the EIP Version and the PR's title.</li> </ol> <p>To allow the tooling to make these changes, the EIP author MUST indicate the scope of change in one of the commit messages pushed to the PR's branch. The scope is indicated by starting a commit message with ("<code>[Mm]ajor:</code>", "<code>[Mm]inor:</code>", or "<code>[Pp]atch</code>"). Multiple commit messages may contain scopes; in this case, the most severe scope change will be applied. If no scope can be detected in any of the commit messages, merging of the PR is blocked until such a commit message is pushed to the PR.</p> <h2 id="rationale">Rationale</h2> <p>Making the version available in the EIP's metadata header allows for programmatic parsing of the version number by tooling used in reference tests or by client teams. Currently, the execution-spec-tests repository, which contains consensus tests for Ethereum execution clients, implements a rudimentary EIP version checker: EIP spec tests are required to declare the EIP's markdown file digest SHA that the test implementation was based on. The current value of the digest SHA is then polled via the Github API to verify that no changes have occurred since the test implementation. While this provides a warning to test implementers that the EIP has changed, it is clearly of limited use.</p> <p>A richer versioning scheme, as defined by this EIP, can provide a lot of value to the testing toolchain. Client teams can provide an interface that reports the EIP version currently implemented and reference tests can specify the version they implement in generated tests as metadata. This allows a test runner to mark tests to xfail (expectedly fail) and issue a warning if the <code>MAJOR</code> or <code>MINOR</code> versions don't match. It would even be possible to automatically select the correct version of the reference tests to run against a client implementation, although given the pace of Ethereum development, it will likely be impractical to maintain and track multiple versions of tests.</p> <h3 id="case-study">Case Study</h3> <p>This section explores how the versioning scheme would be applied to an existing EIPs recently under active development at the time of writing as an example.</p> <p>The history of <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a> contains many changes to its specification. EIP-4788 was updated to status "Review" on 2023-11-28. This case study assumes, however, that the EIP moved to status "Review" as of 2023-04-11 and updated to version 1.0.0 due to the start of a client team implementation.</p> <h4 id="changelog">Changelog</h4> <ul> <li>9.0.1 - 2023-09-26: Update ring buffer size rationale for new ring buffer size, #7786.</li> <li>9.0.0 - 2023-09-26: Post audit tweaks, #7672. <ul> <li>Verify timestamp is non-zero.</li> <li>Make <code>HISTORY_BUFFER_LENGTH</code> prime (8191).</li> <li>Load calldata once.</li> <li>Update <code>BEACON_ROOTS_ADDRESS</code>.</li> </ul> </li> <li>8.0.1 - 2023-08-28: 4788 cleanups, #7532.</li> <li>8.0.0 - 2023-08-24: Initial stab at v2, #7456. <ul> <li>Require timestamp input to be exactly 32 bytes.</li> <li>Revert if timestamp input does not match stored value (instead of returning zeroed word).</li> <li>Remove precompile concept, use regular smart contract with provided bytecode.</li> </ul> </li> <li>7.0.3 - 2023-08-01: Mention genesis block with no existing beacon block root case, #7445.</li> <li>7.0.2 - 2023-07-07: Explicitly specify header schema, #7297.</li> <li>7.0.1 - 2023-07-07: Fix typo, #7293.</li> <li>7.0.0 - 2023-07-05: Bound precompile storage, #7178.</li> <li>6.0.1 - 2023-06-13: Clarify header and validity sections, #7179.</li> <li>6.0.0 - 2023-06-12: Update precompile address, #7173.</li> <li>5.0.0 - 2023-05-31: Key beacon roots by root, #7107.</li> <li>4.0.0 - 2023-05-24: Favor stateful precompile over opcode, #7065.</li> <li>3.0.0 - 2023-05-17: Send current slot from CL to avoid timestamp conversions, #7037.</li> <li>2.0.1 - 2023-05-15: Fix typo, #7005.</li> <li>2.0.0 - 2023-05-03: Update opcode to avoid clash, #6980.</li> <li>1.0.1 - 2023-04-13: Minor nits, #6870.</li> <li>1.0.0 - 2023-04-11: Use block roots; update to status "Draft", #6859. <ul> <li>Update to "Draft" due to client implementation (NethermindEth/nethermind#5476).</li> <li>Use block roots instead of state roots.</li> <li>Roots are stored keyed by slot.</li> <li>Use of ring buffer in state.</li> <li>Use header timestamps to derive slot numbers, rather than consume additional header space.</li> </ul> </li> <li>0.2.1 - 2023-02-04: Update to status "Stagnant", #6432.</li> <li>0.2.0 - 2022-06-29: Rename "beacon block root" to "beacon state root", #5090.</li> <li>0.1.1 - 2022-05-06: Force usage of included LICENSE file, #5055.</li> <li>0.1.0 - 2022-02-17: Add EIP-4788: Beacon state root in EVM, #4788.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>It is not necessary to retroactively add a CHANGELOG or versions for versions of the EIP prior to the introduction of this EIP. Upon the next change to the EIP's Specification section, the author MUST introduce a CHANGELOG section and a version number that follows the semantic versioning scheme outlined above.</p> <h2 id="security-considerations">Security Considerations</h2> <p>None.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-10-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 mikehttps://github.com/michaelneuder Vitalikhttps://github.com/vbuterin Francescohttps://github.com/fradamt Terencehttps://github.com/terencechain potuzhttps://github.com/potuz Manavhttps://github.com/manav2401 https://wg-eips.ritovision.com/7547/

Add an inclusion list mechanism to allow forced transaction inclusion.

<h2 id="abstract">Abstract</h2> <p>Censorship resistance is a core value proposition of blockchains. Inclusion lists aim to provide a mechanism to improve the censorship resistance of Ethereum by allowing proposers to specify a set of transactions that must be promptly included for subsequent blocks to be considered valid.</p> <h2 id="motivation">Motivation</h2> <p>Since the merge, validators have started outsourcing almost all block production to a specialized set of builders who compete to extract the most MEV (this is commonly referred to as Proposer-Builder Separation). As of October 2023, nearly 95% of blocks are built by builders rather than the proposer. While it is great that all proposers have access to competitive blocks through the <code>mev-boost</code> ecosystem, a major downside of externally built blocks is the fact that the builders ultimately decide what transactions to include or exclude. Without any forced transaction inclusion mechanism, the proposer is faced with a difficult choice: they either have no say on the transactions that get included, or they build the block locally (thus have the final say on transactions) and sacrifice some MEV rewards.</p> <p>Inclusion lists aim to allow proposers to retain some authority by providing a mechanism by which transactions can be forcibly included. The simplest design is for the <code>slot N</code> proposer to specify a list of transactions that must be included in the block that is produced for their slot. However, this is not incentive-compatible because builders may choose to abstain from building blocks if the proposer sets some constraints on their behavior. This leads to the idea of "forward" inclusion lists, where the transactions specified by the <code>slot N</code> proposer are enforced in the <code>slot N+1</code> block. The naïve implementation of the forward inclusion lists presents a different issue of potentially exposing free data availability, which could be exploited to bloat the size of the chain without paying the requisite gas costs. The free data availability problem is solved with observations about nonce reuse and allowing multiple inclusion lists to be specified for each slot. With the incentive compatibility and free data availability problems addressed, we can more safely proceed with the implementation of inclusion lists.</p> <h2 id="specification">Specification</h2> <h3 id="constants">Constants</h3> <table><thead><tr><th>Name</th><th>Value</th></tr></thead><tbody> <tr><td><code>MAX_TRANSACTIONS_PER_INCLUSION_LIST</code></td><td><code>2**4 = 16</code></td></tr> <tr><td><code>MAX_GAS_PER_INCLUSION_LIST</code></td><td><code>2**21</code></td></tr> <tr><td><code>MIN_SLOTS_FOR_INCLUSION_LIST_REQUEST</code></td><td><code>1</code></td></tr> </tbody></table> <h4 id="reference-objects">Reference Objects</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>class InclusionListSummaryEntry(Container):</span></span> <span class="giallo-l"><span> address: ExecutionAddress</span></span> <span class="giallo-l"><span> gas_limit: uint64</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>class InclusionListSummary(Container)</span></span> <span class="giallo-l"><span> slot: Slot</span></span> <span class="giallo-l"><span> proposer_index: ValidatorIndex</span></span> <span class="giallo-l"><span> summary: List[InclusionListSummaryEntry, MAX_TRANSACTIONS_PER_INCLUSION_LIST]</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>class SignedInclusionListSummary(Container):</span></span> <span class="giallo-l"><span> message: InclusionListSummary</span></span> <span class="giallo-l"><span> signature: BLSSignature</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>class InclusionList(Container)</span></span> <span class="giallo-l"><span> summary: SignedInclusionListSummary</span></span> <span class="giallo-l"><span> transactions: List[Transaction, MAX_TRANSACTIONS_PER_INCLUSION_LIST]</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>class ExecutionPayload(Container):</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> inclusion_list_summary: List[InclusionListSummaryEntry, MAX_TRANSACTIONS_PER_INCLUSION_LIST]</span></span> <span class="giallo-l"><span> inclusion_list_exclusions: List[uint64, MAX_TRANSACTIONS_PER_INCLUSION_LIST]</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>class ExecutionPayloadHeader(Container):</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> inclusion_list_summary_root: Root</span></span> <span class="giallo-l"><span> inclusion_list_exclusions_root: Root</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>class BeaconBlockBody(Container):</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> inclusion_list_summary: SignedInclusionListSummary</span></span></code></pre><h3 id="consensus-layer">Consensus layer</h3> <h4 id="high-level-overview">High-level overview</h4> <p><strong><code>slot N</code> proposal:</strong></p> <ul> <li>Proposer broadcasts a signed block and an inclusion list (summary and transactions objects) for <code>slot N+1</code>.</li> <li>Transactions will be included in <code>slot N</code> or <code>slot N+1</code>.</li> <li>Summaries include the originating address of the transactions and their respective gas limits.</li> <li>Summaries are signed, but transactions are not.</li> </ul> <p><strong><code>slot N</code> validation:</strong></p> <ul> <li>Validators only consider the block for validation and fork-choice if they have seen at least one inclusion list for that slot.</li> <li>They consider the block invalid if the inclusion list transactions are not executable at the start of <code>slot N</code> or if the transactions' <code>maxFeePerGas</code> are not at least 12.5% higher than the current slot (to ensure the transactions will be valid in <code>slot N+1</code>).</li> </ul> <p><strong><code>slot N+1</code> validation:</strong></p> <ul> <li>The proposer for <code>slot N+1</code> builds their block along with a signed summary from the <code>slot N</code> proposer.</li> <li>The payload includes a list of transaction indices from the <code>slot N</code> payload that satisfy some entry in the signed inclusion list summary.</li> <li>The payload is considered valid if: (a) the execution conditions are met, including satisfying the inclusion list summary and being executable from the execution layer perspective, and (b) the consensus conditions are met with a proposer signature of the previous block.</li> </ul> <h4 id="specific-changes">Specific Changes</h4> <p><strong>Beacon chain state transition spec:</strong></p> <ul> <li><em><strong>New</strong> <code>inclusion_list</code> object:</em> Introduce a new <code>inclusion_list</code> for the proposer to submit and nodes to process.</li> <li><em><strong>Modified</strong> <code>ExecutionPayload</code> and <code>ExecutionPayloadHeader</code> objects:</em> Update these objects to meet the inclusion list requirements.</li> <li><em><strong>Modified</strong> <code>BeaconBlockBody</code>:</em> Modified to cache the inclusion list summary.</li> <li><em><strong>Modified</strong> <code>process_execution_payload</code> function:</em> Update this process to include checks for the inclusion list summary satisfaction.</li> </ul> <p><strong>Beacon chain fork-choice spec:</strong></p> <ul> <li><em><strong>New</strong> <code>is_inclusion_list_available</code> check:</em> Introduce a new check to determine if the inclusion list is available within the visibility window.</li> <li><em><strong>New</strong> notification action:</em> Implement a new call to notify the Execution Layer (EL) client about a new inclusion list. The corresponding block is considered invalid if the EL client deems the inclusion list invalid.</li> </ul> <p><strong>Beacon chain P2P spec:</strong></p> <ul> <li><em><strong>New</strong> gossipnet and validation rules for inclusion list:</em> Define new rules for handling the inclusion list in the gossip network and validation.</li> <li><em><strong>New</strong> RPC request and response network for inclusion list:</em> Establish a new network for sending and receiving inclusion lists.</li> </ul> <p><strong>Validator spec:</strong></p> <ul> <li><em><strong>New</strong> duty for <code>inclusion_list</code>:</em> Proposer to prepare and sign the inclusion list.</li> <li><em><strong>Modified</strong> duty for <code>BeaconBlockBody</code>:</em> Update the duty to prepare the beacon block body to include the <code>inclusion_list_summary</code>.</li> </ul> <h3 id="execution-layer">Execution layer</h3> <ul> <li><em><strong>New</strong> <code>get_inclusion_list</code>:</em> Introduce a new function for proposers to retrieve inclusion lists.</li> <li><em><strong>New</strong> <code>new_inclusion_list</code>:</em> Define a new function for nodes to validate the execution side of the inclusion list.</li> <li><em><strong>Modified</strong> <code>forkchoice_updated</code>:</em> Update the function with a <code>payload_attribute</code> to include the inclusion list summary as part of the attribute.</li> <li><em><strong>Modified</strong> <code>new_payload</code>:</em> Update the function for EL clients to verify that <code>payload_transactions</code> satisfy <code>payload.inclusion_list_summary</code> and <code>payload.inclusion_list_exclusions</code>.</li> <li><em><strong>New</strong> validation rules:</em> Implement new validation rules based on the changes introduced in the Execution-API spec.</li> </ul> <h2 id="rationale">Rationale</h2> <p>We consider a few design decisions present in this EIP.</p> <ol> <li><code>ReducedSummary</code> versus <code>Summary</code> <ul> <li>The original proposal tries to improve data efficiency by using a <code>ReducedSummary</code> and a <code>Rebuilder</code>. This allows the full summary to be reconstructed.</li> <li>This adds a lot of complexity to the spec, so in this initial version, we should consider just using the regular <code>Summary</code> and including that in the subsequent block.</li> </ul> </li> <li>Gas limit vs no limit. <ul> <li>One consideration is whether the inclusion list should have a gas limit or use the block’s gas limit.</li> <li>Having a separate gas limit simplifies complexity but opens up the possibility for validators to outsource their inclusion list construction for side payments (e.g., if a block is full, the proposer could auction off space in the inclusion list for guaranteed inclusion in the subsequent block).</li> <li>Alternatively, inclusion lists could be part of the block gas limit and only satisfied if the block gas limit is not full. However, this could lead to situations where the next block proposer intentionally fills up the block to ignore the inclusion list, albeit at the potential expense of paying to waste the gas.</li> </ul> </li> <li>Inclusion list ordering. <ul> <li>We assume that the inclusion list is processed at the top of the <code>slot N</code> block. Transactions in the inclusion list are evaluated for the pre-state of <code>slot N</code> but are only guaranteed to be included in <code>slot N+1</code>.</li> </ul> </li> <li>Inclusion list transaction exclusion. <ul> <li>Inclusion list transactions proposed at <code>slot N</code> may be satisfied in the same slot (e.g., by being included in the <code>ExecutionPayload</code>). This is a side effect of validators using <code>mev-boost</code> because they don’t know the contents of the block they propose.</li> <li>Due to this, there exists an exclusion field, a node looks at each transaction in the payload’s <code>inclusion_list_exclusion</code> field and makes sure it matches with a transaction in the current inclusion list. When there’s a match, we remove that transaction from the inclusion list summary.</li> </ul> </li> <li><code>mev-boost</code> compatibility. <ul> <li>There are no significant changes to <code>mev-boost</code>. Like any other hard fork, <code>mev-boost</code>, relays, and builders must adjust their beacon nodes.</li> <li>Builders must know that execution payloads that don’t satisfy the inclusion list summary will be invalid.</li> <li>Relays may have additional duties to verify such constraints before passing them to validators for signing.</li> <li>When receiving the header, validators can check that the <code>inclusion_list_summary_root</code> matches their local version and skip building a block if there’s a mismatch, using the local block instead.</li> </ul> </li> <li>Syncing using by range or by root. <ul> <li>To consider a block valid, a node syncing to the latest head must also have an inclusion list.</li> <li>A block without an inclusion list cannot be processed during syncing.</li> <li>To address this, there is a parameter called <code>MIN_SLOTS_FOR_INCLUSION_LIST_REQUEST</code>. A node can skip inclusion list checks if the block’s slot plus this parameter is lower than the current slot.</li> <li>This is similar to <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>, where a node skips blob sidecar data availability checks if it’s outside the retention window.</li> </ul> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backward incompatible changes to the block validation rule set on the consensus layer and must be accompanied by a hard fork. These changes do not break anything related to current user activity and experience.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The main potential issue is around the incentivization of the inclusion lists. If the <code>slot N</code> proposer constructs an inclusion list that negatively impacts the rewards of the <code>slot N+1</code> proposer, the <code>slot N+1</code> proposer may attempt to bribe the <code>slot N</code> proposer to publish an empty list. This isn't a direct attack on the protocol, but rather a profit-sharing mechanism by which the inclusion list would go unutilized. It seems likely these commitment games could be played no matter the censorship resistance scheme in place, but this remains an active area of research.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-10-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 1m1https://github.com/1m1-github https://wg-eips.ritovision.com/7543/

This EIP adds OPCODEs to allow arbitrary precision decimal float calculation of all elementary functions with precise gas enumeration.

<h2 id="abstract">Abstract</h2> <p>This EIP adds <em>arbitrary precision decimal float</em> OPCODEs for arithmetic via DECADD, DECNEG, DECMUL, DECINV and expression of all elementary functions via DECEXP, DECLN, DECSIN. All decimal values upto the maximal precision allowed by a int256 coefficient and exponent are represented exactly, as c*10^q. All implemented algorithms converge for all inputs given enough precision, as chosen by the user. All calculations are deterministic and gas is precisely embedded bottom-up. Allowing arbitrary precision decimal elementary functions invites the worlds of mathematical finance, machine learning, science, digital art, games and others to Ethereum. The implementation is functional.</p> <h2 id="motivation">Motivation</h2> <p>Currently, to take a power, a^b, of non integer values, requires vast amounts of Solidity code. The simplest task in trading e.g. is to convert volatilities from yearly to daily, which involves taking the 16th root.</p> <p>Giving users/devs the same ability that scientific calculators have allows for the creation of apps with higher complexity.</p> <p>The files <a href="https://wg-eips.ritovision.com/7543/./assets/BlackScholes.yul">BlackScholes.yul</a> and <a href="https://wg-eips.ritovision.com/7543/./assets/Neuron.yul">Neuron.yul</a> demonstrate how these OPCODEs simplify numerical smart contract code.</p> <h3 id="why-decimal">Why decimal?</h3> <p>To represent a simple value like 0.1 in binary requires infinite many digits and is therefore not exactly represently in a finite binary machine. Decimal types are much closer to the vast majority of numerical calculations run by humans.</p> <h3 id="evm">eVm</h3> <p>The EVM is a virtual machine and thereby not restricted by hardware. Usually, assembly languages provide OPCODES that are mimic the ability of hardware. In a virtual machine, we have no such limitations and nothing stops us from adding more complex OPCODEs, as long as fair gas is provided. At the same time, we do not want to clutter the OPCODEs library. EXP, LN and SIN are universal functions that open the path to: powers, trigonometry, integrals, differential equations, machine learning, digital art, etc.</p> <h2 id="specification">Specification</h2> <h3 id="decimal">Decimal</h3> <p>A decimal is defined as</p> <p>c * 10^q</p> <p>where c and q are int256.</p> <p>Notationwise: a = ac * 10^aq b = bc * 10^bq etc.</p> <h3 id="opcode-defs">OPCODE defs</h3> <p>0xd0 DECADD a+b -&gt; c : (ac, aq, bc, bq, precision) -&gt; (cc, cq) 0xd1 DECNEG -a -&gt; b : (ac, aq) -&gt; (bc, bq) 0xd2 DECMUL a*b -&gt; c : (ac, aq, bc, bq, precision) -&gt; (cc, cq) 0xd3 DECINV 1/a -&gt; b : (ac, aq, precision) -&gt; (bc, bq) 0xd4 DECEXP exp(a) -&gt; b : (ac, aq, precision, steps) -&gt; (bc, bq) 0xd5 DECLN ln(a) -&gt; b : (ac, aq, precision, steps) -&gt; (bc, bq) 0xd6 DECSIN sin(a) -&gt; b : (ac, aq, precision, steps) -&gt; (bc, bq)</p> <p><code>precision</code> is the # of digits kept during all calculations. <code>steps</code> for DECEXP and DECSIN are the # of Taylor expansion steps. <code>steps</code> for DECLN is the depth of the continued fractions expansion.</p> <h3 id="why-these-functions">Why these functions?</h3> <p>The proposed functions (+,-,*,/,exp,ln,sin) form a small set that combined enable all calculation of all elementary functions, which includes the sets of sums, products, roots and compositions of finitely many polynomial, rational, trigonometric, hyperbolic, and exponential functions, including their inverse functions.</p> <p>a^b = exp(b * ln(a)) gives us powers and polynomials. cos(a) = sin(tau/4-a), tan(a)=sin(a)/cos(a), etc., gives us all of trigonometry.</p> <p>Together with arithmetic, we get all elementary functions.</p> <h3 id="decneg-instead-of-decsub">DECNEG instead of DECSUB</h3> <p>Negation is a more general operation vs subtraction. OPCODEs should be as fundamental as possible and as complex as desirable. For the same reason, we have DECINV instead of DECDIV.</p> <p>DECSUB(a,b) = DECADD(a,DECNEG(b)) DECDIV(a,b) = DECMUL(a,DECINV(b))</p> <h3 id="decexp-decsin-via-taylor-series">DECEXP, DECSIN via Taylor series</h3> <p>The Taylor series of exp and sin converge everywhere and fast. The error falls as fast as the factorial of steps.</p> <h3 id="decln-via-continued-fractions">DECLN via continued fractions</h3> <p>Ln converges fast using continued fractions within the interval ]0,2]. The implementation scales the input into this interval and scales the result back correctly.</p> <p>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> <h2 id="rationale">Rationale</h2> <h3 id="gas">gas</h3> <p>All the above OPCODEs are deterministic, hence the gas cost can be determined. At the same time, the calculations are complex and depend on the input.</p> <p>It is crucial to have accurate gas costs to avoid energy attacks on nodes.</p> <p>To this end, the underlying uint256 lib can be wrapped with gas accumulation, as found in the reference implementation in ../assets/eip-EVM+/uint256_wrapped.go. This gives a bottom-up approach to calculating gas, by running the OPCODE.</p> <p>Because the EVM interprator expects the gas cost before actually running the OPCODE, we are running the OPCODE twice. the first run, identical to the second, is to get the bottom-up gas cost, which is then doubled to account for the actual run plus the gas calculation. On top, we add a fixed emulation cost.</p> <p>This gives an embedded gas calculation, which works well for complex OPCODEs (see gasEVMPlusEmulate in ../assets/eip-EVM+/gasEVMPlusEmulate.go).</p> <p>To remove the double gas, we could find an upper bound on gas usage dependent on the function inputs. Alternatively, a future EIP would suggest the following: allow contract code to run whilst accumulating gas (at runtime) and panicking in case of limit breach, without requiring the cost in advance. This only works for contract code that is pure, defined as code that only depends on the user input and the inner bytecode of the contract. Pure contracts cannot use state from the chain, nor make calls to other contracts. pure mathematical functions would e.g. be pure contracts. pure contracts are fully deterministic given the input, allowing a user to estimate gas costs offline (cheaper) and the EVM to panic at runtime, without knowing gas in advance.</p> <p>Since the costs depend on the input, a fuzzing would give us close to the worst cases (TODO).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <p>Since the EVM allows contracts to deploy with invalid code, there could be previously invalid code that becomes valid when adding a new OPCODE. The EVM could be designed to expect a version tag at the beginning of all bytecode or (not xor) to only deploy valid code. This is an issue for any new OPCODE.</p> <h2 id="test-cases">Test Cases</h2> <p>../assets/eip-EVM+/decimal_float_test.go</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation is found in ../assets/eip-EVM+/decimal_float.go</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no security considerations, as long as numerical correctness is guaranteed and gas is collected fairly.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-10-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Guillaume Ballethttps://github.com/gballet Diederik Loerakkerhttps://github.com/protolambda https://wg-eips.ritovision.com/7545/

Add a precompile to help dapps verify verkle proofs

<h2 id="abstract">Abstract</h2> <p>This EIP proposes the addition of a precompiled contract to provide up-to-date state proof verification capabilities to smart contracts in a stateless Ethereum context.</p> <h2 id="motivation">Motivation</h2> <p>The proposed proof systems for stateless Ethereum require an upgrade to many tools and applications, that need a simple path to keep their proving systems up-to-date, without having to develop and deploy new proving libraries each time another proof format must be supported.</p> <h2 id="specification">Specification</h2> <p>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>A precompiled contract is added at address <code>0x21</code>, wrapping the stateless ethereum proof verification function.</p> <p>The precompile's <code>input</code> is the tightly packed concatenation of the following fields:</p> <ul> <li><code>version</code> (1 byte) specifies which version of the stateless proof verification function should be used. Version 0 is used for an MPT and version 1 is used for the polynomial commitment scheme multiproof used in <a href="https://wg-eips.ritovision.com/6800/">EIP-6800</a>.</li> <li><code>state_root</code> (32 bytes) specifies the state root that the proof is proving against.</li> <li><code>proof_data</code> (arbitrary long) is the proof data.</li> </ul> <p>Pseudo-code behavior of the precompile:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> proof_verification_precompile</span><span>(</span><span class="z-variable z-parameter z-function">input</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span> state_root</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">1</span><span>:</span><span class="z-constant">33</span><span>]</span></span> <span class="giallo-l"><span> proof_data</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">33</span><span>:</span><span class="z-constant">33</span><span class="z-keyword">+</span><span>proof_data_size</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> version</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> proof</span><span class="z-keyword"> =</span><span> deserialize_proof</span><span>(</span><span>state_root</span><span>,</span><span> proof_data</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> verify_mpt_multiproof</span><span>(</span><span>proof</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> version</span><span class="z-keyword"> ==</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span> proof</span><span class="z-keyword"> =</span><span> deserialize_proof</span><span>(</span><span>state_root</span><span>,</span><span> proof_data</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> verify_pcs_multiproof</span><span>(</span><span>proof</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0</span></span></code></pre> <p>If <code>version</code> is <code>0</code> then the proof is expected to follow the SSZ format described in "the verge" proposal in the consensus spec.</p> <p>The precompile returns <code>1</code> if it was able to verify the proof, and <code>0</code> otherwise.</p> <h3 id="gas-costs">Gas costs</h3> <table><thead><tr><th>Constant name</th><th>cost</th></tr></thead><tbody> <tr><td><code>POINT_COST</code></td><td>TBD</td></tr> <tr><td><code>POLY_EVAL_COST</code></td><td>TBD</td></tr> </tbody></table> <p>The precompile cost is:</p> <p><code>cost = (POINT_COST + 1)*len(get_commitments(input)) + POLY_EVAL_COST * [leaf_depth(key, get_tree(input)) for key in get_keys(input))]</code></p> <p>where:</p> <ul> <li><code>get_commitments</code> extracts the list of commitments in the proof, as encoded in <code>input</code></li> <li><code>get_keys</code> extracts the list of keys in the proof, as encoded in <code>input</code></li> <li><code>leaf_depth</code> returns the depth of the leaf in the tree</li> <li><code>get tree</code> reconstruct a stateless view of the tree from <code>input</code></li> </ul> <h2 id="rationale">Rationale</h2> <p>Stateless Ethereum relies on proofs using advanced mathematical concepts and tools from a fast-moving area of cryptography. As a result, a soft-fork approach is currently favored in the choice of the proof format: proofs are going to be distributed outside of consensus, and in the future, stateless clients will be able to chose their favorite proof format.</p> <p>This introduces a burden on several application, e.g. bridges, as they will potentially need to support proof formats designed after the release of the bridge contract.</p> <p>Delegating the proof verification burden to a version-aware precompile will ensure that these applications can support newer proving primitives without having to upgrade their contracts.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>WIP</p> <ul> <li>First implementation in Optimism, pull request #192 of ethereum-optimism/op-geth by @protolambda</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-10-01T00:00:00+00:00 2026-02-11T14:49:28+00:00 Yoav Weisshttps://github.com/yoavw Alex Forshtathttps://github.com/forshtat Dror Tiroshhttps://github.com/drortirosh Shahaf Nacsonhttps://github.com/shahafn https://wg-eips.ritovision.com/7557/

Block-level warming of addresses and slots with access lists

<h2 id="abstract">Abstract</h2> <p>A mechanism for a fair distribution of the gas costs associated with access to addresses and storage slots among multiple transactions with shared items in their <code>accessList</code>.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/2929/">EIP-2929: Gas cost increases for state access opcodes</a> introduced a new gas cost model that differentiates between "cold" and "warm" access to accounts and storage slots.</p> <p>However, the cost of every cold access is borne by each transaction separately, even though the validator only needs to fetch the state object once for the entire block.</p> <p>When multiple transactions access the same state object in the same block the fees charged for these transactions do not accurately reflect the computations that block builders and validators perform for the blockchain state access during transaction execution.</p> <p><a href="https://wg-eips.ritovision.com/2930/">EIP-2930: Optional access lists</a> made it possible for transactions to pre-specify and pre-pay for the accounts and storage slots that the transaction plans to access, however, the cost is still paid repeatedly by each transaction rather than once at the block level.</p> <p>With the <a href="https://wg-eips.ritovision.com/6800/">EIP-6800: Ethereum state using a unified verkle tree</a> on the roadmap for inclusion, the cost of reading from the Ethereum state and especially the contract code is expected to increase.</p> <p>Especially affected by this upcoming change will be transactions that involve smart contracts with a high code size.</p> <p>Each such transaction in the block will be forced to pay the full "retail" price for loading smart contract bytecode during a transaction.</p> <p>The validators, however, only have to perform the actual reading from the Ethereum state once per block, and all subsequent reads of the values that were already referenced are significantly more efficient.</p> <p>If witnesses are introduced to Ethereum blocks, the same witness can be reused by multiple transactions. Requiring each transaction to pay regardless of the contents of the block is unfair and inefficient.</p> <p>Another change that may be on the roadmap for Ethereum is Account Abstraction. This change will see a large share of transactions being initiated by smart contracts directly. It is reasonable to expect many of these Smart Contract Accounts to rely on the same core wallet implementations. If each Account Abstraction transaction is charged a full gas cost of loading the Smart Contract Account code repeatedly, such transactions would become significantly overpriced.</p> <p>This difference is especially noticeable when compared to an EOA, which gets its validation logic loaded and executed for free.</p> <p>In this scenario, the base gas fees would be taken from the senders and burned needlessly while block proposers would be enjoying an unjustified excessive earning of priority gas fees.</p> <p>A major distinction between this proposal and alternatives, such as <a href="https://wg-eips.ritovision.com/7863/">EIP-7863</a>, lies in performing a fair distribution of gas savings between all participants - all transactions senders and the block builder.</p> <h2 id="specification">Specification</h2> <p>The <a href="https://wg-eips.ritovision.com/2930/">EIP-2930: Optional access lists</a> already introduced the first part of the solution. Each transaction can specify an array of <code>accessed_addresses</code> and <code>accessed_storage_keys</code> to announce its intention to read those values during the execution of the transaction.</p> <p>The sender of the transaction is then pre-charged with the cost of accessing this data but is given a small discount compared to unannounced access.</p> <p>The missing component is a mechanism to aggregate the gas costs of the cold access and redistribute the resulting savings amongst the participating transactions.</p> <h3 id="overview">Overview</h3> <p>During the transaction execution, the cost of all storage-related operations is not affected, and all rules from EIP-2929 and EIP-2930 continue to apply.</p> <p>There are no changes to the block header or the transaction payload and receipt.</p> <p>As the last operation of each block, the collected gas costs associated with storage access are redistributed among the senders of all transactions withing a block. This affects the balances of all these accounts in a way that only becomes observable in the next block.</p> <p>This reimbursement's amount is proportional to the amount paid for the access in the first place.</p> <h3 id="participant-transactions-mapping">Participant transactions mapping</h3> <p>After the block builder finalizes the contents of the block, it iterates over all included transactions to read the <code>accessList</code> component of each supported transaction.</p> <p>The block builder then constructs an array containing each accessed address and each accessed slot, and an array of transaction senders' addresses that initiated at least one access to the given address or slot, as well as the <code>priorityFeePerGas</code> that was paid for such access.</p> <p>A sample JSON representation of the data structure that represents such a structure and is used in the pseudocode below:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xde0b295669a9fd93d5f28d9ec85e40f4cb697bae</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">accessors</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xFFcf8FDEE72ac11b5c542428B35EEF5769C409f0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xFFcf8FDEE72ac11b5c542428B35EEF5769C409f0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x22d491Bde2303f2f43325b2108D26f1eAbA1e32b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x22d491Bde2303f2f43325b2108D26f1eAbA1e32b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">3000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">slots</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000003</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">accessors</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x90F8bf6A479f320ead074411a4B0e7944Ea8c9C1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x22d491Bde2303f2f43325b2108D26f1eAbA1e32b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x22d491Bde2303f2f43325b2108D26f1eAbA1e32b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">3000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000007</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">accessors</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xFFcf8FDEE72ac11b5c542428B35EEF5769C409f0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xFFcf8FDEE72ac11b5c542428B35EEF5769C409f0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priorityFeePerGas</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>]</span></span> <span class="giallo-l"></span></code></pre><h3 id="calculating-a-reimbursement-of-the-burned-base-fee">Calculating a reimbursement of the burned base fee</h3> <p>Considering that the same amount of computation is needed to access an address or a slot regardless of the number of transactions using one, it is reasonable for the protocol to only burn the gas cost of the cold access once. As all transactions in the same block pay exactly the same <code>baseFeePerGas</code>, the single cost of accessing a cold item is divided evenly among all transactions containing such access and the rest of the burned base fee is reimbursed.</p> <h3 id="setting-an-absolute-minimal-cost-of-cold-state-access">Setting an absolute minimal cost of cold state access</h3> <p>If a large number of transactions all access the same addresses or slots, the cost of each cold access may get way too low which may represent a potential DoS attack vector.</p> <p>In order to prevent that, the gas cost of including an entity in the access list cannot be lower than <code>MIN_ACCESS_LIST_ENTRY_COST</code>, which is set to <code>32 gas</code>.</p> <p>This value is equivalent to the calldata cost of including two bytes long identifier of entries in <code>block_access_list</code>.</p> <h3 id="calculating-a-reimbursement-of-the-charged-priority-fee">Calculating a reimbursement of the charged priority fee</h3> <p>Each transaction pays an individual <code>priorityFeePerGas</code> value and redistributing this part of the cold access cost is more complex.</p> <p>We propose the following approach to a fair reimbursement of the paid <code>priorityFee</code>:</p> <ol> <li> <p>The validator gets paid the <code>priorityFee</code> for each cold access only once, but according to the highest <code>priorityFee</code> among the transactions containing the said cold access.</p> </li> <li> <p>The rest of the Ether that was charged by the validator as a <code>priorityFee</code> is redistributed back to all the senders of transactions containing the same cold access in proportion to their <strong>marginal contribution</strong> to the <strong>total gains</strong> of the transaction.</p> </li> <li> <p>The block builder is only paid for access once and the remaining value is reimbursed. So the <code>total reimbursement</code> value is a difference between the sum of value charged and the block builder's reward.</p> </li> <li> <p>The <code>total gains</code> of the transaction is defined by a sum of the <code>priorityFee</code> paid out to the block builder and <code>total reimbursement</code> made to all participants.</p> </li> <li> <p>Mathematically, the <code>marginal contribution</code> of a transaction to the <code>total gains</code> is defined as the difference between the sum <code>total gains</code> value calculated when all transactions in a block are included, and when all transactions are included except for this particular transaction. In practice this value always amounts to <code>priorityFee * gasCost</code>.</p> <blockquote> <p>𝑀𝐶𝑖 = 𝑣(𝑆 ∪ {𝑖}) − 𝑣(𝑆)</p> </blockquote> </li> </ol> <p>A single transaction accessing an address or a slot that is not shared by other transactions does not trigger a reimbursement, and therefore has a zero marginal contribution.</p> <h3 id="efficiently-storing-the-access-lists-in-the-block-history">Efficiently storing the access lists in the block history</h3> <p>The contents of the <code>accessList</code> parameter are part of the Ethereum history and the potential cost of keeping this data in the blockchain must be accounted for when implementing this change. There is currently no additional charge applied to the <code>accessList</code> parameter, due to the cost of including an address or a storage slot in the <code>accessList</code> being a constant value that is significantly higher than the potential cost of storing the <code>accessList</code> at the cost of a dynamically sized <code>calldata</code> field.</p> <p>With the block-level warming there is a change that makes it possible for a transaction sender to construct transactions with a large <code>accessList</code> that cost very little to be included, and this can be used to bloat the blockchain size.</p> <p>This potential bloating of the block size also presents a challenge for the propagation of the block in a P2P network.</p> <p>In order to minimize the cost of permanently storing access lists, we propose the following changes to the <code>execution_payload</code> structure:</p> <ol> <li>Add a new <code>block_access_list</code> field.</li> </ol> <p>The execution clients create a combined block-level "access list" that contains all unique entries from all transactions in the block. 2. All individual transaction <code>accessList</code> fields replace the full entries with a compact 2 bytes long reference to the <code>block_access_list</code> in the same order they appeared originally.</p> <p>With this approach shared entries in the access lists cannot cause sufficient bloating of the block size.</p> <p>There is no need to introduce any observable changes to the RPC API as this "compression" can be unwrapped by the clients in real time.</p> <h3 id="pseudocode-implementation-of-the-reimbursement-calculation-algorithm">Pseudocode implementation of the reimbursement calculation algorithm</h3> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-keyword">export</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> calculateBlockColdAccessReimbursement</span><span> (</span></span> <span class="giallo-l"><span class="z-variable"> baseFeePerGas</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> accessDetailsMap</span><span class="z-keyword">:</span><span class="z-entity z-name"> AddressAccessDetails</span><span>[</span><span>]</span></span> <span class="giallo-l"><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name"> Map</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-entity z-name"> reimbursement</span><span>&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> reimbursements</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> Map</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-entity z-name"> Reimbursement</span><span>&gt;</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> accessDetail</span><span class="z-keyword"> of</span><span class="z-variable z-other"> accessDetailsMap</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> calculateItemColdAccessReimbursement</span><span>(</span><span class="z-variable z-other">accessDetail</span><span>.</span><span class="z-variable z-other">accessors</span><span>,</span><span class="z-variable z-other"> baseFeePerGas</span><span>,</span><span class="z-variable z-other z-constant"> COLD_ACCOUNT_ACCESS_COST</span><span>,</span><span class="z-variable z-other"> reimbursements</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> slot</span><span class="z-keyword"> of</span><span class="z-variable z-other"> accessDetail</span><span>.</span><span class="z-variable z-other">slots</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> calculateItemColdAccessReimbursement</span><span>(</span><span class="z-variable z-other">slot</span><span>.</span><span class="z-variable z-other">accessors</span><span>,</span><span class="z-variable z-other"> baseFeePerGas</span><span>,</span><span class="z-variable z-other z-constant"> COLD_SLOAD_COST</span><span>,</span><span class="z-variable z-other"> reimbursements</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> reimbursements</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> calculateItemColdAccessReimbursement</span><span> (</span></span> <span class="giallo-l"><span class="z-variable"> unsortedAccessors</span><span class="z-keyword">:</span><span class="z-entity z-name"> AccessDetails</span><span>[</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> baseFeePerGas</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> accessGasCost</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> reimbursements</span><span class="z-keyword">:</span><span class="z-entity z-name"> Map</span><span>&lt;</span><span class="z-support">string</span><span>,</span><span class="z-entity z-name"> Reimbursement</span><span>&gt;</span></span> <span class="giallo-l"><span>)</span><span class="z-keyword">:</span><span class="z-support"> void</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> sortedAccessDetails</span><span class="z-keyword"> =</span><span class="z-variable z-other"> unsortedAccessors</span><span>.</span><span class="z-entity z-name">sort</span><span>(</span><span>(</span><span class="z-variable">a</span><span>,</span><span class="z-variable"> b</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span><span class="z-keyword"> return</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">b</span><span>.</span><span class="z-variable z-other">priorityFeePerGas</span><span>)</span><span class="z-keyword"> -</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">priorityFeePerGas</span><span>)</span><span> }</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> addressAccessN</span><span class="z-keyword"> =</span><span class="z-variable z-other"> sortedAccessDetails</span><span>.</span><span class="z-support z-variable">length</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> reimbursementPercent</span><span class="z-keyword"> =</span><span> (</span><span class="z-variable z-other">addressAccessN</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> /</span><span class="z-variable z-other"> addressAccessN</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> reimbursementsFromCoinbase</span><span class="z-keyword"> =</span><span class="z-entity z-name"> calculatePriorityFeeReimbursements</span><span>(</span><span class="z-variable z-other">sortedAccessDetails</span><span>,</span><span class="z-variable z-other"> accessGasCost</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">let</span><span class="z-variable z-other"> i</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>;</span><span class="z-variable z-other"> i</span><span class="z-keyword"> &lt;</span><span class="z-variable z-other"> sortedAccessDetails</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other"> i</span><span class="z-keyword">++</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> accessor</span><span class="z-keyword"> =</span><span class="z-variable z-other"> sortedAccessDetails</span><span>[</span><span class="z-variable z-other">i</span><span>]</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> reimbursement</span><span class="z-keyword"> =</span><span class="z-variable z-other"> reimbursements</span><span>.</span><span class="z-entity z-name">get</span><span>(</span><span class="z-variable z-other">accessor</span><span>.</span><span class="z-variable z-other">sender</span><span>)</span><span class="z-keyword"> ??</span><span> {</span><span> reimbursementFromBurn</span><span>:</span><span class="z-constant"> 0</span><span class="z-storage z-type">n</span><span>,</span><span> reimbursementFromCoinbase</span><span>:</span><span class="z-constant"> 0</span><span class="z-storage z-type">n</span><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> adjustedAccessGasCost</span><span class="z-keyword"> =</span><span class="z-variable z-other"> Math</span><span>.</span><span class="z-entity z-name">max</span><span>(</span><span class="z-variable z-other z-constant">MIN_ACCESS_LIST_ENTRY_COST</span><span>,</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">accessGasCost</span><span>)</span><span class="z-keyword"> *</span><span class="z-variable z-other"> reimbursementPercent</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> reimbursement</span><span>.</span><span class="z-variable z-other">reimbursementFromBurn</span><span class="z-keyword"> +=</span><span class="z-entity z-name"> BigInt</span><span>(</span><span class="z-variable z-other">adjustedAccessGasCost</span><span class="z-keyword"> *</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">baseFeePerGas</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> reimbursement</span><span>.</span><span class="z-variable z-other">reimbursementFromCoinbase</span><span class="z-keyword"> +=</span><span class="z-entity z-name"> BigInt</span><span>(</span><span class="z-variable z-other">reimbursementsFromCoinbase</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> reimbursements</span><span>.</span><span class="z-entity z-name">set</span><span>(</span><span class="z-variable z-other">accessor</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> reimbursement</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">export</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> calculatePriorityFeeReimbursements</span><span> (</span><span class="z-variable">sortedAccesses</span><span class="z-keyword">:</span><span class="z-entity z-name"> AccessDetails</span><span>[</span><span>]</span><span>,</span><span class="z-variable"> accessGasCost</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Validator charge is based on the highest paid priority fee per gas</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> validatorFee</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">sortedAccesses</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">priorityFeePerGas</span><span>)</span><span class="z-keyword"> *</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">accessGasCost</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Accumulate the sum of all &quot;contributions&quot;, at least the top transaction contribution</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> totalContributions</span><span class="z-keyword"> =</span><span class="z-variable z-other"> validatorFee</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Accumulate cost of gas paid to validator for accessing the same address/slot/chunk</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> totalSendersCharged</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">sortedAccesses</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span class="z-variable z-other">priorityFeePerGas</span><span>)</span><span class="z-keyword"> *</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">accessGasCost</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Starting with `1` as element at `0` is explicitly shown here to be used as `validatorFee`</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">let</span><span class="z-variable z-other"> i</span><span class="z-keyword"> =</span><span class="z-constant"> 1</span><span>;</span><span class="z-variable z-other"> i</span><span class="z-keyword"> &lt;</span><span class="z-variable z-other"> sortedAccesses</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other"> i</span><span class="z-keyword">++</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> charge</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">sortedAccesses</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>.</span><span class="z-variable z-other">priorityFeePerGas</span><span>)</span><span class="z-keyword"> *</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">accessGasCost</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> totalContributions</span><span class="z-keyword"> +=</span><span class="z-variable z-other"> charge</span></span> <span class="giallo-l"><span class="z-variable z-other"> totalSendersCharged</span><span class="z-keyword"> +=</span><span class="z-variable z-other"> charge</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Calculate the total amount of ether to be reimbursed for this access</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> totalReimbursement</span><span class="z-keyword"> =</span><span class="z-variable z-other"> totalSendersCharged</span><span class="z-keyword"> -</span><span class="z-variable z-other"> validatorFee</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">totalReimbursement</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> possible if only single transaction or if all priority fees are 0</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> Array</span><span>(</span><span class="z-variable z-other">sortedAccesses</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span>.</span><span class="z-entity z-name">fill</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Calculate actual charges and reimbursements</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> reimbursements</span><span class="z-keyword"> =</span><span> [</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">floor</span><span>(</span><span class="z-variable z-other">totalReimbursement</span><span class="z-keyword"> *</span><span class="z-variable z-other"> topTransactionContribution</span><span class="z-keyword"> /</span><span class="z-variable z-other"> totalContributions</span><span>)</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">let</span><span class="z-variable z-other"> i</span><span class="z-keyword"> =</span><span class="z-constant"> 1</span><span>;</span><span class="z-variable z-other"> i</span><span class="z-keyword"> &lt;</span><span class="z-variable z-other"> sortedAccesses</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other"> i</span><span class="z-keyword">++</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> charge</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">sortedAccesses</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>.</span><span class="z-variable z-other">priorityFeePerGas</span><span>)</span><span class="z-keyword"> *</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">accessGasCost</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> calldataCharge</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">sortedAccesses</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>.</span><span class="z-variable z-other">priorityFeePerGas</span><span>)</span><span class="z-keyword"> *</span><span class="z-variable z-other z-constant"> MIN_ACCESS_LIST_ENTRY_COST</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> reimbursementToCalldata</span><span class="z-keyword"> =</span><span class="z-variable z-other"> charge</span><span class="z-keyword"> -</span><span class="z-variable z-other"> calldataCharge</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> reimbursementToContribution</span><span class="z-keyword"> =</span><span class="z-variable z-other"> Math</span><span>.</span><span class="z-entity z-name">floor</span><span>(</span><span class="z-variable z-other">totalReimbursement</span><span class="z-keyword"> *</span><span class="z-variable z-other"> charge</span><span class="z-keyword"> /</span><span class="z-variable z-other"> totalContributions</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> reimbursements</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">min</span><span>(</span><span class="z-variable z-other">reimbursementToCalldata</span><span>,</span><span class="z-variable z-other"> reimbursementToContribution</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> reimbursements</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note that two accumulating values, <code>reimbursementFromBurn</code> and <code>reimbursementFromCoinbase</code>, are necessary in light of <a href="https://wg-eips.ritovision.com/1559/">EIP-1559: Fee market change for ETH 1.0 chain</a> in order to differentiate between the Ether reimbursement that is originating from a reduced block gas burn, and from the reduced block proposer priority fee per gas reward.</p> <h3 id="future-eip-6800-gas-reform-support">Future EIP-6800 gas reform support</h3> <p>Once <a href="https://wg-eips.ritovision.com/6800/">EIP-6800</a> is active, the cost of accessing a contract code for a cold address is expected to change.</p> <p>Instead of being a constant value of <code>COLD_ACCOUNT_ACCESS_COST</code> (currently 2600 gas), the total cost will be determined by the number of 31-byte "chunks" the code consists of. Each "chunk" of code will have a cost of <code>CODE_CHUNK_ACCESS_COST</code> (currently 200 gas).</p> <p>For a maximum contract size of <code>24576 bytes</code> defined by <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> the cost of accessing this contract surges from <code>2600</code> to <code>158600</code> gas.</p> <p>This change will likely require the <code>accessList</code> parameter of transactions to be adjusted for transactions to be able to specify which code chunks will be accessed.</p> <p>In such case the changes are reflected in the reimbursement function as well, which is updated by adding the following code in order to redistribute the shared cost of accessing the same code chunk in multiple transactions:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> reimbursementsFromCoinbase</span><span class="z-keyword"> =</span><span class="z-entity z-name"> calculatePriorityFeeReimbursements</span><span>(</span><span class="z-variable z-other">sortedCodeChunkAccessDetails</span><span>,</span><span class="z-variable z-other z-constant"> CHUNK_ACCESS_COST</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">for</span><span> (</span><span class="z-storage z-type">let</span><span class="z-variable z-other"> i</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>;</span><span class="z-variable z-other"> i</span><span class="z-keyword"> &lt;</span><span class="z-variable z-other"> sortedAccessDetails</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other"> i</span><span class="z-keyword">++</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> reimbursement</span><span class="z-keyword"> =</span><span class="z-variable z-other"> reimbursements</span><span>.</span><span class="z-entity z-name">get</span><span>(</span><span class="z-variable z-other">accessor</span><span>.</span><span class="z-variable z-other">sender</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> reimbursement</span><span>.</span><span class="z-variable z-other">reimbursementFromBurn</span><span class="z-keyword"> +=</span><span class="z-variable z-other z-constant"> CHUNK_ACCESS_COST</span><span class="z-keyword"> *</span><span class="z-variable z-other"> block</span><span>.</span><span class="z-variable z-other">baseFeePerGas</span><span class="z-keyword"> *</span><span class="z-variable z-other"> reimbursementPercent</span></span> <span class="giallo-l"><span class="z-variable z-other"> reimbursement</span><span>.</span><span class="z-variable z-other">reimbursementFromCoinbase</span><span class="z-keyword"> +=</span><span class="z-variable z-other"> reimbursementsFromCoinbase</span><span>[</span><span class="z-variable z-other">i</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="cost-redistribution-system-operation">Cost redistribution system operation</h3> <p>The <a href="https://wg-eips.ritovision.com/4895/">EIP-4895: Beacon chain push withdrawals as operations</a> sets a precedent by introducing a concept of a <code>system-level withdrawal operation</code>.</p> <p>We propose the introduction of yet another system-level operation called <code>cost redistribution</code>. The <code>redistributions</code> in an execution payload are processed after any user-level transactions are applied.</p> <p>The block builder or a validator prepares a list of reimbursement information.</p> <p>For each <code>redistribution</code> in the list, the implementation increases the balance of the address specified by the amount <code>reimbursementFromBurn + reimbursementFromCoinbase</code>.</p> <p>The balance of the <code>coinbase</code> is reduced by a sum of all <code>reimbursementFromCoinbase</code> values.</p> <h2 id="rationale">Rationale</h2> <h3 id="current-cold-storage-gas-cost-is-unfair">Current cold storage gas cost is unfair</h3> <p>As described in the <a href="https://wg-eips.ritovision.com/7557/#motivation">Motivation</a> section, the amount of gas that users spend on accessing the contract code does not reflect the actual cost of this access for the block builder or a validator.</p> <p>The more popular the contract code or a storage slot is, the more transactions in each block should share the cost. However, the current system multiplies the cost for the users instead of dividing it.</p> <h3 id="issuing-a-regular-gas-refund-after-a-transaction-is-not-possible">Issuing a regular gas refund after a transaction is not possible</h3> <p>There exists a list of EVM instructions that trigger both a gas charge and a gas refund. A notable example of such operations is the <code>0x55 SSTORE</code> opcode as defined in <a href="https://wg-eips.ritovision.com/1283/">EIP-1283: Net gas metering for SSTORE without dirty maps</a>. Intuitively it seems reasonable to issue the gas reimbursements for the shared cold storage access in the same fashion.</p> <p>However, this approach significantly complicates the block-building process. In this case, the inclusion or exclusion of a transaction at the end of the block triggers observable effects in transactions included at the beginning of the block, and this makes the job of finding a valid set of transactions for a block potentially computationally unsolvable.</p> <p>Therefore, we propose performing the reimbursements at the end of the block, where it cannot change the behavior of any transaction in the block.</p> <h3 id="weighting-priority-fee-reimbursement">Weighting priority fee reimbursement</h3> <p>A common game-theoretical answer to the problem of calculating a fair redistribution of the payoff of the results of the participants' cooperation is the use of Shapley values.</p> <p>However, we argue that the proposed distribution of the <code>priorityFee</code> reimbursements is sufficiently fair while being a lot easier to compute or articulate.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal does not introduce a change to any behavior that can be observed by a smart contract during its execution. The only effect this change has is a lower effective gas cost for the transaction senders.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The upper limit of storage reads in one block is not affected by this change as the gas charge is done with the full cost of <code>COLD_ACCOUNT_ACCESS_COST</code> or <code>COLD_SLOAD_COST</code>.</p> <p>The maximum amount of memory and computation required to calculate the reimbursements according to the specified algorithm is insignificant.</p> <p>It appears that this change does not have any negative security implications.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-09-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/7519/

Add atomic operations for incrementing and decrementing storage slots

<h2 id="abstract">Abstract</h2> <p>Two new opcodes that atomically mutate smart contract storage are proposed: SCREDIT, which increments a storage slot by a specified value, and SDEBIT, which decrements a storage slot by a specified value. Overflow and underflow errors are enforced, reverting when an unsigned 256-bit integer would overflow or underflow.</p> <h2 id="motivation">Motivation</h2> <p>There has been a large amount of energy around parallel EVMs across multiple chains, however there is a lack of parallel primitives within the EVM to support any model other than optimistic concurrency control (OCC). By adding concurrent increment and decrement operations more advanced parallel environments can be introduced in Layer 2 networks.</p> <p>This also provides the opportunity to serve the principal use case of increment and decrement: token balances. We can introduce failures on overflow and underflow conditions and provide an operation that is also useful outside of parallel use cases.</p> <h2 id="specification">Specification</h2> <p>Two operations to atomically increment and decrement a storage will be introduced at <code>0xTBD</code>. Each operation takes two stack arguments and has no immediate arguments. Gas schedule will be the same as SSTORE.</p> <table><thead><tr><th>Mnemonic</th><th>Op</th><th>Input</th><th>Output</th></tr></thead><tbody> <tr><td><code>SCREDIT</code></td><td><code>0xTBD</code></td><td><code>2</code></td><td><code>0</code></td></tr> <tr><td><code>SDEBIT</code></td><td><code>0xTBD+1</code></td><td><code>2</code></td><td><code>0</code></td></tr> </tbody></table> <h3 id="scredit">SCREDIT</h3> <p><code>SCREDIT: slot, value</code></p> <h4 id="description">Description</h4> <p>Adds <code>value</code> to the value stored in contract storage <code>slot.</code> If an overflow would occur the operation halts exceptionally.</p> <h4 id="gas-charging">Gas Charging</h4> <p>Gas charging is identical to SSTORE. including interactions with the warm storage slot list. Any future modifications to the SSTORE gas charges will also apply to SCREDIT.</p> <h4 id="execution">Execution</h4> <p><em>Not valid python, not suitable for EELS yet</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>slot = evm_stack.pop()</span></span> <span class="giallo-l"><span>value = evm_stack.pop()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>storage_value = read_contract_storage(slot)</span></span> <span class="giallo-l"><span>storage_value = storage_value + value</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>if storage_value &gt;= 2**256 :</span></span> <span class="giallo-l"><span> raise Exception(&quot;scredit overflow&quot;)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>write_contract_storage(storage_value)</span></span></code></pre><h3 id="sdebit">SDEBIT</h3> <p><code>SDEBIT: slot, value</code></p> <h4 id="description-1">Description</h4> <p>Subtracts <code>value</code> to the value stored in contract storage <code>slot.</code> If an underflow would occur the operation halts exceptionally.</p> <h4 id="gas-charging-1">Gas Charging</h4> <p>Gas charging is identical to SSTORE, including interactions with the warm storage slot list. Any future modifications to the SSTORE gas charges will also apply to SDEBIT.</p> <h4 id="execution-1">Execution</h4> <p><em>Not valid python, not suitable for EELS yet</em></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>slot = evm_stack.pop()</span></span> <span class="giallo-l"><span>value = evm_stack.pop()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>storage_value = read_contract_storage(slot)</span></span> <span class="giallo-l"><span>storage_value = storage_value - value</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>if storage_value &lt; 0 :</span></span> <span class="giallo-l"><span> raise Exception(&quot;sdebit underflow&quot;)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>write_contract_storage(storage_value)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The primary consideration when choosing between alternatives is that the primary intended audiences is token contracts and other asset-tracking contracts combined with a desire to ship the minimum necessary changes to enable that use case. General concurrency controls is not a goal of this EIP.</p> <h3 id="enforcing-overflow-semantics">Enforcing Overflow Semantics</h3> <p>When allowing for out-of-order execution there needs to be mechanism to handle any possible order of execution. OCC handles this by validating pre- and post-conditions, and re-evaluating the transactions if those invariants did not hold. This technique breaks down around writing to balances and counters.</p> <p>Increment/decrement with rollover checking allows for simple handling of balances and counters while allowing for functional read support ensuring that sufficient balance or count exists without depending on the exact values. This allows for evaluation models where the only post-condition checked is to validate that the storage slots could handle all possible re-ordering of transactions.</p> <h3 id="gas-schedule">Gas Schedule</h3> <p>The decision to cost the operations at the exact same value as SSTORE is partly for ease of implementation and partly as an incentive to compilers and developers.</p> <p>These semantics could be implemented in the EVM today, but it would also include a SLOAD, DUP, LT, JUMPI and REVERT instructions. The EVM, however, can do these operations much more efficiently than via opcodes. First, each SSTORE always incurs a slot load in order to apply <a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a> gas calculation rules. This load is essential if there is no paired SLOAD. Math libraries for 256-bit numbers can all easily be made sensitive to overflow and underflow, if they are not already present. Conditional logic handling is also much faster in the operation logic as most of the overhead would be operation parsing and stack management when interpreted.</p> <p>The net impact of the most relevant operations to the most expensive evaluation (an ADD and LT operation, above the cost of a plain SSTORE) would be 4 gas, or 0.2% of the current cost of a SSTORE. Finally, database access costs dominate the real cost of the operation. A 0.2% overhead may disappear in I/O stalls.</p> <p>Keeping the cost the same makes implementations of gas charging vert simple.</p> <h3 id="storage-slots-only">Storage Slots Only</h3> <p>This most important use case for this EIP asset balances and not general concurrency controls. Hence, only enabling credit and debit operations on storage slots (which persist across transactions). Parallel execution within a transaction and more generic tools like locks and semaphores have very limited utility within this scope. The lack of in-transaction parallel execution also precludes the use of such primitives against transient storage (as defined in <a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a>).</p> <h3 id="opcode-instead-of-system-contract">Opcode Instead of System Contract</h3> <p>One alternative, particularly viable for Layer 2 chains, would be to implement SCREDIT and SDEBIT as system contracts. The primary objection to system contracts for other operations is the gas cost overhead of constructing a call. Because a SSTORE is always greater than the cost of a call it would be possible to build in a discount. However, there is no such accommodation that can be made for the code size needed to invoke such a call.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>These opcodes are not simple replacements for SLOAD-(ADD|SUB)-SSTORE sequence because there is an overflow/underflow check</p> <p>There is no EVM functionality removed by this proposal.</p> <h2 id="test-cases">Test Cases</h2> <p>Test for overflow and non-overflow for the following values and values before and after:</p> <p>1, 2^8, 2^16, 2^32, 2^64, 2^128 2^255, 2^256-1.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>/# TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>The use of revert to handle over/underflow represents a new halt condition that auditors will need to consider when examining reentrancy concerns.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-09-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 George Kadianakishttps://github.com/asn-d6 Justin Drakehttps://github.com/JustinDrake dapplionhttps://github.com/dapplion https://wg-eips.ritovision.com/7441/

Allow elected block proposers to remain private until block publishing, to prevent DoS attacks

<h2 id="abstract">Abstract</h2> <p>Upgrades the block proposer election mechanism to Whisk, a single secret leader election (SSLE) protocol. Currently, block proposers are publicly known in advance, sufficiently to allow sequential DoS attacks that could disable Ethereum. This upgrade allows the next block proposer to remain secret until its block is published.</p> <h2 id="motivation">Motivation</h2> <p>The beacon chain currently elects the next 32 block proposers at the beginning of each epoch. The results of this election are public and everyone gets to learn the identity of those future block proposers.</p> <p>This information leak enables attackers to launch DoS attacks against each proposer sequentially in an attempt to disable Ethereum.</p> <h2 id="specification">Specification</h2> <h3 id="execution-layer">Execution layer</h3> <p>This requires no changes to the Execution Layer.</p> <h3 id="consensus-layer">Consensus layer</h3> <p>The protocol can be summarized in the following concurrent steps:</p> <ul> <li>Validators register a tracker and unique commitment on their first proposal after the fork</li> <li>At the start of a shuffling phase a list of candidate trackers is selected using public randomness from RANDAO</li> <li>During each shuffling phase each proposer shuffles a subset of the candidate trackers using private randomness</li> <li>After each shuffling phase an ordered list of proposer trackers is selected from the candidate set using RANDAO</li> </ul> <p>The full specification of the proposed change can be found in <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/a39abe388bc2d1abd5b4fd62fd18aed497956b30/specs/_features/whisk/beacon-chain.md"><code>/_features/whisk/beacon-chain.md</code></a>. In summary:</p> <ul> <li>Update <code>BeaconState</code> with fields needed to track validator trackers, commitments, and the two rounds of candidate election.</li> <li>Add <code>select_whisk_candidate_trackers</code> to compute the next vector of candidates from the validator set.</li> <li>Add <code>select_whisk_proposer_trackers</code> to compute the next vector of proposers from current candidates.</li> <li>Add <code>process_whisk_updates</code> to epoch processing logic.</li> <li>Add <code>process_whisk_opening_proof</code> to validate block proposer has knowledge of this slot's elected tracker.</li> <li>Modify <code>process_block_header</code> to not assert proposer election with <code>get_beacon_proposer_index</code>, instead assert valid opening proof.</li> <li>Update <code>BeaconBlockBody</code> with fields to submit opening proof, shuffled trackers with proof, and tracker registration with proof.</li> <li>Add <code>get_shuffle_indices</code> to compute pre-shuffle candidate selection</li> <li>Add <code>process_shuffled_trackers</code> to submit shuffled candidate trackers.</li> <li>Add <code>process_whisk</code> to block processing logic.</li> <li>Modify <code>apply_deposit</code> to register an initial unique tracker and commitment without entropy.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="fields-per-validator">Fields per validator</h3> <p>Whisk requires having one tracker <code>(rG,krG)</code> and one unique commitment <code>kG</code> per validator. Both are updated only once on a validator's first proposal after the fork.</p> <p>Trackers are registered with a randomized base <code>(rG,krG)</code> to make it harder for adversaries to track them through shuffling gates. It can become an issue if the set of honest shufflers is small.</p> <h3 id="identity-binding">Identity binding</h3> <p>Each tracker must be bound to a validator's identity to prevent multiple parties to claim the same proposer slot. Otherwise, it would allow proposers to sell their proposer slot, and cause fork-choice issues if two competing blocks appear.</p> <p>Whisk does identity binding by storing a commitment to the tracker's secret <code>kG</code> in the validator record. Storing the commitment also ensures the uniqueness of <code>k</code>.</p> <p>Alternatively, identity binding can be achieved by forcing the hash prefix of <code>hash(kG)</code> to match its validator index. However, validators would have to brute force <code>k</code> making bootstrap of the system harder for participants with fewer computational resources.</p> <p>Identity binding can also be achieved by setting <code>k = hash(nonce + pubkey)</code>. However, proposers will need to reveal <code>k</code> and be de-anonymized for repeated proposals on adjacent shuffling phases.</p> <h3 id="alternative-non-single-secret-election">Alternative: non-single secret election</h3> <p>Secret non-single leader election could be based on protocol engineering rather than cryptography, thus much simpler and cheaper than Whisk. However, it complicates the fork-choice and opens it up to potential MEV time-buying attacks, making it an unsuitable option at the time of writing.</p> <h3 id="alternative-network-anonymity">Alternative: network anonymity</h3> <p>Privacy-preserving networking protocols like Dandelion or Dandelion++ increase the privacy of network participants but not sufficiently for Ethereum's use case.</p> <p>SASSAFRAS is a simpler alternative SSLE protocol consensus-wise, but it relies on a network anonymity layer. Its specific trade-offs do not fit Ethereum's overall threat model better than Whisk.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces backward incompatible changes to the block validation rule set on the consensus layer and must be accompanied by a hard fork.</p> <p>PBS participants (e.g. builders) will not know the next proposer validator index to use a specific pre-registered fee recipient; unless the proposer chooses to reveal itself ahead of time. Block explorers and tooling will not be able to attribute missing slots to a specific validator index.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The shuffling strategy is analyzed in a companion paper and considered sufficiently safe for Whisk's use case. The data and computational complexity of this EIP are significant but constant, thus does not open new DoS vectors.</p> <h3 id="anonymity-set">Anonymity set</h3> <p>The anonymity set in Whisk is the set of 8,192 candidates that did not get selected as proposers. That count of validators corresponds to a smaller number of p2p nodes. Assuming a Pareto principle where "20% of the nodes run 80% of the validators" the anonymity corresponds to 2,108 nodes on average. A bigger candidate pool could make the shuffling strategy unsafe while shuffling more trackers per round would increase the cost of the ZK proofs.</p> <h3 id="randao-biasing">RANDAO biasing</h3> <p>Whisk uses RANDAO in the candidate selection and proposer selection events, and is susceptible to potential RANDAO biasing attacks by malicious proposers. Whisk security could be made identical to the status quo by spreading the selection events over an entire shuffling period. However, status quo security is not ideal either and it would complicate the protocol further.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-08-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Keyvan Kambakhshhttps://github.com/keyvank Hamid Batenihttps://github.com/irnb Amir Kahooria.kahoorizadeh@gmail.com Nobitex Labslabs@nobitex.ir 0xwormholehttps://github.com/0xwormhole https://wg-eips.ritovision.com/7503/

Enable minting of secretly burnt Ethers as a native privacy solution for Ethereum

<h2 id="abstract">Abstract</h2> <p>While researching on privacy solutions and applications of ZKP, we discovered a technique, by which people can burn their digital asset (E.g ETH) by sending it to an unspendable address, and later build a ZK proof showing that some amount of tokens reside in an account that are unspendable, without revealing the account.</p> <p>The EIP proposes to add a minting functionality to Ethereum, so that people can re-mint Ethers they have purposefully burnt. The mentioned privacy solution will bring strong levels of <em><strong>plausible deniability</strong></em> for the sender, since there is no way one can prove that the sender has been participating in a privacy protocol. This will also make an anonymity pool that includes all of the Ethereum accounts with zero outgoing transactions by default.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <ul> <li><code>MAGIC_ADDRESS</code>: <code>0xfe</code> (one byte)</li> <li><code>MAGIC_NULLIFIER</code>: <code>0x01</code> (one byte)</li> <li><code>MAGIC_POW</code>: <code>0x02</code> (one byte)</li> <li><code>MAGIC_CHANGE</code>: <code>0x0404040404040404040404040404040404040404040404040404040404040404</code></li> <li><code>POW_LOG_DIFFICULTY</code>: <code>24</code></li> <li><code>MAX_DEPOSIT</code>: <code>32 * 10**18</code> wei</li> <li><code>WormholeTxType</code>: <code>TBD</code></li> <li><code>WORMHOLE_NULLIFIER_ADDRESS</code>: <code>TBD</code></li> <li><code>RECEIPT_PREFIX</code>: <code>TBD</code> (datatype <code>List[bool]</code>)</li> </ul> <hr /> <p>We define a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction type, where <code>TransactionType</code> is <code>WormholeTxType</code> and the <code>TransactionPayload</code> format is as follows:</p> <p><code>[chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, to, data, access_list, root_beacon_block_number, proof]</code></p> <p>Verifying this type of transaction requires confirming that:</p> <ol> <li>The proof is a zero-knowledge proof: <ul> <li>Private inputs: <code>secret</code>, <code>main_index</code>, <code>main_branch</code>, <code>privacy_pool_index</code>, <code>privacy_pool_branch</code>, <code>deposit_value</code>, <code>deposit_sender</code>, <code>change_value_salt</code>, <code>change_value</code></li> <li>Public inputs: <code>beacon_block_root</code>, <code>nullifier</code>, <code>privacy_pool_root</code>, <code>withdraw_value</code>, <code>change_value_hash</code></li> <li>Function: verify all of the following conditions <ul> <li><code>verify_merkle_branch(root=beacon_block_root, index=RECEIPT_PREFIX + main_index, leaf=make_receipt_hash(deposit_sender, deposit_value, change_value_salt, secret), branch=main_branch)</code></li> <li><code>verify_merkle_branch(root=privacy_pool_root, index=privacy_pool_index, leaf=make_receipt_hash(deposit_sender, deposit_value, change_value_salt, secret), branch=privacy_pool_branch)</code></li> <li><code>nullifier == sha256(MAGIC_NULLIFIER + secret)</code></li> <li><code>sha256(MAGIC_POW + secret) % 2**POW_LOG_DIFFICULTY == 0</code></li> <li><code>change_value_hash == sha256(change_value_salt, change_value)</code></li> <li><code>change_value + withdraw_value == deposit_value</code> (all values are unsigned int, also need to confirm that there is no overflow)</li> <li><code>deposit_value &lt;= MAX_DEPOSIT</code></li> </ul> </li> </ul> </li> <li><code>SLOAD(WORMHOLE_NULLIFIER_ADDRESS, proof.nullifier) == 0</code></li> <li><code>get_beacon_block_root(root_beacon_block_number) == proof.beacon_block_root</code></li> </ol> <p>We define <code>make_receipt_hash</code> as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def make_receipt_hash(deposit_sender: Address, value: uint256, change_value_salt: bytes32, secret: bytes32):</span></span> <span class="giallo-l"><span> if deposit_sender != 0:</span></span> <span class="giallo-l"><span> to_address = sha256(MAGIC_ADDRESS + secret)[12:]</span></span> <span class="giallo-l"><span> topics = [MAGIC_EIP_7708, deposit_sender, to_address]</span></span> <span class="giallo-l"><span> logdata = int_to_bytes32(value)</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> topics = [MAGIC_CHANGE, hash(change_value_salt, value)]</span></span> <span class="giallo-l"><span> logdata = bytes([])</span></span> <span class="giallo-l"><span> return get_ssz_root_hash(Log(topics=topics, data=logdata))</span></span></code></pre> <p>The hash of the transaction (excluding proof) should be included in the randomness for generating the zero-knowledge proof. This ensures the proof serves as a signature.</p> <p>If the transaction is confirmed, generate <code>proof.withdraw_value</code> ether at address <code>WORMHOLE_NULLIFIER_ADDRESS</code>. Then proceed with a normal call from this address using that value. Before the call, set <code>SSTORE(WORMHOLE_NULLIFIER_ADDRESS, proof.nullifier, 1)</code>, and emit a log event where <code>topics = [MAGIC_CHANGE, proof.change_value_hash]</code> and <code>logdata = bytes([])</code>.</p> <h2 id="rationale">Rationale</h2> <p>In Elliptic-Curve based digital signatures, normally there is a secret scalar $s$, from which a public-key is calculated (By multiplying the generator point with the scalar: $s \times G$). An Ethereum EOA-address is the keccak hash of a public-key.</p> <p>Also, the funds in an Ethereum address might be spendable by a smart-contract, if the keccak hash of the smart-contract's parameters is equal with that address.</p> <p>Therefore, an Ethereum address $A$ is spendable if and only if:</p> <ol> <li>A private-key $s$ exists. such that $A = keccak(s \times G)$.</li> <li>There exists a smart-contract $c$, such that $A = keccak(c_{params})$.</li> </ol> <p>The preimage resistance property of hash functions implies that, you can't find $x$ where $keccak(x)=r$, in case $r$ is a random value. So the funds sent to a random Ethereum address $r$ is unspendable, but how can other people be sure that $r$ is indeed random and not the result of calculating $s \times G$?</p> <p>A great source of randomness is a hash function. If the address is equal with the hash of a secret preimage $s$, we can conclude that the address is unspendable, since there isn't a polynomially bounded algorithm to find $x$ where $keccak(x)=h(s)$. This is only true if the second hash function is a different hash function, and it assumes it is impossible to find $x_1$ and $x_2$ such that $h_1(x_1)=h_2(x_2)$ in case $h_1$ and $h_2$ are different hash functions.</p> <p>Using the help of Zero-Knowledge proofs, we can hide the value of $s$! We just need to prove that we know a secret value $s$ where the address is $h(s)$. We can go even further. We can prove that an Ethereum accounts exists in the state-root, which holds some amount of ETH and is unspendable.</p> <p>By revealing this to the Ethereum blockchain and providing something like a nullifier (E.g. $h(s | 123)$ so that double minting of same burnt tokens are not possible), we can add a new <em><strong>minting</strong></em> functionality for ETH so that people can migrate their secretly burnt tokens to a completely new address, without any trace on the blockchain.</p> <p>Cryptocurrency mixers like TornadoCash can successfully obfuscate Ethereum transactions, but it's easy for the governments to ban usage of them. Anybody who has interactions with a mixer contract, whether the sender or receiver, can get marked. However this EIP tries to minimize the privacy leakage of the senders, by requiring zero smart-contract interactions in order to send money, so we only use plain EOA-to-EOA transfers. In order to have a "teleportation" mechanism we divide the set of all Secp256k1 points $E(K)$ into two subsets/address-spaces:</p> <ul> <li>The spendable address-space: $\{p \in \{0,1\}^{160} | \exists s : keccak(s \times G)=p \lor \exists c : keccak(c_{params})=p \}$</li> <li>The unspendable address-space: $\{p \in \{0,1\}^{160} | \nexists s : keccak(s \times G)=p \land \nexists c : keccak(c_{params})=p \}$</li> </ul> <p>The spendable/unspendable addresses are not distinguishable, so we can exploit this fact and define a spendability rule for the money sent to addresses that can't be spent using regular elliptic-curve signatures.</p> <p>Deposits are made by sending ether to an address <code>sha256(MAGIC_ADDRESS + secret)[12:]</code>, where you know the <code>secret</code>. This ensures that no one knows about the deposit unless you reveal it: a deposit onchain is not distinguishable from sending ether to a friend. Withdrawals use a zero-knowledge proof to prove knowledge of a previous deposit's <code>secret</code>.</p> <p>A deposit can come from two places: a standard deposit by sending ether, or a change deposit. A change deposit is automatically generated when withdrawing funds from another deposit (standard or change). The entire deposited amount does not have to be withdrawn; for example, if 20 ether was deposited and only 12 is withdrawn, the system will make a new change deposit of 8 ether. The value of this change deposit is hashed, so someone looking at the chain cannot calculate <code>change deposit value + withdrawal value = old deposit value</code> and use the value to expose the original deposit.</p> <p>This EIP requires that <a href="https://wg-eips.ritovision.com/7708/">EIP-7708</a> be in place along with an EIP to change receipts to SSZ format. This simplifies the proof as it only needs to verify a regular SHA256 Merkle branch verifying a log, there is no need to do verkle or RLP or other complex logic inside the proof. The log can be of two types: an EIP-7708 ETH transfer log, or a log generated by this EIP itself through the change mechanism.</p> <p>The EIP also includes a privacy pool <sup class="footnote-reference" id="fr-1-1"><a href="#fn-1">1</a></sup> mechanism where you must provide a privacy pool root, which corresponds to a list of deposits, so you prove that your deposit is one of the deposits in that list. Since this second Merkle branch mechanism is integrated into the proof, the marginal cost for a user to use it is zero, ensuring maximum adoption and maximizing the chance that privacy will be used responsibly. The privacy pools paper explains in much more detail the value of this privacy pools mechanism, and the benefits of an ecosystem where almost all legitimate users use it.</p> <p>The built-in PoW and 32 ETH limit prevent hash collision attacks: if an attacker can find collision <code>(x1, x2)</code> such that <code>create2_address(..., x1) == sha256(MAGIC_ADDRESS + x2)</code>, the attacker could extract their ether twice (but only twice). Such an attack requires approximately <code>2**80</code> hashes. Adding 24 bits of PoW increases the difficulty to <code>2**92</code>. This many hashes can be computed but is very difficult; currently, mining a Bitcoin block takes around <code>2**79</code> hashes, so those with the capabilities to attack this mechanism have a much more lucrative opportunity in Bitcoin mining.</p> <h3 id="scalability-implications">Scalability Implications</h3> <p>In case the circuits are able to simultaneously re-mint the sum of multiple burns in a single-proof, merchants and CEXs will be able to accept their payments in burn-addresses and accumulate their funds in a single address by storing a single proof (And a bunch of nullifiers) on the blockchain, which significantly reduces the transaction count on the blockchain. The people who will use this EIP as a scalability solution, will also increase the privacy guarantees of the protocol.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Ethers generated using the mint function should not have any difference with original Ethers. People should be able to use those minted Ethers for paying the gas fees.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>To be determined (TBD).</p> <h3 id="zk-snark-implementation">ZK-SNARK Implementation</h3> <p>Also TBD, but the implementation must meet the following conditions:</p> <ul> <li>Use a transparent setup; ideally reuse the <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a> setup. Do not use Groth16 or other application-specific setups.</li> <li>The circuit should be directly verifiable without blindly trusting compilers like Circom. SHA256 is not too complicated and can be implemented using PLOOKUP with an 8-bit lookup table for arithmetic operations, which should suffice. There is no need to over-focus on prover efficiency.</li> <li>Elliptic curves must still be used; Stark is too large.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>In case of faulty implementation of this EIP, people may mint infinite amount of ETH, collapsing the price of Ethereum.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> <section class="footnotes"> <ol class="footnotes-list"> <li id="fn-1"> <p>Buterin, V., Illum, J., Nadler, M., Schär, F., &amp; Soleimani, A. (n.d.). <span style="font-style: italic;">Blockchain Privacy and Regulatory Compliance: Towards a Practical Equilibrium</span>. https://doi.org/<a href="https://doi.org/10.2139/ssrn.4563364">10.2139/ssrn.4563364</a> (Original work published 2023) <a href="#fr-1-1">↩</a></p> </li> </ol> </section> 2023-08-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Andrei Maiborodahttps://github.com/gumb0 Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast https://wg-eips.ritovision.com/7480/

Instructions to read data section of EOF container

<h2 id="abstract">Abstract</h2> <p>Four new instructions are introduced, that allow to read EOF container's data section: <code>DATALOAD</code> loads 32-byte word to stack, <code>DATALOADN</code> loads 32-byte word to stack where the word is addressed by a static immediate argument, <code>DATASIZE</code> loads data section size and <code>DATACOPY</code> copies a segment of data section to memory.</p> <h2 id="motivation">Motivation</h2> <p>Clear separation between code and data is one of the main features of EOF1. Data section may contain anything, e.g. compiler's metadata, but to make it useful for smart contracts, EVM has to have instructions that allow to read from data section. Previously existing instructions for bytecode inspection (<code>CODECOPY</code>, <code>CODESIZE</code> etc.) are deprecated in EOF1 and cannot be used for this purpose.</p> <p>The <code>DATALOAD</code>, <code>DATASIZE</code>, <code>DATACOPY</code> instruction pattern follows the design of existing instructions for reading other kinds of data (i.e. returndata and calldata).</p> <p><code>DATALOADN</code> is an optimized version of <code>DATALOAD</code>, where data offset to read is set at compilation time, and therefore need not be validated at run-time, which makes the instruction cheaper.</p> <h2 id="specification">Specification</h2> <p>We introduce four new instructions on the same block number <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> is activated on:</p> <ol> <li><code>DATALOAD</code> (0xd0)</li> <li><code>DATALOADN</code> (0xd1)</li> <li><code>DATASIZE</code> (0xd2)</li> <li><code>DATACOPY</code> (0xd3)</li> </ol> <p>If the code is legacy bytecode, all of these instructions result in an <em>exceptional halt</em>. (<em>Note: This means no change to behaviour.</em>)</p> <p>If the code is valid EOF1, the following execution rules apply:</p> <h3 id="dataload"><code>DATALOAD</code></h3> <ol> <li>Pops one value, <code>offset</code>, from the stack.</li> <li>Reads <code>[offset:offset+32]</code> segment from the data section and pushes it as 32-byte value to the stack.</li> <li>If <code>offset + 32</code> is greater than the data section size, bytes after the end of data section are set to 0.</li> <li>Deducts 4 gas.</li> </ol> <h3 id="dataloadn"><code>DATALOADN</code></h3> <ol> <li>Has one immediate argument,<code>offset</code>, encoded as a 16-bit unsigned big-endian value.</li> <li>Pops nothing from the stack.</li> <li>Reads <code>[offset:offset+32]</code> segment from the data section and pushes it as 32-byte value to the stack.</li> <li>Deducts 3 gas.</li> </ol> <p><code>[offset:offset+32]</code> is guaranteed to be within data bounds by <a href="https://wg-eips.ritovision.com/7480/#code-validation">code validation</a>.</p> <h3 id="datasize"><code>DATASIZE</code></h3> <ol> <li>Pops nothing from the stack.</li> <li>Pushes the size of the data section of the active container to the stack.</li> <li>Deducts 2 gas.</li> </ol> <h3 id="datacopy"><code>DATACOPY</code></h3> <ol> <li>Pops three values from the stack: <code>mem_offset</code>, <code>offset</code>, <code>size</code>.</li> <li>Performs memory expansion to <code>mem_offset + size</code> and deducts memory expansion cost.</li> <li>Deducts <code>3 + 3 * ((size + 31) // 32)</code> gas for copying.</li> <li>Reads <code>[offset:offset+size]</code> segment from the data section and writes it to memory starting at offset <code>mem_offset</code>.</li> <li>If <code>offset + size</code> is greater than data section size, 0 bytes will be copied for bytes after the end of the data section.</li> </ol> <h3 id="code-validation">Code Validation</h3> <p>We extend code section validation rules (as defined in <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a>).</p> <ol> <li>Code section is invalid in case an immediate argument <code>offset</code> of any <code>DATALOADN</code> is such that <code>offset + 32</code> is greater than data section size, as indicated in the container header <em>before deployment</em>.</li> <li><code>RJUMP</code>, <code>RJUMPI</code> and <code>RJUMPV</code> immediate argument value (jump destination relative offset) validation: code section is invalid in case offset points to one of two bytes directly following <code>DATALOADN</code> instruction.</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="zero-padding-on-out-of-bounds-access">Zero-padding on out of bounds access</h3> <p>Existing instructions for reading other kinds of data implicitly pad with zeroes on out of bounds access, with the only exception of return data copying.</p> <p>It is beneficial to avoid exceptional failures, because compilers can employ optimizations like removing a code that copies data, but never accesses this copy afterwards, but such optimization is possible only if instruction never has other side effects like exceptional abort.</p> <h3 id="lack-of-extdatacopy">Lack of <code>EXTDATACOPY</code></h3> <p><code>EXTCODECOPY</code> instruction is deprecated and rejected in EOF contracts and does not copy contract code when being called in legacy with an EOF contract as target. A replacement instruction <code>EXTDATACOPY</code> has been considered, but decided against in order to reduce the scope of changes.</p> <p>Data-only contracts which previously relied on <code>EXTCODECOPY</code> are thereby discouraged, but if there is a strong need, support for them can be easily brought back by introducing <code>EXTDATACOPY</code> in a future upgrade.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change poses no risk to backwards compatibility, as it is introduced only for EOF1 contracts, for which deploying undefined instructions is not allowed, therefore there are no existing contracts using these instructions. The new instructions are not introduced for legacy bytecode (code which is not EOF formatted).</p> <h2 id="security-considerations">Security Considerations</h2> <p>Gas cost of these new opcodes is comparable to the legacy <code>CODECOPY</code> instruction. They must be carefully considered during the implementation of the EOF container validation algorithm.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-07-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Guy Gorenhttps://github.com/guy-gorenguy.nahsholim@gmail.com https://wg-eips.ritovision.com/7378/

Using geometric weights to average past block sizes into consideration

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a new formula to update the base fee, derived from <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>. The existing base fee update formula,</p> <p>$$b[i+1]\triangleq b[i] \cdot \left( 1+\frac{1}{8} \cdot \frac{s[i]-s^* }{s^* }\right)$$</p> <p>only considers the last block size $s[i]$. This mechanism incentivizes proposers to collude with users to manipulate the base fee.</p> <p>We propose that even previous block sizes be considered by replacing the last block size with an exponential moving average. In particular, we suggest the following base fee update formula:</p> <p>$$b[i+1]\triangleq b[i] \cdot \left( 1+\frac{1}{8} \cdot \frac{s_{\textit{avg}}[i]-s^* }{s^* }\right)$$</p> <p>where $s_{\textit{avg}}[i]$ is defined by:</p> <p>$$s_{\textit{avg}}[i] \triangleq \alpha\sum_{k=1}^{\infty} (1-\alpha)^k\cdot s[i-k+1]$$</p> <p>and $\alpha\in(0,1)$ is a smoothing factor.</p> <h2 id="motivation">Motivation</h2> <p>To reduce bribe motivation when the demand for blockspace is high (see Incentive Considerations section) and to reduce oscillations, thus, having a more stable fee setting mechanism.</p> <p>Proposers use a mechanism described in EIP-1559 to determine which messages to include in a block. This mechanism includes a "base fee": a portion of the transaction fee that is burned. The base fee varies according to the fill rate of blocks. A target block size is defined. If a block exceeds the target size, the base fee increases, and if it is smaller, the base fee lowers.</p> <p>Research on the subject have revealed issues with this transaction fee mechanism. It has been shown to be <a href="https://wg-eips.ritovision.com/7378/./assets/LMRSP.pdf">unstable in cases</a>. Moreover, it has been shown that the dynamic nature of the base fee, which is influenced by the fill rate of blocks, opens the door for <a href="https://wg-eips.ritovision.com/7378/./assets/AGHH.pdf">manipulation by miners (proposers) and users</a>. The desired behavior of the system under a stable high demand, is for it to reach an equilibrium where the base fee -- $b$ -- is the significant part of the gas fee, and the tip is relatively small -- denoted $\varepsilon$ (for reference, Ethereum's base fee often has $\frac{b}{\varepsilon}\approx 20$). According to <a href="https://wg-eips.ritovision.com/7378/./assets/TR1559.pdf">Roughgarden</a> this is a rational equilibrium under the assumption that proposers do not think ahead. However, we expect a proposer to optimize its behavior by also considering its future payoffs. In essence, since neither the proposer nor the user are getting the burnt fee, by colluding they can both tap into the burnt fee for a win-win situation for them both.</p> <p>A <a href="https://wg-eips.ritovision.com/7378/./assets/AGHH.pdf">theoretical work</a> describes how both proposers and users can initiate such an attack. For example, we can imagine that users who wish to pay lower costs will coordinate the attack. Roughly, a user (or group of users) that has transactions with a total $g$ amount of gas bribes the proposer of the current block (no matter the proposer's power) to propose an empty block instead. The cost of such a bribe is only $\varepsilon \times {s^* }$ -- the tip times the target block size. Consequently, the base fee reduces in the next block. If we accept that EIP-1559 reaches its goals, e.g., users would typically use a simple and honest bidding strategy of reporting their maximal willingness to pay plus adding a small tip ($\varepsilon$), then in the honest users' steady state, gas proposals leave the proposers with an $\varepsilon$ tip. Given that other users are naive (or slow to react), our bribing user will include its transactions with any tip larger than $\varepsilon$ -- making the attack profitable whenever $g \frac{b^* }{8} &gt;s^* \varepsilon$.</p> <h2 id="specification">Specification</h2> <p>$s[i]$ is replaced by $s_{\textit{avg}}[i]$, where:</p> <p>$$s_{\textit{avg}}[i] \triangleq \alpha\sum_{k=1}^{\infty} (1-\alpha)^k\cdot s[i-k+1]$$</p> <p>which simplifies to the recursive form</p> <p>$$s_{\textit{avg}}[i] = \alpha\cdot s[i] + (1-\alpha)\cdot s_{\textit{avg}}[i-1]$$</p> <p>where $\alpha\in(0, 1)$ is the smoothing factor. A higher smoothing factor means that the average responds more quickly to changes in block size (e.g., if $\alpha = 1$ the proposed formula degenerates to the existing rule).</p> <h2 id="rationale">Rationale</h2> <p>An intuitive option for the Transaction Fee Mechanism (TFM) that adjusts supply and demand economically is <em>First price auction</em>, which is well known and studied. Nevertheless, the Ethereum network choice was to use EIP-1559 for the TFM (one stated reason was to try and simplify the fee estimation for users, and reduce the advantage of sophisticated users). In this proposal, our design goal is to improve the TFM (of EIP-1559) by mitigating known problems that it raises. It is important to note that these problems severity are in direct relation to the demand for block space, and currently only mildly impact the Ethereum network. If demand to use Ethereum increases, however, these problems are expected to exacerbate. We may want to prepare for this beforehand.</p> <p>The change is based on <a href="https://wg-eips.ritovision.com/7378/./assets/AGHH.pdf">this work</a> that described a rational strategy in which bribes are profitable. Choosing to average based on a geometric series weights results in two desired properties: (i) the computation and space complexity are both in O(1), and (ii) the average gradually phases out the impact of a single outlier block without causing significant future fluctuations in the base fee. Moreover, the theoretical analysis does not consider the income from classic MEV strategies. (Actually, the described strategy may be seen as another form of MEV.) The fact that classic MEV (sandwich, front running, etc.) are not included in the analysis, means that the proposed solutions to classic MEV (obscuring transactions etc.) will also not help against the described strategy. The problem that we tackle in this EIP is at the core of the base fee mechanism, with no further assumptions (such as MEV or predictability of randomness).</p> <p>Remark: An additional alternative strategy that is not fully discussed <a href="https://wg-eips.ritovision.com/7378/./assets/AGHH.pdf">here</a> but one may consider is to reduce the 'max change denominator' (the learning rate) from 1/8 to something smaller. However, this is problematic since it significantly affects the responsiveness of the base fee, making it slow to respond to actual persistent changes. The reason for using geometric series weights is precisely to achieve the favorable tradeoff of still responding quickly while mitigating incentive misalignments.</p> <h3 id="incentive-considerations">Incentive Considerations</h3> <p>The proposal is designed to improve the incentive compatibility of the TFM. A <a href="https://wg-eips.ritovision.com/7378/./assets/AGHH.pdf">game theoretic analysis</a> shows that the current TFM, which is based on EIP-1559, encourages bribes.</p> <p>One of the main goals of EIP-1559 was to simplify the bidding for users. It was articulated <a href="https://wg-eips.ritovision.com/7378/./assets/TR1559.pdf">theoretically by Roughgarden</a> as users bidding their honest valuations being an optimal strategy. In contrast, when using first price auctions for the TFM (as done by Bitcoin and previously in Ethereum), it is typically sub-optimal for a user to bid its honest valuation. In other words, a TFM that encourages users to not fully reveal their preferences is considered less good. However, one may argue that a TFM that encourages bribes is worse than a TFM that encourages not revealing one's full preferences.</p> <p>Although a first price auction is a safe bet regarding TFMs, the Ethereum network chose to use EIP-1559 and burn transaction fees (perhaps for reasons other than game-theoretic ones). We therefore suggest to mitigate the current incentives for bribes using the above proposal.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change requires a hard fork since the base fee is enforced (for blocks to be considered valid).</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-07-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 lightclienthttps://github.com/lightclient Sam Wilsonhttps://github.com/samwilsn Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/7377/

Allow EOAs to send a one-time transaction which deploys code at their account.

<h2 id="abstract">Abstract</h2> <p>Introduce a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction type with the format <code>0x04 || rlp([chainId, nonce, maxFeePerGas, maxPriorityFeePerGas, gasLimit, codeAddr, storage, data, value, accessList, yParity, r, s])</code> which sets the sending account's <code>code</code> field in the state trie to the <code>code</code> value at <code>codeAddr</code> and applies the storage tuples to the sender's storage trie.</p> <h2 id="motivation">Motivation</h2> <p>Smart contract wallets have long been touted as the solution to Ethereum's user experience woes. As early as 2015, there were proposals for allowing smart contracts to originate transactions in hopes that new users would flock to smart contract wallets to store their assets. So far, only a fraction of users have elected to do so.</p> <p>Today, account abstraction is still an important goal in Ethereum and there are many efforts attempting to realize it. We're getting closer to succeeding at this, but unfortunately the years of failure have caused many users to simply rely on EOA.</p> <p>After a user has accumulated enough assets in an EOA, it is not tenable to migrate each individual asset to a new address. This is due both to the cost and to needing to manually sign and verify potentially hundreds of transactions.</p> <p>This is an overlooked piece of the problem. Converting <em>existing</em> users to smart contract wallets efficiently will expedite adoption and push forward better support and integrations for smart contract wallets. They will no longer be dismissed as a niche use case.</p> <p>Therefore, we must provide a mechanism, embedded in the protocol, to migrate EOAs to smart contracts. This EIP proposes such mechanism.</p> <h2 id="specification">Specification</h2> <p>At the fork block <code>X</code>, introduce the migration transaction type.</p> <h3 id="migration-transaction">Migration Transaction</h3> <h4 id="definition">Definition</h4> <table><thead><tr><th>field</th><th>type</th></tr></thead><tbody> <tr><td><code>chainId</code></td><td><code>uint256</code></td></tr> <tr><td><code>nonce</code></td><td><code>uint64</code></td></tr> <tr><td><code>maxFeePerGas</code></td><td><code>uint256</code></td></tr> <tr><td><code>maxPriorityFeePerGas</code></td><td><code>uint256</code></td></tr> <tr><td><code>gasLimit</code></td><td><code>uint64</code></td></tr> <tr><td><code>codeAddr</code></td><td><code>address</code></td></tr> <tr><td><code>storage</code></td><td><code>List[Tuple[uint256, uint256]]</code></td></tr> <tr><td><code>data</code></td><td><code>bytes</code></td></tr> <tr><td><code>value</code></td><td><code>uint256</code></td></tr> <tr><td><code>accessList</code></td><td><code>List[Tuple[address, List[uint256]]]</code></td></tr> <tr><td><code>yParity</code></td><td><code>uint8</code></td></tr> <tr><td><code>r</code></td><td><code>uint256</code></td></tr> <tr><td><code>s</code></td><td><code>uint256</code></td></tr> </tbody></table> <p>The EIP-2718 <code>TransactionType</code> is <code>0x04</code> and the <code>TransactionPayload</code> is <code>rlp([chainId, nonce, maxFeePerGas, maxPriorityFeePerGas, gasLimit, codeAddr, storage, data, value, accessList, yParity, r, s])</code>.</p> <p>The transaction's signature hash is <code>keccak256(0x04 || rlp([chainId, nonce, maxFeePerGas, maxPriorityFeePerGas, gasLimit, codeAddr, storage, data, value, accessList])</code></p> <h4 id="validation">Validation</h4> <p>A migration transaction is considered valid if the follow properties hold:</p> <ul> <li>all <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> properties, unless specified otherwise</li> <li>the code at <code>codeAddr</code> is less than the <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> limit of <code>24576</code></li> <li>the code at <code>codeAddr</code> must not have size <code>0</code></li> </ul> <p>The intrinsic gas calculation modified from <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> to be <code>21000 + 16 * non-zero calldata bytes + 4 * zero calldata bytes + 1900 * access list storage key count + 2400 * access list address count + 20000 * length of storage</code>.</p> <h4 id="processing">Processing</h4> <p>Executing a migration transaction has two parts.</p> <h5 id="contract-deployment">Contract Deployment</h5> <p>Unlike standard contract deployment, a migration transaction directly specifies what <code>code</code> value the sender's account should be set to.</p> <p>As the first step of processing the transaction, set the sender's <code>code</code> to <code>state[tx.codeAddr].code</code>. Next, for each tuple in <code>tx.storage</code> and the sender's storage trie, set <code>storage[t.first] = t.second</code>.</p> <h5 id="transaction-execution">Transaction Execution</h5> <p>Now instantiate an EVM call into the sender's account using the same rules as <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> and set the transaction's origin to be <code>keccak256(sender)[0..20]</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="no-to-address-field">No <code>to</code> address field</h3> <p>This transaction is only good for one-time use to migrate an EOA to a smart contract. It is designed to immediately call the deployed contract, which is at the sender's address, after deployment to allow the sender to do any kind of further processing.</p> <h3 id="code-pointer-for-deployment">Code pointer for deployment</h3> <p>Naively, one could design the migration transaction to have a field <code>code</code> of type <code>bytes</code>. However, there would be substantial duplication of code calldata, since many users will want to deploy the exact same thing (often a wallet). Using a pointer instead acknowledges this overwhelming use case for the transaction type, and exploits it as an optimization.</p> <h3 id="cheaper-storage">Cheaper storage</h3> <p>Since the storage is guaranteed to be empty, there is no need to read before write. This means only 20,000 gas is needed to pay for the <a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a> <code>SSTORE_SET_GAS</code> value. This is a small discount to the normal cost of <code>22,100</code>, which is <code>SSTORE_SET_GAS</code> plus the <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> <code>COLD_SLOAD_COST</code> of <code>2100</code>, because no load occurs.</p> <h3 id="intrinsic-does-not-account-for-contract-deployment">Intrinsic does not account for contract deployment</h3> <p>This takes advantage of the fact that clients tend to store a single, unique copy of code; no matter the number of deployments. Therefore, the only operation here is changing a pointer in the state trie to the desired code.</p> <p>Additionally, the EOA already exists because it has enough balance for the migration transaction to be considered valid. Therefore, we don't need to pay a premium for adding a new account into the state trie.</p> <h3 id="manipulating-transaction-origin">Manipulating transaction origin</h3> <p>Many applications have a security check <code>caller == origin</code> to verify the caller is an EOA. This is done to "protect" assets. While it is usually more of a bandage than an actual fix, we attempt to placate these projects by modifying the origin of the transaction so the check will continue performing its duty.</p> <h3 id="one-time-migration">One-time migration</h3> <p>There is no technical reason we couldn't allow EOAs to change their code at any time with this transaction type. The only inhibitor at the moment is <a href="https://wg-eips.ritovision.com/3607/">EIP-3607</a> which will cause migration transactions to be considered invalid if they come from an account with code already deployed. A functional reason for retaining this behavior though is that it makes it simpler to reason about contracts and their upgradability.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="blind-signing">Blind Signing</h3> <p>As with all sufficiently sophisticated account designs, if a user can be convinced to sign an arbitrary message, that message could be a migration transaction which is owned by a malicious actor instead of the user. This can generally be avoided if wallets treat these transactions with <em>extreme</em> care and create as much friction and verification as possible before completing the signature.</p> <h3 id="on-ecrecover">On <code>ecrecover</code></h3> <p>Applications standards such as <a href="https://wg-eips.ritovision.com/2612/">ERC-2612: Permit Extension</a> have exploited the cryptographic relationship between EOA addresses and their private keys. Many tokens today support this extension, allowing EOAs to approve the transfer of fund from their account using only a signature. Although collisions between EOAs and contract accounts are considered unlikely and <a href="https://wg-eips.ritovision.com/3607/">maybe impossible</a> given today's computing power, this EIP would make it common place for private keys to exist for contract accounts. There are some considerations here regarding security:</p> <ul> <li>The obvious attack is a defi protocol deploys some their contract using this EIP and later sign an <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> message to steal the funds accrued in the contract. This can be avoided by wallets simply not allowing users to interact with protocols deployed in this manner.</li> <li>It's also worth mentioning that there are concerns around how this EIP will affect the cross chain experience. Ultimately a users private key may still have some control over the account's assets, depending on the exact protocols used on Ethereum and on other chains. It isn't really possible perfectly migrate the EOA at the same time, on all chains. The best thing that can be done is to educate the user that just because their account has been migrated doesn't mean that they are safe to now publicly reveal their private key. This seems like a reasonable request, especially since they'll want to retain the private key in case they want to use the address on any other EVM-like chain.</li> </ul> <p>Something that may alleviate these issues to some degree would be to add an <code>EXTCODEHASH</code> check in <code>ecrecover</code>. If the recovered account has code, the precompile will revert. This would disallow migrated EOAs from using standards like <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-07-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 pcaversacciohttps://github.com/pcaversaccio https://wg-eips.ritovision.com/7266/

Remove the blake2f (0x09) precompile by changing the precompile behaviour to result in an exceptional abort

<h2 id="abstract">Abstract</h2> <p>This EIP removes the <a href="https://wg-eips.ritovision.com/152/"><code>blake2f</code></a> (<code>0x09</code>) precompile by changing the precompile behaviour to result in an exceptional abort.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/152/">EIP-152</a> has never capitalised on a real-world use case. This fact is clearly reflected in the number of times the address <code>0x09</code> has been invoked (numbers from the date this EIP was created):</p> <ul> <li>The most recent call took place on 6 October 2022.</li> <li>Since its gone live as part of the Istanbul network upgrade on December 7 2019 (block number 9,069,000), <code>0x09</code> has been called only 22,131 times.</li> </ul> <p>One of the reasons why <a href="https://wg-eips.ritovision.com/152/">EIP-152</a> has failed is that the envisioned use cases were not validated before inclusion.</p> <h2 id="specification">Specification</h2> <p>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>All <code>CALL</code>, <code>CALLCODE</code>, <code>DELEGATECALL</code>, and <code>STATICCALL</code> invocations to the <code>blake2f</code> precompile address <code>0x09</code> MUST result in an exceptional halting state that consumes all supplied gas and returns no data.</p> <h2 id="rationale">Rationale</h2> <p>The EVM should be optimised for simplicity and future-proofness. The original Yellow Paper states: <em>these are so-called 'precompiled' contracts, meant as a preliminary piece of architecture that may later become native extensions</em>. Considering that no use cases have been realised in the last 3.5 years, we can conclude that the precompile <code>blake2f</code> (<code>0x09</code>) will never transition into a native opcode. In that sense, the precompile <code>blake2f</code> (<code>0x09</code>) is an obsolete carry-along with no real-world traction and thus should be removed. This removal will simplify the EVM to the extent that it only consists of clear instructions with real-world use cases. Eventually, the precompile <code>blake2f</code> (<code>0x09</code>) can be safely used as a test run for the phase-out and removal of EVM functions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork as it modifies the consensus rules. Note that very few applications are affected by this change and a lead time of 6-12 months can be considered sufficient.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no known additional security considerations introduced by this change.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-05-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Sam Wilsonhttps://github.com/SamWilsn https://wg-eips.ritovision.com/7039/

Using custom protocol handlers to initiate connections between web pages and wallets.

<h2 id="abstract">Abstract</h2> <p>This proposal (affectionately known as SHADOW) is an alternative to <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> for wallet discovery in web browsers that requires no special permissions. Web pages intending to open a connection to a wallet inject an <code>iframe</code> tag pointing at a well-known scheme. Communication between the page and the wallet uses the <code>postMessage</code> API.</p> <h2 id="motivation">Motivation</h2> <p>Current wallet discovery methods (eg. <code>window.ethereum</code>) only support one active wallet at a time, and require browser extensions to request broad permissions to modify web pages.</p> <p>Ideally users should be able to have multiple wallets active, and choose between them at runtime. This not only results in an improved user experience but also reduces the barrier to entry for new browser extensions as users are no longer forced to only install one browser extension at a time.</p> <p>With SHADOW, and unlike other recent proposals, browser extensions do not need blanket <code>content_scripts</code> or any <code>permissions</code> at all. Furthermore, any web page (and not just browser extensions) can register a handler for a protocol. That means better support for pure web wallets, native executable wallets, and hardware wallets. As long as a wallet can serve a page securely, it can register itself as a handler.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="initiating-a-connection">Initiating a Connection</h3> <p>To initiate a connection to a provider, a web page SHOULD:</p> <ol> <li>Add an event listener to <code>window</code> for the <code>"message"</code> event (or set <code>window.onmessage</code>.)</li> <li>Create an <code>iframe</code> tag with a <code>src</code> attribute value of <code>web+evm://</code>; then</li> <li>Attach the <code>iframe</code> to the DOM.</li> <li>Wait for a <code>"message"</code> event with a non-nullish <code>source</code> equal to the <code>iframe</code>'s <code>contentWindow</code>.</li> <li>Save the first port from the message event for further communication. This is referred to as the "primary port."</li> </ol> <p>The event received in step 4 MAY contain additional information about the provider. If present, the event data SHALL satisfy the following TypeScript interface:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ProviderInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> name</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> icon</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Where:</p> <ul> <li><strong><code>name</code></strong> is the human-readable name of the provider; and</li> <li><strong><code>icon</code></strong> is a URI pointing at an image. See <a href="https://wg-eips.ritovision.com/7039/#icon-images">Icon Images</a>.</li> </ul> <h3 id="communicating-on-an-established-connection">Communicating on an Established Connection</h3> <p>The web page and wallet MAY make requests of the other. The party making the request is known as the requester, and the replying party is known as the responder.</p> <p>A requester MAY make requests of the responder by sending a message (using <code>postMessage</code>) on the primary port. The message MAY include a <code>MessagePort</code> as the first item of the message's transfer list to receive a reply. This port is known as a "reply port." The message's data MUST satisfy <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a>'s <code>RequestArguments</code> interface, and SHALL be interpreted as described there.</p> <p>The responder SHALL respond by posting a single message to the reply port, if a reply port was transferred. The message's data SHALL satisfy the following TypeScript interface, where <code>ProviderRpcError</code> is defined in EIP-1193:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> Response</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> result</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> unknown</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> error</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> ProviderRpcError</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Exactly one of <code>result</code> or <code>error</code> SHALL be present on the response.</p> <p>If present, <code>result</code> SHALL be equivalent to the <code>result</code> field of the named JSON-RPC method's response.</p> <p>Error objects SHOULD follow the recommendations set out in EIP-1193.</p> <p>A request without a transferred reply port SHALL NOT be considered an error, even if a reply would have been sent.</p> <h3 id="icon-images">Icon Images</h3> <!-- TODO --> <h2 id="rationale">Rationale</h2> <p>Instead of directly using the <code>iframe.contentWindow</code>'s message port, SHADOW transfers a message port in the first message. This allows the <code>iframe</code>, in some specific scenarios, to completely hand off communication, so the web page and the provider communicate directly, without any proxying in the <code>iframe</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>While not backwards compatible with EIP-1193, this proposal uses extremely similar data structures to make the transition as painless as possible.</p> <p>It is possible to implement an EIP-1193 compatible provider using this proposal like so:</p> <!-- TODO: Show example of implementing EIP-1193 provider on top of this proposal. --> <h2 id="security-considerations">Security Considerations</h2> <!-- TODO: Needs more discussion. --> <p>Both providers and web pages MUST verify the origin of messages before trusting them.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-05-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast Danno Ferrinhttps://github.com/shemnon Andrei Maiborodahttps://github.com/gumb0 Charles Cooperhttps://github.com/charles-cooper https://wg-eips.ritovision.com/7069/

Introduce EXTCALL, EXTDELEGATECALL and EXTSTATICCALL with simplified semantics

<h2 id="abstract">Abstract</h2> <p>Introduce three new call instructions, <code>EXTCALL</code>, <code>EXTDELEGATECALL</code> and <code>EXTSTATICCALL</code>, with simplified semantics. Introduce another instruction, <code>RETURNDATALOAD</code> for loading a word from return data into stack. Modify the behavior of <code>RETURNDATACOPY</code> instruction executed within EOF formatted code (as defined by <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>). The existing <code>*CALL</code> instructions are rejected by EOF validation.</p> <p>The new instructions do not allow specifying a gas limit, but rather rely on the "63/64th rule" (<a href="https://wg-eips.ritovision.com/150/">EIP-150</a>) to limit gas. An important improvement is the rules around the "stipend" are simplified, and callers do not need to perform special calculation whether the value is sent or not.</p> <p>Furthermore, the obsolete functionality of specifying output buffer address is removed in favor of using <code>RETURNDATACOPY</code> instead. For cases which would previously <code>*CALL</code> output into a buffer and then <code>MLOAD</code> from the buffer, <code>RETURNDATALOAD</code> is provided instead.</p> <p>Lastly, instead of returning a boolean for execution status, an extensible list of status codes is returned: <code>0</code> for success, <code>1</code> for revert, <code>2</code> for failure.</p> <h2 id="motivation">Motivation</h2> <p>Observability of gas has been a problem for very long. The system of gas has been (and likely must be) flexible in adapting to changes to both how Ethereum is used as well as changes in underlying hardware.</p> <p>Unfortunately, in many cases compromises or workarounds had to be made to avoid affecting call instructions negatively, mostly due to the complex semantics and expectations of them.</p> <p>This change removes gas observability from the new instructions and opens the door for new classes of contracts that are not affected by repricings. Furthermore, the legacy call instructions are rejected within EOF contracts, making sure they are mostly unaffected by changes in gas fees. Because these operations are required for removing gas observability they are required for EOF in lieu of the existing legacy instructions.</p> <p>It is important to note that starting Solidity 0.4.21, the compiler already passes all remaining gas to calls (using <code>call(gas(), ...</code>), unless the developer uses the explicit override (<code>{gas: ...}</code>) in the language. This suggests most contracts don't rely on controlling gas.</p> <p>Besides the above, this change introduces a convenience feature of returning more detailed status codes: <code>success (0)</code>, <code>revert (1)</code>, <code>failure (2)</code>. This moves from the boolean option to codes, which are extensible in the future.</p> <p>Lastly, the introduction of the <code>RETURNDATA*</code> instructions (<a href="https://wg-eips.ritovision.com/211/">EIP-211</a>) has obsoleted the output parameters of calls, in a large number of cases rendering them unused. Using the output buffers have caused "bugs" in the past: in the case of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, conflicting implementations caused a lot of trouble, where some would return something, while others would not. With relying on <code>RETURNDATA*</code> instructions this is implicitly clarified. This proposal also adds the "missing" <code>RETURNDATALOAD</code> instruction to round out returndata buffer access instructions.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td>WARM_STORAGE_READ_COST</td><td>100</td><td>From <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a></td></tr> <tr><td>COLD_ACCOUNT_ACCESS</td><td>2600</td><td>From <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a></td></tr> <tr><td>CALL_VALUE_COST</td><td>9000</td><td></td></tr> <tr><td>ACCOUNT_CREATION_COST</td><td>25000</td><td></td></tr> <tr><td>MIN_RETAINED_GAS</td><td>5000</td><td></td></tr> <tr><td>MIN_CALLEE_GAS</td><td>2300</td><td></td></tr> </tbody></table> <p>We introduce four new instructions:</p> <ul> <li><code>EXTCALL</code> (<code>0xf8</code>) with arguments <code>(target_address, input_offset, input_size, value)</code></li> <li><code>EXTDELEGATECALL</code> (<code>0xf9</code>) with arguments <code>(target_address, input_offset, input_size)</code></li> <li><code>EXTSTATICCALL</code> (<code>0xfb</code>) with arguments <code>(target_address, input_offset, input_size)</code></li> <li><code>RETURNDATALOAD</code> (<code>0xf7</code>) with argument <code>offset</code></li> </ul> <p>These four new instructions are undefined in legacy code and only available in EOF code.</p> <p>Execution semantics of <code>EXT*CALL</code>:</p> <ol> <li>Charge <code>WARM_STORAGE_READ_COST</code> gas.</li> <li>Pop required arguments from stack, halt with exceptional failure on stack underflow. <ul> <li><strong>NOTE</strong>: When implemented in EOF, stack underflow check is done during stack validation and runtime check is omitted.</li> </ul> </li> <li>If <code>value</code> is non-zero (only <code>EXTCALL</code>): <ul> <li>Halt with exceptional failure if the current frame is in <code>static-mode</code>.</li> <li>Charge <code>CALL_VALUE_COST</code> gas.</li> </ul> </li> <li>If <code>target_address</code> has any of the high 12 bytes set to a non-zero value (i.e. it does not contain a 20-byte address) then halt with an exceptional failure.</li> <li>Perform (and charge for) memory expansion using <code>[input_offset, input_size]</code>.</li> <li>If <code>target_address</code> is not in the <code>warm_account_list</code>, charge <code>COLD_ACCOUNT_ACCESS - WARM_STORAGE_READ_COST</code> gas.</li> <li>If <code>target_address</code> is not in the state and the call configuration would result in account creation, charge <code>ACCOUNT_CREATION_COST</code> gas. <ul> <li>The only such case in this EIP is if <code>value</code> is non-zero (only <code>EXTCALL</code>).</li> </ul> </li> <li>Calculate the gas available to callee as caller's remaining gas reduced by <code>max(floor(gas/64), MIN_RETAINED_GAS)</code>.</li> <li>Clear the returndata buffer.</li> <li>Fail with status code <code>1</code> returned on stack if any of the following is true (only gas charged until this point is consumed): <ul> <li>Gas available to callee at this point is less than <code>MIN_CALLEE_GAS</code>.</li> <li>Balance of the current account is less than <code>value</code> (only <code>EXTCALL</code>).</li> <li>Current call stack depth equals <code>1024</code>.</li> <li>(only <code>EXTDELEGATECALL</code>) <code>target_address</code> account in the state doesn't have EOF code to execute (in particular, <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> delegations should be resolved, as if <code>EXTCALL</code> was used)</li> </ul> </li> <li>Perform the call with the available gas and configuration.</li> <li>Push a status code on the stack: <ul> <li><code>0</code> if the call was successful.</li> <li><code>1</code> if the call has reverted (also can be pushed earlier in a light failure scenario described in step 10).</li> <li><code>2</code> if the call has failed (in case of general OOG failure or any scenario where all gas passed to the callee is burnt in case of an error).</li> </ul> </li> <li>Gas not used by the callee is returned to the caller.</li> </ol> <p>Execution semantics of <code>RETURNDATALOAD</code>:</p> <ol> <li>Charge <code>3</code> gas</li> <li>Pop 1 item from the stack, to be referred to as <code>offset</code></li> <li>Push 1 item onto the stack, the 32-byte word read from the returndata buffer starting at <code>offset</code>.</li> <li>If <code>offset + 32 &gt; len(returndata buffer)</code>, the result is zero-padded.</li> </ol> <p>Execution semantics of <code>RETURNDATACOPY</code> in EOF formatted code (<a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>) is modified as follows:</p> <ol> <li>Assume the 3 arguments popped from stack are <code>destOffset</code>, <code>offset</code> and <code>size</code>. <em>(no change)</em></li> <li>Performs memory expansion to <code>destOffset + size</code> and deducts memory expansion cost. <em>(no change)</em></li> <li>If <code>offset + size &gt; len(returndata buffer)</code> <strong>do not</strong> halt with exceptional failure, but instead set the <code>offset + size - len(returndata buffer)</code> memory bytes after the copied ones to zero.</li> <li>Gas charged for memory copying remains <code>3 * num_words(size)</code>, regardless of the number of bytes actually copied or set to zero.</li> </ol> <p>Execution of <code>RETURNDATACOPY</code> which is not in EOF formatted code (i.e. is in legacy code) is not changed.</p> <h2 id="rationale">Rationale</h2> <h3 id="removing-gas-selectability">Removing gas selectability</h3> <p>One major change from the original <code>CALL</code> series of instructions is that the caller has no control over the amount of gas passed in as part of the call. The number of cases where such a feature is essential are probably better served by direct protocol integration.</p> <p>Removing gas selectability also introduces a valuable property that future revisions to the gas schedule will benefit from: you can always overcome Out of Gas (OOG) errors by sending more gas as part of the transaction (subject to the block gas limit). Previously when raising storage costs (<a href="https://wg-eips.ritovision.com/1884/">EIP-1884</a>) some contracts that sent only a limited amount of gas to their calls were broken by the new costing.</p> <p>Hence some contracts had a gas ceiling they were sending to their next call, permanently limiting the amount of gas they could spend. No amount of extra gas could fix the issue as the call would limit the amount sent. The notion of a stipend floor is retained in this spec. This floor can be changed independent of the smart contracts and still preserve the feature that OOG halts can be fixed by sending more gas as part of the transaction.</p> <h3 id="stipend-and-63-64th-rule">Stipend and 63/64th rule</h3> <p>The purpose of the stipend is to have enough gas to emit logs (i.e. perform non-state-changing operations) when a "contract wallet" is called. The stipend is only added when the <code>CALL</code> instruction is used and the value is non-zero.</p> <p>The 63/64th rule has multiple purposes:</p> <p>a. to limit call depth, b. to ensure the caller has gas left to make state changes after a callee returns.</p> <p>Additionally, there is a call depth counter, and calls fail if the depth would exceed 1024.</p> <p>Before the 63/64th rule was introduced, it was required to calculate available gas semi-accurately on caller side. Solidity has a complicated ruleset where it tries to estimate how much it will cost on the caller side to perform the call itself, in order to set a reasonable gas value.</p> <p>We have changed the ruleset:</p> <p>The 63/64th rule is still applied, but</p> <ul> <li>At least <code>MIN_RETAINED_GAS</code> gas is retained prior to executing the callee,</li> <li>At least <code>MIN_CALLEE_GAS</code> gas is available to the callee.</li> </ul> <p>The <code>MIN_CALLEE_GAS</code> rule is a replacement for stipend: it simplifies the reasoning about the gas costs and is applied uniformly for all introduced <code>EXT*CALL</code> instructions. The following table visualizes the differences (note the discrepancy between <em>caller required gas</em> and <em>caller cost</em> for <code>CALL</code>).</p> <table><thead><tr><th></th><th>Caller required gas</th><th>Caller cost (burned gas)</th><th>Caller min retained gas</th><th>Callee min gas</th></tr></thead><tbody> <tr><td>CALL V=0</td><td>100</td><td>100</td><td>0</td><td>0</td></tr> <tr><td>CALL V≠0</td><td>100+9000</td><td>100+6700</td><td>0</td><td>2300</td></tr> <tr><td>DELEGATECALL</td><td>100</td><td>100</td><td>0</td><td>0</td></tr> <tr><td>STATICCALL</td><td>100</td><td>100</td><td>0</td><td>0</td></tr> <tr><td>EXTCALL V=0</td><td>100</td><td>100</td><td>5000</td><td>2300</td></tr> <tr><td>EXTCALL V≠0</td><td>100+9000</td><td>100+9000</td><td>5000</td><td>2300</td></tr> <tr><td>EXTDELEGATECALL</td><td>100</td><td>100</td><td>5000</td><td>2300</td></tr> <tr><td>EXTSTATICCALL</td><td>100</td><td>100</td><td>5000</td><td>2300</td></tr> </tbody></table> <ul> <li><strong>Caller required gas</strong>: the minimum amount of gas a caller is required to have to execute a call instruction, lower value causes caller's OOG,</li> <li><strong>Caller cost (burned gas)</strong>: the amount of gas deducted from the caller to execute the instruction, this amount is not available to the callee,</li> <li><strong>Caller min retained gas</strong>: the minimum amount of gas the caller is guaranteed to have after the call, if this cannot be guaranteed the call fails without even reaching the callee,</li> <li><strong>Callee min gas</strong>: the minimum gas limit for the callee's execution.</li> </ul> <p>Removing the call stack depth check was initially considered, but this would be incompatible with the original <code>*CALL</code> instructions, as well as <code>CREATE*</code> instructions, which can be intertwined with the new <code>EXT*CALL</code> instructions in the call stack. As such, keeping the call stack depth check involves no change affecting legacy code.</p> <p>Also, we find the simple (as opposed to the complex 63/64th rule) hard cap reassuring, that the call stack depth is limited, in case the gas rules can be bypassed. Lastly, the amount of gas to reach depth of 1024 is huge, but not absurdly huge, and we want to avoid constraining ourselves by dependency of this check on current gas limits.</p> <h3 id="output-buffers">Output buffers</h3> <p>The functionality of specifying output buffer address is removed, because it is added complexity and in a large number of cases implementers prefer to use <code>RETURNDATACOPY</code> instead. Even if they rely on the output buffer (like in the case of Vyper), they would still check the length with <code>RETURNDATASIZE</code>. In Solidity one exception is the case when the expected return size is known (i.e. non-dynamic return values), in this case Solidity still uses the output buffer. For these cases, <code>RETURNDATALOAD</code> is introduced, which simplifies the workflow of copying returndata into a (known) output buffer and using <code>MLOAD</code> from there; instead, <code>RETURNDATALOAD</code> can be used directly.</p> <h3 id="status-codes">Status codes</h3> <p>Current call instructions return a boolean value to signal success: 0 means failure, 1 means success. The Solidity compiler assumed this value is a boolean and thus uses the value as branch condition to status (<code>if iszero(status) { /* failure */ }</code>). This prevents us from introducing new status codes without breaking existing contracts. At the time of the design of <a href="https://wg-eips.ritovision.com/211/">EIP-211</a> the idea of return a specific code for revert was discussed, but ultimately abandoned for the above reason.</p> <p>We change the value from boolean to a status code, where <code>0</code> signals success and thus it will be possible to introduce more non-success codes in the future, if desired.</p> <p>Status code <code>1</code> is used for both reverts coming from the callee frame and light failures encountered (see step 10. of Execution Semantics) in the execution of the instructions. The reason for combining them is keeping the semantics similar to the original CALLs - both scenarios preserve unused gas and continue being indistinguishable to the caller.</p> <p>Status code <code>2</code> signals an exceptional failure in the callee execution, meaning an error occurred that consumed all remaining gas in the callee frame.</p> <h3 id="parameter-order">Parameter order</h3> <p>The order of parameters has been changed to move the <code>value</code> field to be the last. This allows the instructions to have identical encoding with the exception of the last parameter, and simplifies EVM and compiler implementations slightly.</p> <h3 id="opcode-encoding">Opcode encoding</h3> <p>Instead of introducing three new <code>EXT*CALL</code> opcodes we have discussed a version with an immediate configuration byte (flags). There are two main disadvantages to this:</p> <ol> <li>Some combination of flags may not be useful/be invalid, and this increases the testing/implementation surface.</li> <li>The instruction could take variable number of stack items (i.e. <code>value</code> for <code>EXTCALL</code>) would be a brand new concept no other instruction has.</li> </ol> <p>It is also useful to have these as new opcodes instead of modifying the existing CALL series inside of EOF. This creates an "escape hatch" in case gas observability needs to be restored to EOF contracts. This is done by adding the GAS and original CALL series opcodes to the valid EOF opcode list.</p> <h3 id="callcode"><code>CALLCODE</code></h3> <p>Since <code>CALLCODE</code> is deprecated, we do not introduce a counterpart here.</p> <h3 id="halting-when-target-address-is-not-a-20-byte-ethereum-addresses">Halting when <code>target_address</code> is not a 20-byte ethereum addresses</h3> <p>When existing <code>CALL</code> series operations encounter an address that does not fit into 20 bytes the current behavior is to mask the address so that it fits into 20 bytes, ignoring all high bytes. For the <code>EXT*CALL</code> operations a halt was chosen over treating the contract as empty for two reasons. First, it handles the case of sending value to an address that doesn't exist without having to create a special case. Second, it keeps the <code>warm_access_list</code> from needing to track anything that is not a 20-byte ethereum address.</p> <p>Smart contract developers should not rely on the operation reverting when such addresses are passed in. When a suitable proposal for the use of Address Space Extension is adopted it is expected that the <code>EXT*CALL</code> series of operations will adopt those changes.</p> <h3 id="new-instructions-undefined-in-legacy-this-eip-is-part-of-eof-only">New instructions undefined in legacy (this EIP is part of EOF only)</h3> <p>Initially an alternative scenario was considered to introduce these new instructions separately in the legacy EVM first to limit the scope of EOF change, but it was decided to include it as a part of the EOF upgrade and keep them undefined in the legacy EVM.</p> <h3 id="returndataload-and-returndatacopy-padding-behavior"><code>RETURNDATALOAD</code> and <code>RETURNDATACOPY</code> padding behavior</h3> <p>This EIP initially proposed keeping the halt-on-OOB behavior of legacy <code>RETURNDATACOPY</code>. This makes compilers optimizations harder, because unnecessary <code>RETURNDATA*</code> instructions cannot be optimized out without change to code semantics.</p> <p>It could be that only <code>RETURNDATALOAD</code> is given the padding behavior, but that would make it confusingly inconsistent with the closely related <code>RETURNDATACOPY</code> instruction.</p> <p>There also was the alternative to have <code>RETURNDATACOPY2</code> introduced with the padding behavior, available in EOF only, at the same time banning <code>RETURNDATACOPY</code> in EOF. This has been rejected in order to avoid multiplying opcodes, and also as suboptimal from the point of view of compiler implementation.</p> <h3 id="eof1-contracts-can-extdelegatecall-only-eof1-contracts">EOF1 contracts can <code>EXTDELEGATECALL</code> only EOF1 contracts</h3> <p>Legacy contracts can selfdestruct in three different ways (directly through <code>SELFDESTRUCT</code>, indirectly through <code>CALLCODE</code> and indirectly through <code>DELEGATECALL</code>). <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a> disables the first two possibilities, however the third possibility remains. Allowing EOF1 contracts to <code>EXTDELEGATECALL</code> only other EOF1 contracts allows the following strong statement: EOF1 contract can never be destructed. Attacks based on <code>SELFDESTRUCT</code> completely disappear for EOF1 contracts. These include destructed library contracts (e.g. Parity Multisig).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No existing instructions are changed and so we do not think any backwards compatibility issues can occur.</p> <h2 id="security-considerations">Security Considerations</h2> <p>It is expected that the attack surface will not grow. All of these operations can be modeled by existing operations with fixed gas (all available) and output range (zero length at zero memory).</p> <p>When implemented in EOF (where the GAS opcode and the original CALL operations are removed) existing out of gas attacks will be slightly more difficult, but not entirely prevented. Transactions can still pass in arbitrary gas values and clever contract construction can still result in specific gas values being passed to specific calls. It is expected the same surface will remain in EOF, but the ease of exploitation will be reduced.</p> <p>The legacy <code>*CALL</code> instructions allow to pass gas available for the callee. This ability is used to prevent reentrancy attack but in case of potential future gas repricing proposal this pattern does not give this guarantee any longer. Protecting against reentrancy should be resolved by using <code>TSTORE/TLOAD</code> instructions introduced in <a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a> or other solutions which do not rely on current gas schedule.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-05-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mikhail Kalininhttps://github.com/mkalinin https://wg-eips.ritovision.com/6988/

Prevents a slashed validator from being elected as a block proposer

<h2 id="abstract">Abstract</h2> <p>Introduces a modification to the consensus layer specification which ensures that slashed validator cannot be elected as block proposer.</p> <h2 id="motivation">Motivation</h2> <p>A block proposed by a slashed validator is rejected by the corresponding validity check in the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/3115d1140b23dd4c9c23fbd9e2428186cf816bde/specs/phase0/beacon-chain.md#block-header"><code>phase0/process_block_header</code></a> function as defined in the consensus layer specification.</p> <p>At the same time the definition of the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/3115d1140b23dd4c9c23fbd9e2428186cf816bde/specs/phase0/beacon-chain.md#compute_proposer_index"><code>phase0/compute_proposer_index</code></a> allows for a slashed validator to be elected as a proposer. This contradiction effectively leads to a missed proposal if it is supposed to be made by a slashed validator.</p> <p>The impact of the proposed fix in the case of a single slashing on Ethereum Mainnet is negligible but it becomes significant in the case of correlated slashings. For instance, a correlated slashing of <code>1/10th</code> of a validator set can lead to <code>1/10th</code> of missed proposals in a number of epochs after the slashing.</p> <h2 id="specification">Specification</h2> <p>Specification of the proposed change can be found in <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/0ad3972725e7c22e8edf3bab2dd7730acbe3c272/specs/_features/eip6988/beacon-chain.md"><code>/_features/eip6988/beacon-chain.md</code></a>.</p> <h2 id="rationale">Rationale</h2> <h3 id="modifying-get-beacon-proposer-index">Modifying <code>get_beacon_proposer_index</code></h3> <p>This function is modified to read a proposer index from a beacon state if a slot of a latest block header is the same as the <code>state.slot</code>.</p> <p>This modification is done to make the function return correct proposer index in the case when the proposer of a given block is being slashed during processing of the block.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This fix changes proposer election mechanism in a backwards incompatible way and requires a hard fork to be deployed.</p> <h2 id="test-cases">Test Cases</h2> <p>The following test cases were added to cover this change:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/0ad3972725e7c22e8edf3bab2dd7730acbe3c272/tests/core/pyspec/eth2spec/test/altair/block_processing/sync_aggregate/test_process_sync_aggregate.py#L712"><code>test_slashed_proposer_rewarded_for_sync_aggregate_inclusion</code></a></li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/0ad3972725e7c22e8edf3bab2dd7730acbe3c272/tests/core/pyspec/eth2spec/test/altair/block_processing/test_process_attestation.py#L17"><code>test_slashed_proposer_rewarded_for_attestation_inclusion</code></a></li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/0ad3972725e7c22e8edf3bab2dd7730acbe3c272/tests/core/pyspec/eth2spec/test/eip6988/unittests/validator/test_validator.py#L9"><code>test_slashed_validator_not_elected_for_proposal</code></a></li> <li><a rel="external" href="https://github.com/ethereum/consensus-specs/blob/0ad3972725e7c22e8edf3bab2dd7730acbe3c272/tests/core/pyspec/eth2spec/test/phase0/unittests/validator/test_validator_unittest.py#L520"><code>test_slashed_validator_elected_for_proposal</code></a></li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>Reference implementation is in the same place as <a href="https://wg-eips.ritovision.com/6988/#specification">Specification</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no observed security issues introduced by the proposed change.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-05-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Zak Colezak@numbergroup.xyz Zak Colehttps://github.com/zscole Kevin Owockikevin@supermodular.xyz lightclienthttps://github.com/lightclient https://wg-eips.ritovision.com/6968/

Contract Secured Revenue on an EVM based L2

<h2 id="abstract">Abstract</h2> <p>Contract Secured Revenue (CSR) allows smart contract developers to claim a percentage of all transaction fees paid by users when interacting with their smart contracts.</p> <p>This EIP proposes the introduction of CSR on EVM-based L2s which would provide smart contract developers who deploy on L2s access to revenue streams and/or public goods.</p> <h2 id="motivation">Motivation</h2> <p>Using protocol rewards of an L1 to fund smart contract development would be a big change to the way the current market works. This EIP <em>does not</em> advocate for any changes to the existing Ethereum L1.</p> <p>This EIP does advocate that L2s could begin to experiment with Contract Secured Revenue as a means of:</p> <ol> <li>creating a new revenue stream for smart contract developers</li> <li>creating a new way of funding public goods</li> <li>creating incentives for developers to deploy their dapps on your network</li> </ol> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td>REVENUE_SHARE_QUOTIENT</td><td>5</td></tr> </tbody></table> <h3 id="fee-mechanism">Fee Mechanism</h3> <p>The current <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fee behavior is modified so that <code>header.base_fee_per_gas * REVENUE_SHARE_QUOTIENT</code> per gas is reallocated proportionally, based on gas used, to each contract executed during the transaction.</p> <p>Implicitly, this means that no fees are redistributed to externally owned accounts (EOA).</p> <h4 id="gas-tracking">Gas Tracking</h4> <p>In order to fairly distribute the fee revenue, a new transaction-wide gas tracker is defined.</p> <p>When executing a block, maintain a mapping <code>gas_used_by_address</code> of <code>address</code> to <code>uint64</code>. This will track the amount of gas used by each address. For every EVM instruction that does not instantiate a new execution frame (e.g. <code>CALL</code>, <code>CALLCODE</code>, <code>DELEGATECALL</code>, <code>STATICCALL</code>, <code>CREATE</code>, and <code>CREATE2</code>), add the cost of the instruction to the address' current sum in the mapping.</p> <p>For EVM instructions which do instantiate new frames, greater care must be taken to determine the cost of the instruction to the calling frame. For simplicity, this cost is defined to be the total cost of the operation minus the amount of gas passed to the child frame. The gas passed to the child frame is determined via <a href="https://wg-eips.ritovision.com/150/">EIP-150</a>. The computed cost is added to the address' current sum in the mapping.</p> <p>Additionally:</p> <ul> <li>If the address does not exist in the mapping, it's total gas used is <code>0</code>.</li> <li>If the instructions throws an out-of-gas (OOG) error, all remaining gas allocated to execution frame is added to the current total gas used by the address.</li> <li>No other exceptional halt adds remaining gas to the counter for the address where the halt occurred.</li> </ul> <h4 id="setting-revenue-recipient">Setting Revenue Recipient</h4> <p>Revenue recipients are tracked via a new transaction wide mapping <code>revenue_recipient</code> of <code>address</code> to <code>address</code>. The default value for every key is the key itself. For example, unless set otherwise, the key <code>0xdead...beef</code> maps to the value <code>0xdead...beef</code>.</p> <p>To set a different revenue recipient, a new instruction <code>SETREVENUERECIPIENT</code> is introduced with the opcode <code>0x49</code>. The operation takes <code>1</code> stack element as input and outputs <code>0</code> stack elements.</p> <p>The <code>20</code> least significant bytes of the input stack element is the address of the new revenue recipient for the instruction's caller. The <code>revenue_recipient</code> entry is updated to reflect this.</p> <p>The instruction costs <code>3</code> gas.</p> <h4 id="dispersing-revenue">Dispersing Revenue</h4> <p>After a transaction completes, for every element (<code>addr</code>, <code>gas_used</code>) in <code>gas_used_by_address</code>, increase the balance of <code>revenue_recipient[addr]</code> by <code>gas_used * (header.base_fee_per_gas // REVENUE_SHARE_QUOTIENT)</code></p> <h2 id="rationale">Rationale</h2> <h3 id="tracking-gas-proportionally">Tracking Gas Proportionally</h3> <p>A simpler mechanism would be to send the full transaction revenue to the <code>to</code> value of the transaction. This, however, does not accurately reward the composition of many different smart contracts and applications. Additionally, it is not compatible with smart contract wallets which, by definition, are often the first destination of a transaction.</p> <p>Maintaining a transaction wide tracker of gas uses makes it possible to distribute revenue to contracts which are genuinely the most utilized.</p> <h3 id="ephemeral-revenue-recipient-mapping">Ephemeral Revenue Recipient Mapping</h3> <p>Constructing the revenue recipient mapping ephemerally during each transaction appears inefficient on the surface. This value is expected to be relatively static and even if it did need to change, the change could be facilitated by the recipient contract.</p> <p>Unfortunately such a change is much more invasive for the EVM. The recipient value would need to be stored somewhere. This would require a modification to the account structure in the state trie. Also, the recipient value would need to be set at some point. This would necessitate either a modification to the <code>CREATE*</code> opcodes or a new opcode, similar to <code>SETREVENUERECIPIENT</code>, that would be called by initcode to "initialize" the recipient value.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="increased-max-block-size-complexity">Increased Max Block Size/Complexity</h3> <p>Similar to EIP-1559, we must consider the effects this will have on block size. Depending on the method by which this is implemented, it could increase maximum block size in the event that a significant number of contracts opt-in to CSR.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-04-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 Lionhttps://github.com/dapplion Danny Ryanhttps://github.com/djrtwo https://wg-eips.ritovision.com/6914/

Reuse fully withdrawn and safe to reuse validator indices for new beacon chain deposits.

<h2 id="abstract">Abstract</h2> <p>Reuse fully withdrawn validator indices after a sufficient safe-to-reuse period has passed to eliminate the unbounded growth of the beacon chain validator list as the validator set churns.</p> <h2 id="motivation">Motivation</h2> <p>The beacon chain maintains a list of validators and a separate list of balances associated with each validator. When a new deposit for a new validator occurs, the current mechanism only appends, rather than reusing previously fully withdrawn validator indices. As validators fully withdraw and new validators enter, this means the two lists will grow unbounded.</p> <p>This specification allows for the reuse of validator indices in the event that it is safe to do so, eliminating the concerns around the unbounded validator list growth.</p> <h2 id="specification">Specification</h2> <h3 id="consensus-layer">Consensus Layer</h3> <p>The configuration values and mechanics of the specification can be found in the <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/1a38b83e5db8638ee01c9461cccf11e7d8a3ebce/specs/_features/eip6914">Consensus Layer specs</a>.</p> <p>Note that validator indices are reused in the event that the validator has been fully withdrawn <em>and</em> that the validator has been withdrawable for a sufficient safe period.</p> <h3 id="execution-layer">Execution Layer</h3> <p>This specification does not require any changes to the Execution Layer.</p> <h2 id="rationale">Rationale</h2> <p>The <code>validators</code> and <code>balances</code> lists are currently appended to each time a new Deposit for a new pubkey comes into the beacon chain. Due to the natural mechanics of stakers entering and leaving consensus over long time spans, these lists, thus the state size, will grow unbounded.</p> <p>Increased state size represents load and/or complexity in client implementations. This comes in the form of client memory footprint, state root calculations, validator set scans, and more. This is a relatively simple clean-up within the state transition that will prevent the unnecessary load and complexity of the otherwise unbounded lists.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible change to the Consensus Layer of Ethereum and must be scheduled with a hard fork.</p> <p>There are no forwards/backwards compatibility issues with the Execution Layer</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are work-in-progress within the standard Consensus Layer tests.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Validator indices cannot be immediately reused but instead must wait <code>SAFE_EPOCHS_TO_REUSE_INDEX</code> epochs to ensure that attestations cannot be "poisoned" with withdrawn validator signatures -- thus non-slashable -- for at least the weak subjectivity period.</p> <p>The attestation poisoning attack hinges upon two facts:</p> <ul> <li>The reuse of a validator index overwrites the previous validator's pubkey from the beacon state.</li> <li><code>AttesterSlashing</code>s includes validator indices to reconstruct signature participants.</li> </ul> <h3 id="details-of-the-attack">Details of the attack</h3> <p>Assume a 1/3 attacker. Attacker exits N validators on the honest chain, where N is a small fraction of the validator set. These validators leave the exit queue and are withdrawable within a few days. Now, N new deposits come in and overwrite the validators and most importantly their pubkeys.</p> <p>The attacker then constructs an alternative attacker chain from before any of the N voluntary exits, such that the original N validators are not exited and withdrawn. N is large enough such that at least one of the N keys is on average in every committee of the attacker chain. The attacker double-signs in an attempt to finalize the attacker chain but ensures that one of the N keys is mixed into any revealed double-signed aggregate attestation -- the individual attestations are unavailable, only aggregates. These malicious attestations are <em>not</em> includable in the honest chain because <code>AttesterSlashing</code>s rely upon mapping validator indices to particular pubkeys, thus breaking accountable safety.</p> <h3 id="mitigation">Mitigation</h3> <p>Not overwriting withdrawn validators for <code>SAFE_EPOCHS_TO_REUSE_INDEX</code> epochs (3x the max weak subjectivity period) ensures that attestations cannot be poisoned within the accountable safety security window.</p> <h3 id="alternative">Alternative</h3> <p>Note that if <code>AttesterSlashing</code>s included a list of pubkeys instead of validator indices, then this would not be an issue. However, this would require more breaking changes and would increase the data requirement of an <code>AttesterSlashing</code>, the largest Consensus Layer data type, by a factor of 6.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-04-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Renan Rodrigues de Souzahttps://github.com/RenanSouza2 https://wg-eips.ritovision.com/6888/

Check for math overflows and division by zero at EVM level

<h2 id="abstract">Abstract</h2> <p>This EIP adds arithmetics checks to EVM arithmetic and a new opcode jump conditionally if there were events. The list of check includes overflows, division by zero.</p> <h2 id="motivation">Motivation</h2> <p>The importance of math checks in smart contract projects is very clear. It was an OpenZeppelin library and then incorporated in Solidity's default behavior. Bringing this to EVM level can combine both gas efficiency and safety.</p> <h2 id="specification">Specification</h2> <p>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>Starting from <code>BLOCK_TIMESTAMP &gt;= HARDFORK_TIMESTAMP</code></p> <h3 id="constants">Constants</h3> <table><thead><tr><th>Constant</th><th>Type</th><th>Value</th></tr></thead><tbody> <tr><td><code>HARDFORK_TIMESTAMP</code></td><td><code>uint64</code></td><td><code>TBD</code></td></tr> <tr><td><code>UINT_MAX</code></td><td><code>uint256</code></td><td><code>2 ** 256 - 1</code></td></tr> <tr><td><code>INT_MIN</code></td><td><code>int256</code></td><td><code>-(2**255)</code></td></tr> </tbody></table> <h3 id="flags">Flags</h3> <table><thead><tr><th>Variable</th><th>Type</th><th style="text-align: left">Initial Value</th></tr></thead><tbody> <tr><td><code>carry</code></td><td><code>bool</code></td><td style="text-align: left">false</td></tr> <tr><td><code>overflow</code></td><td><code>bool</code></td><td style="text-align: left">false</td></tr> </tbody></table> <p>Two new flags are added to the EVM state: unsigned warning (<code>carry</code>) and signed warning (<code>overflow</code>). The scope of those flags are the same as the program counter.</p> <h3 id="definitions">Definitions</h3> <p>From this point forward <code>a</code>, <code>b</code> and <code>c</code> references the arguments in a math operation and <code>res</code> the output. <code>c</code> is only used if the operation takes 3 inputs.</p> <p>The function <code>sign(x)</code> is defined in the set of <code>uint256 -&gt; {NEGATIVE, ZERO, POSITIVE}</code></p> <h3 id="contidions">Contidions</h3> <p>The <code>carry</code> flag MUST be set in the following circumstances:</p> <ul> <li>When opcode is <code>ADD</code> (<code>0x01</code>) and <code>res &lt; a</code></li> <li>When opcode is <code>MUL</code> (<code>0x02</code>) and <code>a != 0 ∧ res / a != b</code></li> <li>When opcode is <code>SUB</code> (<code>0x03</code>) and <code>b &gt; a</code></li> <li>When opcode is <code>DIV</code> (<code>0x04</code>) or <code>MOD</code> (<code>0x06</code>); and <code>b == 0</code></li> <li>When opcode is <code>ADDMOD</code> (<code>0x08</code>) and <code>c == 0</code></li> <li>When opcode is <code>MULMOD</code> (<code>0x08</code>) and <code>c == 0</code></li> <li>When opcode is <code>EXP</code> (<code>0x0A</code>) and <code>a ** b &gt; UINT_MAX</code></li> <li>When opcode is <code>SHL</code> (<code>0x1b</code>) and <code>res &gt;&gt; a != b</code></li> </ul> <p>The <code>overflow</code> flag MUST be set in the following circumstances:</p> <ul> <li>When opcode is <code>ADD</code> (<code>0x01</code>) and <code>a != 0 ∧ b != 0 ∧ sign(a) == sign(b) ∧ sign(a) != sign(res)</code></li> <li>When opcode is <code>SUB</code> (<code>0x03</code>) and <code>(a != 0 ∧ b != 0 ∧ sign(a) != sign(b) ∧ sign(a) != sign(res)) ∨ (a == 0 ^ b == INT_MIN)</code></li> <li>When opcode is <code>MUL</code> (<code>0x02</code>) and <code>(a == -1 ∧ b == INT_MIN) ∨ (a == INT_MIN ∧ b == -1) ∨ (a != 0 ∧ (res / a != b))</code> (this <code>/</code> represents <code>SDIV</code>)</li> <li>When opcode is <code>SDIV</code> (<code>0x05</code>) or <code>SMOD</code> (<code>0x06</code>); and <code>b == 0 ∨ (a == INT_MIN ∧ b == -1)</code></li> <li>When opcode is <code>SHL</code> (<code>0x1b</code>) and <code>res &gt;&gt; a != b</code> (this <code>&gt;&gt;</code> represents <code>SAR</code>)</li> </ul> <h3 id="opcodes">Opcodes</h3> <h4 id="jumpc"><code>JUMPC</code></h4> <p>Consumes one argument from the stack, the possible pc dest, Conditionally alter the program counter depending on the <code>carry</code> flag. <code>J_JUMPC = carry ? µ_s[0] : µ_pc + 1</code> Clears both flags. <code>carry = overflow = false</code></p> <h4 id="jumpo"><code>JUMPO</code></h4> <p>Consumes one argument from the stack, the possible pc dest, Conditionally alter the program counter depending on the <code>ovewflow</code> flag. <code>J_JUMPO = carry ? µ_s[0] : µ_pc + 1</code> Clears both flags. <code>carry = overflow = false</code></p> <h3 id="gas">gas</h3> <p>The gas cost for both instructions is <code>G_high</code>, the same as <code>JUMPI</code>.</p> <h2 id="rationale">Rationale</h2> <p>EVM uses two's complement for negative numbers. The opcodes listed above triggers one or two flags depending if they are used for signed and unsigned numbers.</p> <p>The conditions described for each opcode is made with implementation friendliness in mind. The only exception is EXP as it is hard to give a concise test as most of the others relied on the inverse operation and there is no native <code>LOG</code>. Most <code>EXP</code> implementations will internally use <code>MUL</code> so the flag <code>carry</code> can be drawn from that instruction, not the <code>overflow</code>.</p> <p>Both flags are cleaned at the same time because the instructions are expected to be used when transitioning between codes where numbers are treated as signed or unsigned.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a new opcode and changes int EVM behavior.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>This is a new EVM behavior but each code will decide how to interact with it.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-04-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Guillaume Ballethttps://github.com/gballet https://wg-eips.ritovision.com/6873/

Execution clients must retain the preimages of addresses and slots accessed between the fork preceding the verge, and the verge itself.

<h2 id="abstract">Abstract</h2> <p>Enforce preimage collection by every node on the network from the fork preceding the verge, up to the fork. This is needed in case each node is responsible for their own conversion.</p> <h2 id="specification">Specification</h2> <p>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>Let <code>T_p</code> be the timestamp of the fork preceding the verge, and <code>T_v</code> the timestamp of the verge.</p> <ul> <li> <p>EL clients MUST save the preimage of each address and slot hashes they produce during the execution of all blocks produced between <code>T_p</code> and <code>T_v</code></p> </li> <li> <p>EL clients MAY start storing preimages outside of this time range as well</p> </li> <li> <p>Given a hash produced between <code>T_p</code> and <code>T_v</code>, EL clients SHOULD be able to show they have the preimage for that hash in their database</p> </li> <li> <p>EL clients SHOULD be able to download the preimages of the address and slot hashes that were produced before <code>T_v</code> from a publicly-available datastore</p> </li> </ul> <h2 id="rationale">Rationale</h2> <p>Switching to verkle trees require a complete rehashing of all tree keys. Most execution clients store all keys hashed, without their preimages, which as the time of print take up 70GB on mainnet. In order to make these preimages available to everyone, the following course of action are available to each user:</p> <ul> <li>Restart a full-sync with preimage retention enabled</li> <li>Download the preimages as a file</li> </ul> <p>The second option is the only acceptable option in practice, as a full-sync requires the syncing machine to be offline for several days, and therefore should not be simultaneously imposed to the entire network. A file download, however, poses a problem of data obsolescence as new preimages will immediately need to be added to the list as the chain progresses and new addresses are accessed. Updating the preimage file is not sufficient, since it takes more than a slot time to download over 70GB.</p> <p>To guarantee a timely availability of all preimages around the verkle transition time, each node is therefore responsible for updating the list of preimages between the fork preceding the Verge, and the Verge itself.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <!-- ## Test Cases TODO --> <h2 id="reference-implementation">Reference Implementation</h2> <p>All clients already implement preimage retention, at least as an option.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion. <!-- TODO --></p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-04-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/6810/

Allow transactions to be reversed after confirmation

<h2 id="abstract">Abstract</h2> <p>A new transaction type reverts one of a sender's prior transactions, and other transactions dependent on that state, recursively.</p> <h2 id="motivation">Motivation</h2> <p>While Ethereum has the capability of reversible transactions through smart contracts, instant settlement is the default. But sometimes users make mistakes. Most mistakes are discovered quickly. However, once the transaction is confirmed, it is settled. There are many use cases for reverting settled transactions. Some of the most-common mistakes are listed below.</p> <ul> <li>Wrong recipient</li> <li>Unintended consequences</li> <li>Got scammed</li> </ul> <p>This feature addresses these issues and more, ending all regret.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <p>A new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction is introduced with <code>TransactionType</code> <code>0x5a</code>. The <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>TransactionPayload</code> for this transaction is <code>rlp([chainId, nonce, revertNonce, budget, signatureYParity, signatureR, signatureS])</code>. The <code>signatureYParity, signatureR, signatureS</code> elements of this transaction represent a secp256k1 signature over <code>keccak256(0x5a || rlp([chainId, nonce, revertNonce, budget]))</code>. The <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>ReceiptPayload</code> for this transaction is <code>rlp([status, budgetUsed, removedLogsBloom, [newReceiptPayloads]])</code>, where <code>newReceiptPayloads</code> is a sequential array of the updated receipts of all reverted transactions.</p> <h3 id="block-gas-limit">Block gas limit</h3> <p>A transaction of type <code>0x5a</code> shall be the only transaction in its block.</p> <h3 id="cascading-revert-operation">Cascading revert operation</h3> <p>A transaction fee budget is initialized to the value specified by <code>budget</code>, denominated in ether. This budget is the transaction fee for this type of transaction. Reverted transaction fees are refunded from this budget. Should the budget be insufficient, the Ex Post Facto Cascading Revert transaction fails and the entire budget is paid to the <code>COINBASE</code> specified in the block header. Otherwise, the remainder of the budget after all transactions are reverted is paid to the <code>COINBASE</code> account.</p> <p>The state is rolled back to the start of the transaction specified by <code>revertNonce</code>. An access list is initialized empty. Any state previously modified by a reverted transaction is added to the access list. Any subsequent transaction reading or using state included in the access list must also be reverted. This operation cascades forward until the current block.</p> <p>State includes:</p> <ul> <li>ether balance</li> <li>contract code</li> <li>account nonce</li> <li>storage keys</li> </ul> <h3 id="snap-sync">Snap sync</h3> <p>Due to the large amount of state that may be modified by such a transaction, slower clients should use snap sync to load the new state.</p> <h2 id="rationale">Rationale</h2> <p>The transaction must fill the entire block to prevent MEV attacks.</p> <p>While some cascading reverts are highly consequential, others are considerably simpler. The budget ensures the full network cost of the operation is paid. For example, reversing a token transfer to the wrong recipient would be relatively cheap. On the other hand, it would be prohibitively expensive to revert all deposits to a custodial exchange.</p> <p>Transaction fees must be refunded from this budget rather than the prior block reward in order to protect the security of the consensus protocol.</p> <p>Snap sync should be safe because if the state root is invalid then the block producer could get slashed.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>If we find any backwards compatibility issue we can maybe reverse those transactions. If that doesn't work idk maybe need another hard fork.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li>Reverting a transaction that ever funded an account reverts all of that account's subsequent transactions.</li> <li>Reverting the transaction that deploys a contract reverts all transactions interacting with that contract.</li> <li>Reverting a transfer to a new account does not revert other transactions.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>Seems simple enough. TODO this later; should only take a few hours, tops.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This specification has been audited by Illinois Senator Robert Peters. No exploits were found.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-04-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Pandapip1https://github.com/Pandapip1 https://wg-eips.ritovision.com/6811/

Increases the block time to facilitate finality over cosmic distances

<h2 id="abstract">Abstract</h2> <p>This EIP makes a minimal number of changes to allow Ethereum to be used on the moon and other potentially habitable bodies in Earth's solar system. It changes the time between blocks, the per-block validator reward, and the number of blocks per epoch.</p> <h2 id="motivation">Motivation</h2> <p>It is impossible for today's Ethereum to literally "go to the moon" due to a limitation in the protocol: the block length. Should validators attempt to validate on the surface of the moon, they would find that the ~1.25 second communication delay (caused by the speed of light) might cause issues with synchronization, considering the 12-second timer between blocks. The validators would eventually be ejected on the terrestrial chain after leaking. If however a substantial number of validators are displaced (think 1/3), they might follow their own fork and would eventually eject the terrestrial to finalize their own chain.</p> <h2 id="specification">Specification</h2> <p>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> <ul> <li>The time between blocks MUST be changed from 12 seconds to 600 seconds (10 minutes).</li> <li>The per-block validator reward MUST be multiplied by 50</li> <li>The number of blocks per epoch MUST be reduced from 4 to 2</li> </ul> <h2 id="rationale">Rationale</h2> <ul> <li>The block gas limit is multiplied by fifty to compensate for the time between blocks being multiplied by fifty.</li> <li>The per-block validator reward is also multiplied by fifty to compensate for the time between blocks being multiplied by fifty.</li> <li>Epochs are changed to be 2 blocks long so that finality can be reached in a reasonable amount of time.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Many applications expect mainnet transactions to be included in a short amount of time. This would clearly no longer be the case. Such applications should switch to planetary rollups. Syncing rollups across heavenly bodies is outside the scope of this proposal.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Definitely needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-03-27T00:00:00+00:00 2026-02-11T14:49:27+00:00 pcaversacciohttps://github.com/pcaversaccio https://wg-eips.ritovision.com/6789/

This EIP suggests renaming gas to mana, as proposed by Vitalik Buterin in 2015

<h2 id="abstract">Abstract</h2> <p>This EIP suggests renaming <code>gas</code> to <code>mana</code>, as proposed by Vitalik Buterin in 2015.</p> <h2 id="motivation">Motivation</h2> <p>The underlying motivation for reviving Vitalik's original proposal from 2015 is that we have finally arrived at the age of Proof-of-Stake, and given the roadmap ahead (i.e. "The Surge", "The Scourge", "The Verge", "The Purge", and "The Splurge"), I consider this moment as the last opportunity to make such a far-reaching semantic change.</p> <h2 id="specification">Specification</h2> <p>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>The core term <code>gas</code> MUST be renamed to <code>mana</code>.</p> <p>The following opcodes MUST be renamed:</p> <ul> <li><code>GASPRICE</code> to <code>MANAPRICE</code>;</li> <li><code>GASLIMIT</code> to <code>MANALIMIT</code>; and</li> <li><code>GAS</code> to <code>MANA</code>.</li> </ul> <p>Additionally, the input parameters or outputs of the following opcodes MUST be renamed:</p> <ul> <li><code>CALL</code>'s <code>gas</code> input parameter to <code>mana</code>;</li> <li><code>CALLCODE</code>'s <code>gas</code> input parameter to <code>mana</code>;</li> <li><code>DELEGATECALL</code>'s <code>gas</code> input parameter to <code>mana</code>;</li> <li><code>STATICCALL</code>'s <code>gas</code> input parameter to <code>mana</code>;</li> <li><code>GASLIMIT</code>'s <code>gasLimit</code> output to <code>manaLimit</code>; and</li> <li><code>GAS</code>'s <code>gas</code> output to <code>mana</code>.</li> </ul> <p>Finally, the following RPC endpoints MUST be renamed:</p> <ul> <li><code>eth_estimateGas</code> to <code>eth_estimateMana</code>;</li> <li><code>eth_gasPrice</code> to <code>eth_manaPrice</code>; and</li> <li><code>eth_maxPriorityFeePerGas</code> to <code>eth_maxPriorityFeePerMana</code>.</li> </ul> <p>The description of the RPC endpoints MUST be renamed accordingly:</p> <ul> <li><code>eth_estimateMana</code>: Generates and returns an estimate of how much <code>mana</code> is necessary to allow the transaction to complete;</li> <li><code>eth_manaPrice</code>: Returns the current price per <code>mana</code> in wei; and</li> <li><code>eth_maxPriorityFeePerMana</code>: Returns the current <code>maxPriorityFeePerMana</code> per <code>mana</code> in wei.</li> </ul> <h2 id="rationale">Rationale</h2> <ul> <li><code>mana</code> reflects the increased environmental friendliness of Proof-of-Stake;</li> <li><code>mana</code> is generally understood to be ephemeral and non-transferable, which better represents the concept of <code>gas</code>; and</li> <li><code>mana</code> is generally portrayed as renewable, while (natural) <code>gas</code> is non-renewable.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is not backward compatible as it renames the core term <code>gas</code>.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="example-1">Example 1</h3> <p>If a transaction requires more <code>mana</code> than allowed by the <code>manaLimit</code>, it is reverted as an <em>out-of-mana</em> transaction.</p> <h3 id="example-2">Example 2</h3> <p>A Solidity contract to estimate the used <code>mana</code> via the new <code>manaleft()</code> syntax (replacing <code>gasleft()</code>) for dedicated function calls.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: AGPL-3.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> 0.8.19</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ManaMetering</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> oldWay</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> manaUsed</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> hiMom </span><span class="z-keyword">=</span><span class="z-string"> &quot;Hi Mom, &quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> missYou </span><span class="z-keyword">=</span><span class="z-string"> &quot;miss you.&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> startMana </span><span class="z-keyword">=</span><span class="z-entity z-name"> manaleft</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> concat </span><span class="z-keyword">=</span><span class="z-support"> string</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>hiMom</span><span>,</span><span> missYou</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> manaUsed </span><span class="z-keyword">=</span><span> startMana </span><span class="z-keyword">-</span><span class="z-entity z-name"> manaleft</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>concat</span><span>,</span><span> manaUsed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> newWay</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> manaUsed</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> hiMom </span><span class="z-keyword">=</span><span class="z-string"> &quot;Hi Mom, &quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> missYou </span><span class="z-keyword">=</span><span class="z-string"> &quot;miss you.&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> startMana </span><span class="z-keyword">=</span><span class="z-entity z-name"> manaleft</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> concat </span><span class="z-keyword">=</span><span class="z-support"> string</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span><span>hiMom</span><span>,</span><span> missYou</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> manaUsed </span><span class="z-keyword">=</span><span> startMana </span><span class="z-keyword">-</span><span class="z-entity z-name"> manaleft</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>concat</span><span>,</span><span> manaUsed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>In Vyper, the same behaviour can be replicated with the new transaction property <code>msg.mana</code>, which replaces <code>msg.gas</code>.</p> <h3 id="example-3">Example 3</h3> <p>An example of how to set the <code>manaLimit</code> in MetaMask:</p> <p><img src="https://wg-eips.ritovision.com/6789/./assets/MetaMask_ManaLimit.png" alt="MetaMask manaLimit" /></p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no security considerations directly related to the renaming of <code>gas</code> to <code>mana</code>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-03-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Dankrad Feisthttps://github.com/dankrad Kevaundray Wedderburnhttps://github.com/kevaundray Guillaume Ballethttps://github.com/gballet Piper Merriamhttps://github.com/pipermerriam Gottfried Heroldhttps://github.com/GottfriedHerold Ignacio Hagopianhttps://github.com/jsign Tanishq Jasoriahttps://github.com/tanishqjasoria Gajinder Singhhttps://github.com/g11tech Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/6800/

This introduces a new Verkle state tree alongside the existing MPT.

<h2 id="abstract">Abstract</h2> <p>Introduce a new Verkle state tree alongside the existing hexary Patricia tree. After the hard fork, the Verkle tree stores all edits to state and a copy of all accessed state, and the hexary Patricia tree can no longer be modified. This is a first step in a multi-phase transition to Ethereum exclusively relying on Verkle trees to store execution state.</p> <h2 id="motivation">Motivation</h2> <p>Verkle trees solve a key problem standing in the way of Ethereum being stateless-client-friendly: witness sizes. A witness accessing an account in today’s hexary Patricia tree is, in the average case, close to 3 kB, and in the worst case it may be three times larger. Assuming a worst case of 6000 accesses per block (15m gas / 2500 gas per access), this corresponds to a witness size of ~18 MB, which is too large to safely broadcast through a p2p network within a 12-second slot. Verkle trees reduce witness sizes to ~200 bytes per account in the average case, allowing stateless client witnesses to be acceptably small.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="verkle-tree-definition">Verkle tree definition</h3> <p>We define a Verkle tree here by providing the function to compute the root commitment given a set of 32-byte keys and 32-byte values. Algorithms for updating and inserting values are up to the implementer; the only requirement is that the root commitment after the update must continue to match the value computed from this specification. We will then define an embedding that provides the 32-byte key at which any particular piece of state information (account headers, code, storage) should be stored.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># Bandersnatch curve order</span></span> <span class="giallo-l"><span>BANDERSNATCH_MODULUS = \</span></span> <span class="giallo-l"><span>13108968793781547619861935127046491459309155893440570251786403306729687672801</span></span> <span class="giallo-l"><span># Bandersnatch Pedersen basis of length 256</span></span> <span class="giallo-l"><span>PEDERSEN_BASIS = [....]</span></span> <span class="giallo-l"><span>VERKLE_NODE_WIDTH = len(PEDERSEN_BASIS)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def group_to_scalar_field(point: Point) -&gt; int:</span></span> <span class="giallo-l"><span> # Not collision resistant. Not random oracle. </span></span> <span class="giallo-l"><span> # Binding for Pedersen commitments.</span></span> <span class="giallo-l"><span> assert isinstance(point, Point)</span></span> <span class="giallo-l"><span> if point == bandersnatch.Z:</span></span> <span class="giallo-l"><span> return 0</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> return point.map_to_base_field() % BANDERSNATCH_MODULUS</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>def compute_commitment_root(children: Sequence[int]) -&gt; Point:</span></span> <span class="giallo-l"><span> o = bandersnatch.Z</span></span> <span class="giallo-l"><span> for generator, child in zip(PEDERSEN_BASIS, children):</span></span> <span class="giallo-l"><span> o = bandersnatch.add(o, bandersnatch.mul(generator, child))</span></span> <span class="giallo-l"><span> return o</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def extension_and_suffix_tree(stem: bytes31, values: Dict[byte, bytes32]) -&gt; int:</span></span> <span class="giallo-l"><span> sub_leaves = [0] * 512</span></span> <span class="giallo-l"><span> for suffix, value in values.items():</span></span> <span class="giallo-l"><span> sub_leaves[2 * suffix] = int.from_bytes(value[:16], &#39;little&#39;) + 2**128</span></span> <span class="giallo-l"><span> sub_leaves[2 * suffix + 1] = int.from_bytes(value[16:], &#39;little&#39;)</span></span> <span class="giallo-l"><span> C1 = compute_commitment_root(sub_leaves[:256])</span></span> <span class="giallo-l"><span> C2 = compute_commitment_root(sub_leaves[256:])</span></span> <span class="giallo-l"><span> return compute_commitment_root([1, # Extension marker</span></span> <span class="giallo-l"><span> int.from_bytes(stem, &quot;little&quot;),</span></span> <span class="giallo-l"><span> group_to_scalar_field(C1),</span></span> <span class="giallo-l"><span> group_to_scalar_field(C2)] +</span></span> <span class="giallo-l"><span> [0] * 252)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def compute_main_tree_root(data: Dict[bytes32, int],</span></span> <span class="giallo-l"><span> prefix: bytes) -&gt; int:</span></span> <span class="giallo-l"><span> # Empty subtree: 0</span></span> <span class="giallo-l"><span> if len(data) == 0:</span></span> <span class="giallo-l"><span> return 0</span></span> <span class="giallo-l"><span> elif len(data) == 1:</span></span> <span class="giallo-l"><span> return list(data.values())[0]</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> sub_commitments = [</span></span> <span class="giallo-l"><span> compute_main_tree_root({</span></span> <span class="giallo-l"><span> key: value for key, value in data.items() if</span></span> <span class="giallo-l"><span> key[:len(prefix) + 1] == prefix + bytes([i])</span></span> <span class="giallo-l"><span> }, prefix + bytes([i]))</span></span> <span class="giallo-l"><span> for i in range(VERKLE_NODE_WIDTH)</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> return group_to_scalar_field(compute_commitment_root(sub_commitments))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def compute_verkle_root(data: Dict[bytes32, bytes32]) -&gt; Point:</span></span> <span class="giallo-l"><span> stems = set(key[:-1] for key in data.keys())</span></span> <span class="giallo-l"><span> data_as_stems = {}</span></span> <span class="giallo-l"><span> for stem in stems:</span></span> <span class="giallo-l"><span> commitment_data = Dict[byte, bytes32]()</span></span> <span class="giallo-l"><span> for i in range(VERKLE_NODE_WIDTH):</span></span> <span class="giallo-l"><span> if stem + bytes([i]) in data:</span></span> <span class="giallo-l"><span> commitment_data[i] = data[stem + bytes([i])]</span></span> <span class="giallo-l"><span> data_as_stems[stem] = extension_and_suffix_tree(stem, commitment_data)</span></span> <span class="giallo-l"><span> sub_commitments = [</span></span> <span class="giallo-l"><span> compute_main_tree_root({</span></span> <span class="giallo-l"><span> key: value for key, value in data.items() if</span></span> <span class="giallo-l"><span> key[0] == i</span></span> <span class="giallo-l"><span> }, bytes([i]))</span></span> <span class="giallo-l"><span> for i in range(VERKLE_NODE_WIDTH)</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> return compute_commitment_root(sub_commitments)</span></span></code></pre> <p>Note that a value of zero is not the same thing as a position being empty; a position being empty is represented as 0 in the bottom layer commitment, but a position being zero is represented by a different value in the suffix tree commitment (2**128 is added to value_lower to distinguish it from empty). This distinction between zero and empty is not a property of the existing Patricia tree, but it is a property of the proposed Verkle tree.</p> <p>In the rest of this document, saving or reading a number at some position in the Verkle tree will mean saving or reading the 32-byte little-endian encoding of that number.</p> <h3 id="illustration">Illustration</h3> <p>This is an illustration of the tree structure.</p> <p><img src="https://wg-eips.ritovision.com/6800/./assets/tree_structure.png" alt="tree structure" /></p> <h3 id="tree-embedding">Tree embedding</h3> <p>Instead of a two-layer structure as in the Patricia tree, in the Verkle tree we will embed all information into a single <code>key: value</code> tree. This section specifies which tree keys store the information (account header data, code, storage) in the state.</p> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td>BASIC_DATA_LEAF_KEY</td><td>0</td></tr> <tr><td>CODE_HASH_LEAF_KEY</td><td>1</td></tr> <tr><td>HEADER_STORAGE_OFFSET</td><td>64</td></tr> <tr><td>CODE_OFFSET</td><td>128</td></tr> <tr><td>VERKLE_NODE_WIDTH</td><td>256</td></tr> <tr><td>MAIN_STORAGE_OFFSET</td><td>256**31</td></tr> </tbody></table> <p><em>It’s a required invariant that <code>VERKLE_NODE_WIDTH &gt; CODE_OFFSET &gt; HEADER_STORAGE_OFFSET</code> and that <code>HEADER_STORAGE_OFFSET</code> is greater than the leaf keys. Additionally, <code>MAIN_STORAGE_OFFSET</code> must be a power of <code>VERKLE_NODE_WIDTH</code>.</em></p> <p>Note that addresses are always passed around as an <code>Address32</code>. To convert existing addresses to <code>Address32</code>, prepend with 12 zero bytes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def old_style_address_to_address32(address: Address) -&gt; Address32:</span></span> <span class="giallo-l"><span> return b&#39;\x00&#39; * 12 + address</span></span></code></pre><h4 id="header-values">Header values</h4> <p>These are the positions in the tree at which block header fields of an account are stored.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def hash_point_to_bytes(point: Point) -&gt; int:</span></span> <span class="giallo-l"><span> return group_to_scalar_field(point).to_bytes(32, &#39;little&#39;)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def pedersen_hash(inp: bytes) -&gt; bytes32:</span></span> <span class="giallo-l"><span> assert len(inp) &lt;= 255 * 16</span></span> <span class="giallo-l"><span> # Interpret input as list of 128 bit (16 byte) integers</span></span> <span class="giallo-l"><span> ext_input = inp + b&quot;\0&quot; * (255 * 16 - len(inp))</span></span> <span class="giallo-l"><span> ints = [2 + 256 * len(inp)] + \</span></span> <span class="giallo-l"><span> [int.from_bytes(ext_input[16 * i:16 * (i + 1)], &#39;little&#39;) for i in range(255)]</span></span> <span class="giallo-l"><span> return compute_commitment_root(ints).hash_point_to_bytes()</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def get_tree_key(address: Address32, tree_index: int, sub_index: int):</span></span> <span class="giallo-l"><span> # Assumes VERKLE_NODE_WIDTH = 256</span></span> <span class="giallo-l"><span> return (</span></span> <span class="giallo-l"><span> pedersen_hash(address + tree_index.to_bytes(32, &#39;little&#39;))[:31] +</span></span> <span class="giallo-l"><span> bytes([sub_index])</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>def get_tree_key_for_basic_data(address: Address32):</span></span> <span class="giallo-l"><span> return get_tree_key(address, 0, BASIC_DATA_LEAF_KEY)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Backwards compatibility for EXTCODEHASH </span></span> <span class="giallo-l"><span>def get_tree_key_for_code_hash(address: Address32):</span></span> <span class="giallo-l"><span> return get_tree_key(address, 0, CODE_HASH_LEAF_KEY)</span></span></code></pre> <p>An account's <code>version</code>, <code>balance</code>, <code>nonce</code> and <code>code_size</code> fields are packed with big-endian encoding in the value found at <code>BASIC_DATA_LEAF_KEY</code>:</p> <table><thead><tr><th>Name</th><th>Offset</th><th>Size</th></tr></thead><tbody> <tr><td><code>version</code></td><td>0</td><td>1</td></tr> <tr><td><code>code_size</code></td><td>5</td><td>3</td></tr> <tr><td><code>nonce</code></td><td>8</td><td>8</td></tr> <tr><td><code>balance</code></td><td>16</td><td>16</td></tr> </tbody></table> <p>Bytes <code>1..4</code> are reserved for future use.</p> <p>The current layout and encoding allow for an extension of <code>code_size</code> to 4 bytes without changing the account version.</p> <p>When any account header field is set, the <code>version</code> field is also set to zero. The <code>codehash</code> and <code>code_size</code> fields are set upon contract or EoA creation.</p> <h4 id="code">Code</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_tree_key_for_code_chunk(address: Address32, chunk_id: int):</span></span> <span class="giallo-l"><span> return get_tree_key(</span></span> <span class="giallo-l"><span> address,</span></span> <span class="giallo-l"><span> (CODE_OFFSET + chunk_id) // VERKLE_NODE_WIDTH,</span></span> <span class="giallo-l"><span> (CODE_OFFSET + chunk_id) % VERKLE_NODE_WIDTH</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>Chunk <code>i</code> stores a 32 byte value, where bytes 1…31 are bytes <code>i*31...(i+1)*31 - 1</code> of the code (ie. the i’th 31-byte slice of it), and byte 0 is the number of leading bytes that are part of PUSHDATA (eg. if part of the code is <code>...PUSH4 99 98 | 97 96 PUSH1 128 MSTORE...</code> where <code>|</code> is the position where a new chunk begins, then the encoding of the latter chunk would begin <code>2 97 96 PUSH1 128 MSTORE</code> to reflect that the first 2 bytes are PUSHDATA).</p> <p>For precision, here is an implementation of code chunkification:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH_OFFSET = 95</span></span> <span class="giallo-l"><span>PUSH1 = PUSH_OFFSET + 1</span></span> <span class="giallo-l"><span>PUSH32 = PUSH_OFFSET + 32</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>def chunkify_code(code: bytes) -&gt; Sequence[bytes32]:</span></span> <span class="giallo-l"><span> # Pad to multiple of 31 bytes</span></span> <span class="giallo-l"><span> if len(code) % 31 != 0:</span></span> <span class="giallo-l"><span> code += b&#39;\x00&#39; * (31 - (len(code) % 31))</span></span> <span class="giallo-l"><span> # Figure out how much pushdata there is after+including each byte</span></span> <span class="giallo-l"><span> bytes_to_exec_data = [0] * (len(code) + 32)</span></span> <span class="giallo-l"><span> pos = 0</span></span> <span class="giallo-l"><span> while pos &lt; len(code):</span></span> <span class="giallo-l"><span> if PUSH1 &lt;= code[pos] &lt;= PUSH32:</span></span> <span class="giallo-l"><span> pushdata_bytes = code[pos] - PUSH_OFFSET</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> pushdata_bytes = 0</span></span> <span class="giallo-l"><span> pos += 1</span></span> <span class="giallo-l"><span> for x in range(pushdata_bytes):</span></span> <span class="giallo-l"><span> bytes_to_exec_data[pos + x] = pushdata_bytes - x</span></span> <span class="giallo-l"><span> pos += pushdata_bytes</span></span> <span class="giallo-l"><span> # Output chunks</span></span> <span class="giallo-l"><span> return [</span></span> <span class="giallo-l"><span> bytes([min(bytes_to_exec_data[pos], 31)]) + code[pos: pos+31]</span></span> <span class="giallo-l"><span> for pos in range(0, len(code), 31)</span></span> <span class="giallo-l"><span> ]</span></span></code></pre><h4 id="storage">Storage</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def get_tree_key_for_storage_slot(address: Address32, storage_key: int):</span></span> <span class="giallo-l"><span> if storage_key &lt; (CODE_OFFSET - HEADER_STORAGE_OFFSET):</span></span> <span class="giallo-l"><span> pos = HEADER_STORAGE_OFFSET + storage_key</span></span> <span class="giallo-l"><span> else:</span></span> <span class="giallo-l"><span> pos = MAIN_STORAGE_OFFSET + storage_key</span></span> <span class="giallo-l"><span> return get_tree_key(</span></span> <span class="giallo-l"><span> address,</span></span> <span class="giallo-l"><span> pos // VERKLE_NODE_WIDTH,</span></span> <span class="giallo-l"><span> pos % VERKLE_NODE_WIDTH</span></span> <span class="giallo-l"><span> )</span></span></code></pre> <p>Note that storage slots in the same size <code>VERKLE_NODE_WIDTH</code> range (ie. a range the form <code>x*VERKLE_NODE_WIDTH ... (x+1)*VERKLE_NODE_WIDTH-1)</code> are all, with the exception of the <code>HEADER_STORAGE_OFFSET</code> special case, part of a single commitment. This is an optimization to make witnesses more efficient when related storage slots are accessed together. If desired, this optimization can be exposed to the gas schedule, making it more gas-efficient to make contracts that store related slots together (however, Solidity already stores in this way by default).</p> <h4 id="fork">Fork</h4> <p>Described in <a href="https://wg-eips.ritovision.com/7612/">EIP-7612</a>.</p> <h4 id="access-events">Access events</h4> <p>Described in <a href="https://wg-eips.ritovision.com/4762/">EIP-4762</a>.</p> <h2 id="rationale">Rationale</h2> <p>This implements all of the logic in transitioning to a Verkle tree, and at the same time reforms gas costs, but does so in a minimally disruptive way that does not require simultaneously changing the whole tree structure. Instead, we add a new Verkle tree that starts out empty, and only new changes to state and copies of accessed state are stored in the tree. The Patricia tree continues to exist, but is frozen.</p> <p>This sets the stage for a future hard fork that swaps the Patricia tree in-place with a Verkle tree storing the same data. Unlike <a href="https://wg-eips.ritovision.com/2584/">EIP-2584</a>, this replacement Verkle tree does not need to be computed by clients in real time. Instead, because the Patricia tree would at that point be fixed, the replacement Verkle tree can be computed off-chain.</p> <h3 id="verkle-tree-design">Verkle tree design</h3> <p>The Verkle tree uses a single-layer tree structure with 32-byte keys and values for several reasons:</p> <ul> <li><strong>Simplicity</strong>: working with the abstraction of a key/value store makes it easier to write code dealing with the tree (eg. database reading/writing, caching, syncing, proof creation and verification) as well as to upgrade it to other trees in the future. Additionally, witness gas rules can become simpler and clearer.</li> <li><strong>Uniformity</strong>: the state is uniformly spread out throughout the tree; even if a single contract has many millions of storage slots, the contract’s storage slots are not concentrated in one place. This is useful for state syncing algorithms. Additionally, it helps reduce the effectiveness of unbalanced tree filling attacks.</li> <li><strong>Extensibility</strong>: account headers and code being in the same structure as storage makes it easier to extend the features of both, and even add new structures if later desired.</li> </ul> <h3 id="gas-reform">Gas reform</h3> <p>Gas costs for reading storage and code are reformed to more closely reflect the gas costs under the new Verkle tree design. WITNESS_CHUNK_COST is set to charge 6.25 gas per byte for chunks, and WITNESS_BRANCH_COST is set to charge ~13,2 gas per byte for branches on average (assuming 144 byte branch length) and ~2.5 gas per byte in the worst case if an attacker fills the tree with keys deliberately computed to maximize proof length.</p> <p>The main differences from gas costs in Berlin are:</p> <ul> <li>200 gas charged per 31 byte chunk of code. This has been estimated to increase average gas usage by ~6-12%</li> <li>Cost for accessing adjacent storage slots (<code>key1 // 256 == key2 // 256</code>) decreases from 2100 to 200 for all slots after the first in the group,</li> <li>Cost for accessing storage slots 0…63 decreases from 2100 to 200, including the first storage slot. This is likely to significantly improve performance of many existing contracts, which use those storage slots for single persistent variables.</li> </ul> <p>Gains from the latter two properties have not yet been analyzed, but are likely to significantly offset the losses from the first property. It’s likely that once compilers adapt to these rules, efficiency will increase further.</p> <p>The precise specification of when access events take place, which makes up most of the complexity of the gas repricing, is necessary to clearly specify when data needs to be saved to the period 1 tree.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The main backwards-compatibility-breaking changes are:</p> <ul> <li>(1) Gas costs for code chunk access making some applications less economically viable</li> <li>(2) Tree structure change makes in-EVM proofs of historical state no longer work</li> </ul> <p>(1) can be mitigated by increasing the gas limit at the same time as implementing this EIP, reducing the risk that applications will no longer work at all due to transaction gas usage rising above the block gas limit.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO</p> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li>github.com/gballet/go-ethereum, branch beverly-hills-just-after-pbss - a geth implementation</li> <li>github.com/NethermindEth/nethermind, branch verkle/tree - a nethermind implementation</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-03-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Jared Wasingerhttps://github.com/jwasinger Alex Beregszaszihttps://github.com/axic Vitalik Buterinhttps://github.com/vbuterin Radosław Zagórowiczhttps://github.com/rodiazet Paweł Bylicahttps://github.com/chfast https://wg-eips.ritovision.com/6690/

Expanded-width, efficient modular arithmetic operations for the EVM

<h2 id="abstract">Abstract</h2> <p>This EIP proposes new EVM modular arithmetic opcodes which support operations on odd or power-of-two moduli between 3 and 2**768-1</p> <h2 id="motivation">Motivation</h2> <p>Current opcodes for modular arithmetic only support values up to 256 bits wide. In addition, they are permissive and accept any representable value for the inputs.</p> <p>Many cryptographic operations are heavily-bottlenecked by modular arithmetic. To expand the range of cryptographic primitives that can be implemented efficiently as EVM contracts, we propose new modular arithmetic opcodes designed for efficiency.</p> <h2 id="specification">Specification</h2> <h3 id="constants">Constants</h3> <table><thead><tr><th>Name</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>COST_SETMODX_BASE</code></td><td>1</td><td>static cost component for the <code>SETMODX</code> opcode</td></tr> <tr><td><code>COST_STOREX_BASE</code></td><td>1</td><td>static cost for the <code>STOREX</code> opcode</td></tr> <tr><td><code>COST_LOADX_BASE</code></td><td>1</td><td>static cost for the <code>LOADX</code> opcode</td></tr> </tbody></table> <h3 id="conventions">Conventions</h3> <ol> <li>The use of <code>assert</code> implies that if the assertion fails, the current call frame will consume all call gas and terminate call execution in an exceptional state.</li> <li>Unless otherwise stated, the implied unit for size is bytes.</li> </ol> <h3 id="overview">Overview</h3> <p>The execution state of an EVM call frame is modified to include a mapping of <code>id</code> (a number 0-256) to a field context. A field context comprises a modulus and an allocated space of virtual registers to perform modular arithmetic operations on.</p> <p>An executing contract uses a new instruction <code>SETMODX</code> to set the active field context, allocating a new one in the mapping if it does not already exist for <code>id</code>.</p> <p>New arithmetic opcodes perform modular addition, subtraction and multiplication with inputs/outputs from virtual registers of the active field context.</p> <p>New load/store opcodes copy values to and from EVM memory and the virtual registers allocated by the active field context.</p> <h3 id="new-opcodes">New Opcodes</h3> <h4 id="setmodx-0xc0"><code>SETMODX(0xc0)</code></h4> <p><strong>Input</strong>: <code>&lt;top of stack&gt; id modulus_offset modulus_size alloc_count</code>.</p> <p><strong>Output</strong>: none</p> <h5 id="execution">Execution</h5> <p>Charge <code>COST_SETMODX_BASE</code>.</p> <p>Assert <code>0 &lt;= id &lt;= 256</code>.</p> <p>If a field context for <code>id</code> exists in this call scope:</p> <ul> <li>Set it as the active one.</li> </ul> <p>Otherwise:</p> <ul> <li>Assert <code>modulus_size &lt;= 96</code>.</li> <li>Assert that the byte range<code>[modulus_offset, modulus_offset+modulus_size]</code> falls within EVM memory.</li> <li>Load the byte range from EVM memory, interpreting it as a big endian <code>modulus</code>.</li> <li>Assert <code>modulus</code> is odd or is a power of two.</li> <li>Assert <code>3 &lt;= modulus &lt;= 2**768 - 1</code>.</li> <li>Assert <code>0 &lt; alloc_count &lt;= 256</code>.</li> <li>Define the size of elements stored in virtual registers: <code>element_size</code> as the size needed to represent the modulus padded to be a multiple of 64 bits. Implementations will align virtual register values along system-word lines.</li> <li>assert that the new size of all virtual registers allocated in the current call-context does not exceed 24576 bytes.</li> <li>Charge EVM memory expansion cost to expand memory by <code>alloc_count * element_size</code> bytes:.</li> <li>if the modulus is odd, charge the dynamic cost component (defined below)</li> <li>Allocate the new field context with <code>alloc_count</code> initially-zeroed registers. Associate it with <code>id</code> in the mapping.</li> <li>The new field context is now set as the active one.</li> </ul> <h5 id="dynamic-cost-component-for-odd-moduli">Dynamic Cost Component for Odd Moduli</h5> <table><thead><tr><th>Modulus size (padded to nearest 64 bits)</th><th>cost</th></tr></thead><tbody> <tr><td>64 bits</td><td>23</td></tr> <tr><td>128 bits</td><td>26</td></tr> <tr><td>192 bits</td><td>29</td></tr> <tr><td>256 bits</td><td>32</td></tr> <tr><td>320 bits</td><td>36</td></tr> <tr><td>384 bits</td><td>39</td></tr> <tr><td>448 bits</td><td>42</td></tr> <tr><td>512 bits</td><td>45</td></tr> <tr><td>576 bits</td><td>48</td></tr> <tr><td>640 bits</td><td>51</td></tr> <tr><td>704 bits</td><td>54</td></tr> <tr><td>768 bits</td><td>58</td></tr> </tbody></table> <p>The values in this table are based on the following linear cost model:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def cost_setmodx_dynamic(modulus_size: int) -&gt; int:</span></span> <span class="giallo-l"><span> limb_count = (modulus_size + 7) / 8</span></span> <span class="giallo-l"><span> return round(limb_count * 3.13 + 19.94)</span></span></code></pre><h4 id="arithmetic-opcodes">Arithmetic Opcodes</h4> <p>Opcodes <code>ADDMODX(0xc3)</code>, <code>SUBMODX(0xc4)</code>, <code>MULMODX(0xc5)</code> take a 7 byte immediate interpreted as byte values <code>out_idx</code>, <code>out_stride</code>, <code>x_idx</code>, <code>x_stride</code>, <code>y_idx</code>, <code>y_stride</code>, <code>count</code>.</p> <p>Define cost tables for each arithmetic operation based on the modulus:</p> <table><thead><tr><th>Modulus size (padded to nearest 64 bits)</th><th>cost per add/sub</th><th>cost per mul</th></tr></thead><tbody> <tr><td>64</td><td>1</td><td>1</td></tr> <tr><td>128</td><td>1</td><td>1</td></tr> <tr><td>192</td><td>1</td><td>1</td></tr> <tr><td>256</td><td>1</td><td>2</td></tr> <tr><td>320</td><td>1</td><td>2</td></tr> <tr><td>384</td><td>1</td><td>3</td></tr> <tr><td>448</td><td>1</td><td>4</td></tr> <tr><td>512</td><td>2</td><td>5</td></tr> <tr><td>576</td><td>2</td><td>7</td></tr> <tr><td>640</td><td>2</td><td>8</td></tr> <tr><td>704</td><td>2</td><td>10</td></tr> <tr><td>768</td><td>2</td><td>12</td></tr> </tbody></table> <p>The values in this table correspond to the following cost models:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>def cost_add_or_sub(modulus_size: int) -&gt; int:</span></span> <span class="giallo-l"><span> limb_count = (modulus_size + 7) // 8</span></span> <span class="giallo-l"><span> return round(limb_count * 0.12 + 0.58)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>def cost_mul(modulus_size: int) -&gt; int:</span></span> <span class="giallo-l"><span> limb_count = (modulus_size + 7) // 8</span></span> <span class="giallo-l"><span> return round((0.08 * limb_count**2) + (-0.06 * limb_count) + 0.75)</span></span></code></pre> <p>Execution asserts:</p> <ul> <li>all accessed values fall within bounds: <code>max([out_idx + (out_stride * count), x_idx + (x_stride * count), y_idx + (y_stride * count)]) &lt; len(field_context.registers)</code></li> <li><code>out_stride != 0</code></li> <li><code>count != 0</code></li> <li>an active field context <code>active_ctx</code> is set.</li> </ul> <p>Then, charge <code>count * operation_cost</code> where <code>operation_cost</code> is drawn from the cost table. Compute:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>for i in range(count):</span></span> <span class="giallo-l"><span> active_ctx.registers[out_idx+i*out_stride] = operation(active_ctx.registers[x_idx+i*x_stride], active_ctx.registers[y_idx+i*y_stride])</span></span></code></pre> <p>Where <code>operation</code> computes modular addition, subtraction or multiplication depending on the opcode.</p> <p>Note: Inputs/outputs can overlap. <code>active_ctx.registers</code> is not modified until all operations in the loop have completed.</p> <h4 id="data-transfer-opcodes">Data Transfer Opcodes</h4> <p>Note: serialization format for values in EVM memory: big-endian padded to <code>active_ctx.element_size</code> bytes.</p> <h5 id="loadx-0xc1"><code>LOADX(0xc1)</code></h5> <p><strong>Stack in</strong>: <code>(top of stack) dest source count</code></p> <p><strong>Stack out</strong>: none</p> <p><strong>Description</strong>: copies values from registers in the currently-active field context to EVM memory.</p> <h6 id="execution-1">Execution</h6> <ul> <li>Assert that a field context is set as active in the current call frame.</li> <li>Assert that the range <code>[source, source + count]</code> falls within the active field context's zero-indexed value space.</li> <li>Assert that the range <code>[dest, dest + count * active_ctx.element_size]</code> falls entirely within EVM memory.</li> <li>If modulus is a power of two: <ul> <li>charge <code>(active_ctxt.element_size + 31) // 32 * 3</code> gas (the same as the memory copying component for the <code>MCOPY</code> opcode)</li> </ul> </li> <li>If modulus is odd: <ul> <li>charge <code>count * operation_cost</code> gas, where <code>operation_cost</code> is looked up from the multiplication cost table, given <code>active_ctxt.element_size</code>.</li> </ul> </li> <li>copy virtual register values <code>[source, source + count]</code> to memory <code>[dest, dest + count * active_ctx.element_size]</code>.</li> </ul> <h5 id="storex-0xc2"><code>STOREX(0xc2)</code></h5> <p><strong>Stack in</strong>: <code>dest source count</code></p> <p><strong>Stack out</strong>: none</p> <p><strong>Description</strong>: copies values from EVM memory into registers of the currently-active field context.</p> <h6 id="execution-2">Execution</h6> <ul> <li>Assert that a field context is set as active in the current call frame.</li> <li>Assert <code>dest + count</code> is less than or equal to the number of the active field context's virtual registers.</li> <li>If modulus of the active context is a power of two: <ul> <li>charge <code>cost_mem_copy(count * active_ctx.element_size)</code> (TBD: deliberately didn't choose <code>mcopy</code> gas model to see if this can consider a cheaper one).</li> </ul> </li> <li>Else if modulus of the active context is odd: <ul> <li>charge <code>count * operation_cost</code> gas, where <code>operation_cost</code> is looked up from the multiplication cost table, given <code>active_ctxt.element_size</code>.</li> </ul> </li> <li>Assert that <code>[source, source + count * active_context.element_size]</code> falls entirely within EVM memory. Interpret it as <code>count</code> number of values, asserting that each is less than the modulus and storing them in the registers <code>[dest, dest + count]</code>.</li> </ul> <h3 id="evm-memory-expansion-cost-modification">EVM Memory Expansion Cost Modification</h3> <p>When expanding EVM memory or allocating a new field context via <code>SETMODX</code>, expansion cost will now consider the size of all allocated virtual registers in the current call frame.</p> <h2 id="rationale">Rationale</h2> <h3 id="separation-of-evm-memory-and-evmmax-virtual-register-space">Separation of EVM Memory and EVMMAX Virtual Register Space</h3> <p>It is assumed that optimized implementations will not store values in EVM-compatible big-endian serialization format, but instead convert them to an internal working representation. The costs in the spec explicitly reflect the choice of Montgomery form as an optimal internal representation.</p> <p>Values represented in Montgomery form can make use of optimized modular reduction for multiplication. See the dedicated section on Montgomery multiplication in the rationale for more details.</p> <h3 id="total-virtual-register-allocation-cap">Total Virtual Register Allocation Cap</h3> <p>24576 bytes is chosen as the per-call-context allocation limit with the goal of ensuring that the virtual register space can be contained in the L1 CPU data cache of most machines (with room to spare), in order that arithmetic operation costs do not have to account for memory access latency.</p> <h3 id="setmodx-cost">SETMODX cost</h3> <p>For odd moduli, <code>SETMODX</code> precomputes two values used for optimized modular multiplication via Montgomery reduction. This is dominated by a modular reduction by the modulus, so the cost model is assumed to be linear.</p> <p>Power-of-two moduli require no precomputation for optimized modular arithmetic.</p> <h3 id="loadx-storex-costs">LOADX/STOREX costs</h3> <p>For power-of-two moduli, <code>LOADX</code>/<code>STOREX</code> are assumed to copy values directly between EVM/EVMMAX memories without measurable conversion cost to convert between EVM big-endian serialization and whatever internal representation is used.</p> <p>For odd moduli, the spec assumes that the internal representation is Montgomery form. Conversion between canonical/Montgomery form requires one modular multiplication per value per direction. The cost of memory copying is baked in to the multiplication price model.</p> <h3 id="arithmetic-costs">Arithmetic Costs</h3> <p>Addition/subtraction/multiplication are assumed to have constant-time implementations. Addition/subtraction can be implemented with linear complexity, while multiplication is quadratic in the size of the modulus.</p> <p>The costs for power-of-two modular multiplication are provisional, and likely be brought down when an optimized arithmetic implementation is rolled out and benchmarked.</p> <h3 id="montgomery-modular-multiplication">Montgomery Modular Multiplication</h3> <p>For a value <code>A</code>, an odd modulus <code>M</code> and a value <code>R</code> (must be coprime and greater than <code>M</code>, chosen as a power of two for efficient performance), the Montgomery representation is <code>A * R % M</code>.</p> <p>Define the Montgomery modular multiplication of two values <code>A</code> and <code>B</code>: <code>mulmont(A, B, M): A * B * R**-1 % M</code> where <code>R**-1 % M</code> is the modular inverse of <code>R</code> with respect to <code>M</code>. There is various literature and algorithms for computing <code>mulmont</code> which have been published since 1985, and the operation is used ubiquitously where execution is bottlenecked by operations over odd moduli.</p> <p>Note that normal modular addition and subtraction algorithms work for Montgomery form values.</p> <h4 id="conversion-of-canonical-to-montgomery-representation">Conversion of Canonical to Montgomery Representation</h4> <p><code>mulmont(canon_val, R**2 % M, M) = mont_val</code></p> <h4 id="conversion-from-montgomery-to-canonical-representation">Conversion from Montgomery to Canonical representation</h4> <p><code>mulmont(mont_val, 1, M) = canon_val</code></p> <h4 id="implementation">Implementation</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># Basic Montgomery Multiplication</span></span> <span class="giallo-l"><span># x, y, mod (int) - x &lt; mod and y &lt; mod</span></span> <span class="giallo-l"><span># mod (int) - an odd modulus</span></span> <span class="giallo-l"><span># R (int) - a power of two, and greater than mod</span></span> <span class="giallo-l"><span># mont_const (int) - pow(-mod, -1, R), precomputed</span></span> <span class="giallo-l"><span># output:</span></span> <span class="giallo-l"><span># (x * y * pow(R, -1, mod)) % mod</span></span> <span class="giallo-l"><span>#</span></span> <span class="giallo-l"><span>def mulmont(x: int, y: int, mod: int, mont_const: int, R: int) -&gt; int:</span></span> <span class="giallo-l"><span> t = x * y</span></span> <span class="giallo-l"><span> m = ((t % R) * mont_const) % R</span></span> <span class="giallo-l"><span> t = t + m * mod</span></span> <span class="giallo-l"><span> t /= R</span></span> <span class="giallo-l"><span> if t &gt;= mod:</span></span> <span class="giallo-l"><span> t -= mod</span></span> <span class="giallo-l"><span> return t</span></span></code></pre> <p>There are various optimized algorithms for computing Montgomery Multiplication of bigint numbers expressed as arrays of system words.</p> <p>These all use a different precomputed constant <code>mont_const = pow(-mod, -1, 2**SYSTEM_WORD_SIZE_BITS)</code>.</p> <h2 id="test-cases">Test Cases</h2> <p>There are tests contained in the Geth implementation. However, no cross-client tests exist yet.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>There is an implementation of this EIP in an open PR to Go Ethereum.</p> <h2 id="security-considerations">Security Considerations</h2> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-02-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Josh Weintraubhttps://github.com/jhweintraub https://wg-eips.ritovision.com/6506/

Interface for building contracts that escrow funds based on an account taking action in a DAO

<h2 id="abstract">Abstract</h2> <p>The following EIP defines the interface for a contract that facilitates the exchange of a governance-incentive for users to vote in a designated direction on a DAO-proposal while escrowing funds until the vote can be verified.</p> <h2 id="motivation">Motivation</h2> <p>While a ton of effort has gone into building bribe systems for DAOs like Curve, Frax, Convex, etc., not a lot of focus has been put on how bribes on other, more general DAO votes, may affect outcomes. Bribes are a lucrative market on many popular DAO’s, and it stands to reason that people are willing to accept them for voting on other proposals, especially if they have no personal stake in the outcome. There are however, problems with current systems:</p> <ol> <li> <p>Current bribe schemes for votes based on pro-rata distribution are economically inefficient and result in worse outcomes for voters. For systems like Votium or Hidden-Hand, If Alice votes on a proposal with the expectation of receiving $10 in bribes, they can just be backrun by a larger voter, diluting their share of the pool. It may no longer be economical to make the decision they did. Using an OTC mechanisms is more efficient because the amount is “locked in” when the bribe is made and the recipient has much more concrete assurances on which to base their decision. These protocols are also centralized, relying on a central authority to accept and redistribute rewards fairly. Whenever possible, centralization should be avoided.</p> </li> <li> <p>The lack of an existing standard means that parties are relying entirely on trust in one-another to obey. Bob has to trust Alice to pay out and Alice has to trust Bob to vote. Even if the two of them were to use an escrow contract, it may have flaws like relying on a trusted third-party, or simply that it is outside the technical reach of both parties.</p> </li> <li> <p>There are no mechanisms for creating transparency into the collusion of actors. Users colluding off-chain to sway the vote of a large token-holder creates opaque outcomes with no accountability since everything happens off-chain.</p> </li> <li> <p>For actors that wish to solicit incentives for their vote, this may require either active management, or the doxxing of their identity/pseudonymous identifier. A user who wishes to negotiate would need to provide a way for incentivizers to contact them, engage in a negotiation process, write and deploy escrow contracts, vote, and then claim their reward. This is a lengthy and involved process that requires active management and communication. This creates a limit on who is able to solicit these incentives, and leads to the centralization of profit towards the few who can sustain this process at length.</p> </li> <li> <p>Bribe Revenue as subsidies. As Vitalik wrote in a 2019 article, <em>On Collusion</em>, a potential solution would be a token that requires voters for a proposal to purchase the governance-token if the proposal-passes, subsidizing the cost of a bad decision for everyone else. If the revenue generated from these incentives is used (at least partly) to directly buy back those tokens by the treasury, then you get a similar outcome. The impact of a bad proposal being passed via-bribing is subsidized for everyone who didn't vote for it by having some value returned to token-holders. This not only makes malicious bribes more costly, as it has to offset the value accrued via buyback, but also means higher profits for recipients.</p> </li> </ol> <h2 id="specification">Specification</h2> <p>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>The key words "BRIBE" and "INCENTIVE" are to be interpreted as the transfer of a digital-asset(s) from user A to user B in exchange for an assurance that user B will vote in a specific-direction, on a specific proposal, for a specified-DAO. If user B does not honor the arrangement, the digital-asset(s) will be returned to user A.</p> <p>The key words "BRIBER", "INCENTIVIZER", and "SENDER" shall refer to the user A offering monetary compensation to user B. "RECIPIENT", "VOTER", and "INCENTIVIZEE" herein refer to user B whom shall formally receive their compensation upon the termination of the agreement.</p> <p>The key word "VOTE" shall be interpreted as the casting of a ballot in any kind of governance system which uses accounts as a form of permissions.</p> <p>Contracts wishing to implement such a standard must implement the following interface</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IEscrowedGovIncentive</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> incentive</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> incentiveToken</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> incentivizer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> recipient</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> proposalId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> direction</span><span>;</span><span class="z-comment"> //</span><span class="z-comment">the keccak256 of the vote direction</span></span> <span class="giallo-l"><span class="z-support"> uint96</span><span> deadline</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint96</span><span> timestamp</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> claimed</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> incentiveSent</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> incentivizer</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> token</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> amount</span><span>, </span><span class="z-support">address</span><span class="z-variable"> recipient</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> incentiveReclaimed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> incentivizer</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> recipient</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> token</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> amount</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> modifiedClaimer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> recipient</span><span>, </span><span class="z-support">address</span><span class="z-variable"> claimer</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> direction</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> incentiveClaimed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> incentivizer</span><span>, </span><span class="z-support">address</span><span class="z-variable"> voter</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> incentiveId</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> proofData</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> disputeInitiated</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> incentiveId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> plaintiff</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> defendant</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> disputeResolved</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> incentive</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> plaintiff</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> defendant</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> dismissed</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">Core mechanism</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> incentivize</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> incentiveId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> incentiveInfo</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> claimIncentive</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> incentiveId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> reveal</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> payable</span><span class="z-variable"> recipient</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> reclaimIncentive</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> incentiveId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> reveal</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyVote</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> incentive</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> voteInfo</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> isVerifiable</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> proofData</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> modifyClaimer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> claimer</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> designation</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">Dispute Mechanism</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> beginDispute</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> incentiveId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> disputeInfo</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> resolveDispute</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> incentiveId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> disputeResolutionInfo</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> isDismissed</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="optional-implementation-details">Optional Implementation Details</h3> <p>Below are three potential implementation examples of the above system for different aspects.</p> <h4 id="complete-transparency"><em>Complete Transparency</em></h4> <p>In this version all information about the vote direction, the amount, and the recipient are public at all times. Information is passed as calldata in plaintext and stored/emitted as such.</p> <h4 id="opacity-until-completion-ouc"><em>Opacity until Completion (OUC)</em></h4> <p>In this model, the recipient, the direction, and the amount are kept secret until the incentive is claimed. In this model, the data is committed to, and an encrypted version is passed as calldata. This data can be encrypted with the recipient's public-key. It should be emitted as such which can then be decrypted off-chain by the recipient and used to make a determination on whether to oblige. In this model to ensure the privacy of transferring funds into escrow, the incentivizer could use methods such as deterministic-address-generation with the create2 opcode.</p> <p>Upon the claiming of the bribe the recipient would simply open the commitment, which would then be checked on-chain and funds released.</p> <h4 id="compatibility-with-off-chain-voting"><em>Compatibility with Off-Chain Voting</em></h4> <p>Many DAO's operate off-chain, typically through voting platforms like snapshot. This system does allow for such compatibility using known signature data. Consider the following example</p> <ol> <li>User A commits an incentive to user B to vote on snapshot. User B votes.</li> <li>Once the deadline has passed, a challenge window is initiated. The incentivizer has a predetermined window to demonstrate that the bribe was not honored. This can be done by simply passing to the contract a signature signed by User B voting in the opposite direction of the bribe. If the signature can be verified, then the arrangement was not honored and funds can be safely released back to user A.</li> <li>If the challenge window concludes without A being able produce proof of noncompliance, then B is able to claim the reward. If B voted inline with the incentive, A will not be able to produce a valid signature of noncompliance. The challenge window with A demonstrating noncompliance is necesarry, because otherwise B could simply sign a message and not broadcast it, allowing them to claim the reward without voting.</li> <li>In the event that B does NOT vote at all, then a special challenge period may be entered. Since B did not vote at all, A would not be able to produce the requisite proof, but B would still be able to claim the reward without complying. In this event, user A would have the option to enter a special dispute period. The details of this are determined by the contract implementation. This can include resolution by a trusted third-party, or other methods. An example includes using a merkle-root to show that B was not in the list of voters at the conclusion of the proposal. It should be considered making A present a</li> </ol> <h3 id="methods">Methods</h3> <p>While this EIP defines a struct <em>incentive</em>, <code>bytes memory</code> should be used whenever possible. Given as each DAO will have its own implementation details, interfaces, and signature data, this should then be decoded using <code>abi.decode()</code> and interpreted according to those known specifications.</p> <h4 id="incentivize"><code>incentivize</code></h4> <p>The function where an incentivizer should commit to the details of their incentive. The commitment value can be calculated off-chain or calculated on-chain in a full transparency system. The function should take the input data from <code>incentiveInfo</code> and create store a new <code>incentive</code> object in the mapping incentives. If OUC is enabled, then only incentivizer and timestamp information need be public, everything else should be left as zero.</p> <p>Function should account for fees taken from user at deposit. If fees are present, then <code>incentivize</code> should take them up front. This is to ensure that the amount quoted to a recipient is <em>at least</em> as much as they would receive.</p> <p>MUST emit the <code>incentiveSent</code> event</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentivize</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> p</span><span class="z-string">ayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveId</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveInfo</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes memory</span></span></code></pre><h4 id="claimincentive"><code>claimIncentive</code></h4> <p>Should be used by the intended recipient of a previously-committed incentive.</p> <p>MUST revert if <code>msg.sender != original_recipient</code> and <code>!allowedClaimer[original_recipient][msg.sender]</code></p> <p>MUST revert if the data provided in <code>reveal</code> does not match the data committed to by <code>incentiveId</code>.</p> <p>MUST revert if all funds committed to cannot be properly sent to <code>recipient</code> at conclusion of the function. If fees are present, then additional funds should be present at deposit to ensure that <em>at least</em> the amount committed to is sent to the user. This however, <strong>DOES NOT</strong> apply to any fees which may be taken by an approved claimer.</p> <p>Ex: Alice commits to Bob an incentive 100 USDC. Bob has approved Eve to claim on his behalf in exchange for 5% of net value. Function should check that amount paid to Bob and Eve is <code>&gt;=100 USDC</code> but <strong>NOT</strong> that Bob himself receives <code>&gt;=100 USDC</code></p> <p>MUST revert if the voting direction of the original recipient cannot be verified as being in line with the intended direction of <code>incentiveId</code>, and no dispute resolution process is defined.</p> <p>MUST revert if the specified incentive has a pending dispute.</p> <p>If verification is successful then funds should be sent to <code>recipient</code>.</p> <p>MUST emit the <code>incentiveClaimed</code> event if function does not revert.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> c</span><span class="z-string">laimIncentive</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveId</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">eveal</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes memory</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">ecipient</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress payable</span></span></code></pre><h4 id="reclaimincentive"><code>reclaimIncentive</code></h4> <p>Function that should be invoked by the initial sender of <code>incentiveId</code> in the event that <code>recipient</code> did not vote in accordance with the incentive's <code>direction</code>. Function should return the funds initially committed to by <code>incentiveId</code> to <code>incentivizer</code></p> <p>MUST revert if all of the funds committed to cannot be returned to the incentivizer.</p> <p>MUST revert if the function cannot successfully verify the validity of <code>msg.sender</code> claim of non-compliance.</p> <p>MUST emit the event <code>incentiveReclaimed</code> if verification is successful. If proof can be retrieved on-chain, then the <code>proof</code> parameter may be left empty.</p> <p>MUST revert if the specified incentive has a pending dispute.</p> <p>If fees are taken, then all funds including any prepaid fees committed to should be returned to the <code>incentivizer</code>.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">eclaimIncentive</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveId</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">eveal</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes memory</span></span></code></pre><h4 id="verifyvote"><code>verifyVote</code></h4> <p><code>function verifyVote(bytes32 incentive, bytes memory voteInfo) public view returns (bool isVerifiable);</code></p> <p>Function used to determine if the voter for <code>incentive</code> should receive the incentive originally committed to.</p> <p>Functions may use whatever scheme they like to determine this information. Necessary data should be encoded and passed through <code>voteInfo</code>.</p> <p>MUST return <code>false</code> if <code>voteInfo</code> indicates that <code>recipient</code> did not vote in the direction committed to by <code>incentive</code>, and true otherwise.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> v</span><span class="z-string">erifyVote</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveId</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> v</span><span class="z-string">oteInfo</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes memory</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span><span> </span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">sVerified</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ool</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">roofData</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes memory</span></span></code></pre><h4 id="modifyclaimer"><code>modifyClaimer</code></h4> <p>Function changing the designation of an address as being approved to claim a bribe on behalf of another user. Only an approved claimer should be able to claim the incentive on behalf of the user which approved them.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">odifyClaimer</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> c</span><span class="z-string">laimer</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">esignation</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ool</span></span> <span class="giallo-l"></span></code></pre><h4 id="begindispute"><code>beginDispute</code></h4> <p>A function used to initiate the resolution of an incentive through an optional dispute-mechanism. At the discretion of the developers, and based on the specifics of the vote-verification mechanism in which a voting direction cannot be conclusively decided, the developers may opt for an additional mechanism to resolve dispute between parties. This may include third-party intervention, additional cryptographic evidence, etc. needed to determine whether to pay out rewards to <code>recipient</code> or return them to the <code>incentivizer</code></p> <p>Potential Examples requiring additional dispute mechanisms:</p> <ol> <li>Requiring a trusted third-party to resolve disputes.</li> <li>The recipient did not vote in an off-chain proposal, and additional off-chain information is needed to confirm.</li> <li>An additional unlocking mechanism is required to access previously deposited funds.</li> </ol> <p>Dispute mechanisms may optionally choose to require a bond from the filer to prevent frivolous filings, to be returned to them on successful resolution of the dispute in their favor.</p> <p>Must emit the event <code>disputeInitiated</code></p> <p>Once a dispute for a given incentive has been filed, neither the <code>incentivizer</code> nor <code>recipient</code> should be able to withdraw funds until completed.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> b</span><span class="z-string">eginDispute</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> p</span><span class="z-string">ayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveId</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">isputeInfo</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes memory</span></span></code></pre><h4 id="resolvedispute"><code>resolveDispute</code></h4> <p>A function which is used to resolve pending disputes over <code>incentiveId</code>. The exact mechanism shall be specified by the developers.</p> <p>MUST return false, and be <em>"dismissed"</em>, if the mechanisms resolves the dispute in favor of the defendant <code>(recipient)</code>, by showing they did honor the incentive of <code>incentiveId</code>. If the dispute is <em>"confirmed"</em>, then the function should return true.</p> <p>MUST transfer funds committed to by <code>incentivizer</code> to <code>recipient</code> if dispute is <code>dismissed</code> and return <code>funds + fee + bond</code> to the <code>plaintiff</code>. If dismissed, the distribution of the bond shall be at the discretion of the developers. This may including burning, awarding to the defendant, or donating to a community treasury.</p> <p>MUST emit the event <code>disputeResolved</code> on successful resolution.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">esolveDispute</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onPayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveId</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">isputeResolutionInfo</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes memory</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span><span> </span></span> <span class="giallo-l"><span> -</span><span class="z-string"> n</span><span class="z-string">ame isDismissed</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ool</span></span></code></pre><h3 id="events">Events</h3> <h4 id="incentivesent"><code>incentiveSent</code></h4> <p><code>incentivizer</code> has bribed <code>recipient</code> <code>amount</code> of <code>token</code> for some information.</p> <p>If system is private then recipient, amount, and <code>token</code> may be left as zero.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveSent</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> e</span><span class="z-string">vent</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span><span> </span></span> <span class="giallo-l"><span> -</span><span class="z-string"> n</span><span class="z-string">ame incentivizer</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> t</span><span class="z-string">oken</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">mount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">ecipient</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span></code></pre><h4 id="incentiveclaimed"><code>incentiveClaimed</code></h4> <p><code>recipient</code> claimed an incentive <code>amount</code> of <code>token</code> and any other data relevant.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveClaimed</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> e</span><span class="z-string">vent</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">ecipient</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> t</span><span class="z-string">oken</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">mount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">ata</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes</span></span></code></pre><h4 id="modifiedclaimer"><code>modifiedClaimer</code></h4> <p>A new <code>claimer</code> was either whitelisted by <code>recipient</code> or blacklisted.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">odifiedClaimer</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> e</span><span class="z-string">vent</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">ecipient</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> c</span><span class="z-string">laimer</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">irection</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ool</span></span></code></pre><h4 id="incentivereclaimed"><code>incentiveReclaimed</code></h4> <p>An <code>incentivizer</code> is reclaiming <code>incentiveId</code>, and outing the noncompliance of <code>voter</code></p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveReclaimed</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> e</span><span class="z-string">vent</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span><span> </span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentivizer</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> v</span><span class="z-string">oter</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveId</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">roofData</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes</span></span></code></pre><h4 id="disputeinitiated"><code>disputeInitiated</code></h4> <p><code>incentivizer</code> has initiated a dispute with <code>plaintiff</code> over <code>incentiveId</code></p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">isputeInitiated</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> e</span><span class="z-string">vent</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span><span> </span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveId</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">laintiff</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">efendant</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span></code></pre><h4 id="disputeresolved"><code>disputeResolved</code></h4> <p>The dispute over <code>incentiveId</code> has been resolved, either <code>dismissed</code> in favor of <code>defendant</code> or resolved in favor of the <code>plaintiff</code></p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">isputeResolved</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> e</span><span class="z-string">vent</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> i</span><span class="z-string">ncentiveId</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">laintiff</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">efendant</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">ismissed</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ool</span></span> <span class="giallo-l"><span> </span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This design was motivated by a few factors:</p> <ol> <li> <p>The issue of offering incentives for votes is an inevitability. There is no mechanism that can prevent users from colluding off-chain to vote a certain direction, and with enough obfuscation, can be completely hidden from the community's view. The solution is therefore to realign the incentives of these actors in a way that both creates transparency, while allowing for the decentralization of bribe-revenue. Flashbots is a relevant example. Since MEV could not be prevented, the solution was to make it more fairly distributed by incentivizing miners to use Flashbots-Geth with profits. Using an OTC market structure would have the same effect, allowing anyone to reap the benefits of a potential incentive while also creating a more efficient marketplace.</p> </li> <li> <p>Injecting transparency about whom is bribing whom for what increases both fairness and profitability. This makes it possible for the community to organize around potential solutions. Ex: Alice pays Bob $10 for his 1k votes in the DAO. This is now known on-chain and next time someone who cares about the outcome can offer Bob $11 for the votes. This maximizes profit to the recipient.</p> </li> </ol> <p><strong>Implementations should operate similar to the following example:</strong></p> <ol> <li> <p>Alice wants to give bob $10 to vote YES on DAO proposal #420. She wants an assurance he will do it and gets the money back if he doesn’t</p> </li> <li> <p>It should work as an escrow service for both on-chain and snapshot based voting, releasing funds only after the vote has concluded, and it can be verified the recipient voted in line with the vote. It should be done without requiring a trusted third-party to escrow and release the funds themselves.</p> </li> <li> <p>This EIP makes no discernment about the nature in which this information is relayed to the recipient. Implementation details are at the discretion of the protocol. This includes the optional decisions to enable privacy for both the recipient and the amount. Information on how this can be implemented is below. Once the vote has occurred, then the contents of the bribe can be claimed, pending verification. This verification should satisfy both soundness and completeness, that only after the user can show they did vote in line with the incentive do they receive the funds, and that such proof cannot be forged or misleading in any way.</p> </li> </ol> <p><strong>Factors to consider</strong></p> <ol> <li> <p>To remedy the problem of diluted rewards, the system uses a simple hash-based commitment scheme. When an incentive is sent, its data is committed to, and revealed when withdrawn.</p> </li> <li> <p>Once a bribe is committed to, it cannot be withdrawn until after the voting period for the proposal has concluded. This is to ensure the legitimacy of the escrow, so that user A cannot withdraw the bribe after B has voted, but before they can claim the reward.</p> </li> </ol> <h3 id="potential-ethical-issues">Potential Ethical Issues</h3> <p>Potential ethical issues have been raised about the prospect of potentially encouraging users to accept monetary payment for their vote. This is the wrong frame of reference. The question is not whether it is ethical to encourage users to send/solicit, but rather the consequences of doing nothing. Returning to the flashbots example, the question is not whether MEV is ethical, but repercussions of allowing it to flourish without pushback.</p> <p>If nothing is done, the following outcomes are possible:</p> <ol> <li> <p>Flywheel Effect - Only dedicated and financially endowed holders will solicit incentives with impunity. This centralization of profit allows them to purchase more voting-rights, increasing power and so on until they have accumulated a critical mass, exerting potentially harmful influence over operations. This can range anywhere from minor operational decisions, to votes over treasury resolution.</p> </li> <li> <p>Lack of transparency - Decisionmaking will occur behind closed doors as the true intentions of voters is unclear, and votes that should pass may fail, or vice-versa. The will of the community will not be honored.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues found.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This standard is intended to work with existing governance systems. Any potential issue with existing governance may represent a potential attack on this as well. This includes voting-weight manipulation, vote forgery, verification discrepancies etc. All systems in which this EIP is integrated with should be properly audited for maximum security, as any issues may result in improper distribution of these governance incentives.</p> <p>Potential implementations of this system may rely on complex cryptographic operations as well. This may include proper implementation of digital-signatures to prevent replay attacks, or correctness requirements of SNARK proofs. These features may be <strong>non-trivial</strong> and thus require special care to ensure they are implemented and configured securely, otherwise features like confidentiality may be violated.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-02-09T00:00:00+00:00 2026-02-11T14:49:27+00:00 Etan Kisslinghttps://github.com/etan-status Zahary Karadjovhttps://github.com/zah https://wg-eips.ritovision.com/6475/

New SSZ type to represent optional values

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/67c2f9ee9eb562f7cc02b2ff90d92c56137944e1/ssz/simple-serialize.md">Simple Serialize (SSZ) type</a> to represent <code>Optional[T]</code> values.</p> <h2 id="motivation">Motivation</h2> <p>Optional values are currently only representable in SSZ using workarounds. Adding proper support provides these benefits:</p> <ol> <li> <p><strong>Better readability:</strong> SSZ structures with optional values can be represented with idiomatic types of the underlying programming language, e.g., <code>Optional[T]</code> in Python, making them easier to interact with.</p> </li> <li> <p><strong>Compact serialization:</strong> SSZ serialization can rely on the binary nature of optional values; they either exist or they don't. This allows more compact serialization than using alternative approaches based on workarounds.</p> </li> </ol> <h2 id="specification">Specification</h2> <p>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> <h3 id="type-definition">Type definition</h3> <p><code>Optional[T]</code> is defined as a type that can represent:</p> <ul> <li>A value of SSZ type <code>T</code></li> <li>Absence of a value, indicated by <code>None</code></li> </ul> <h3 id="default-value">Default value</h3> <p>The default value of <code>Optional[T]</code> is <code>None</code>.</p> <h3 id="serialization">Serialization</h3> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">if</span><span> value</span><span class="z-keyword"> is</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-keyword">else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant">\x01</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span> serialize</span><span>(</span><span>value</span><span>)</span></span></code></pre><h3 id="deserialization">Deserialization</h3> <p>The deserialization of an <code>Optional[T]</code> depends on the input length:</p> <ul> <li>If the input length is 0, the value is <code>None</code>.</li> <li>Otherwise, the first byte of the deserialization scope must be checked to be <code>0x01</code>, the remainder of the scope is deserialized same as <code>T</code>.</li> </ul> <h3 id="merkleization">Merkleization</h3> <p>An <code>Optional[T]</code> is merkleized as a <code>List[T, 1]</code>.</p> <ul> <li>If the value is <code>None</code>, the list length is <code>0</code>.</li> <li>Otherwise, the list length is <code>1</code>, and the first list element contains the underlying value.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="why-not-union-none-t">Why not <code>Union[None, T]</code>?</h3> <p><code>Union[None, T]</code> leaves ambiguity about the intention whether the type may be extended in the future, i.e., <code>Union[None, T, U]</code>.</p> <p>Furthermore, SSZ Union types are currently not used in any final Ethereum specification and do not have a finalized design themselves. If the only use case is a workaround for lack of <code>Optional[T]</code>, the simpler <code>Optional[T]</code> type is sufficient, and support for general unions could be delayed until really needed. Note that the design of <code>Optional[T]</code> could be used as basis for a more general <code>Union</code>.</p> <h3 id="why-not-list-t-1">Why not <code>List[T, 1]</code>?</h3> <p>The serialization is less compact for variable-length <code>T</code>, due to the extra offset table at the beginning of the list to indicate the list length.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>Union[None, T]</code> and <code>List[T, 1]</code> workarounds are not used at this time to represent <code>Optional[T]</code>.</p> <h2 id="test-cases">Test Cases</h2> <p>See <a href="https://wg-eips.ritovision.com/6475/./assets/tests.py">EIP assets</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <ul> <li><strong>Python:</strong> See <a href="https://wg-eips.ritovision.com/6475/./assets/optional.py">EIP assets</a>, based on <code>protolambda/remerkleable</code></li> <li><strong>Nim:</strong> <code>status-im/nim-ssz-serialization</code></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>None</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-02-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Cristian Espinozahttps://github.com/crisgarner Simon Fremauxhttps://github.com/dievardump David Huberhttps://github.com/cxkoda and Arran Schlosberghttps://github.com/aschlosberg https://wg-eips.ritovision.com/6464/

Extends ERC-721 to allow token owners to approve multiple operators to control their assets on a per-token basis.

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/721/">ERC-721</a> did not foresee the approval of multiple operators to manage a specific token on behalf of its owner. This lead to the establishment of <code>setApprovalForAll()</code> as the predominant way to authorise operators, which affords the approved address control over all assets and creates an unnecessarily broad security risk that has already been exploited in a multitude of phishing attacks. The presented EIP extends ERC-721 by introducing a fine-grained, on-chain approval mechanism that allows owners to authorise multiple, specific operators on a per-token basis; this removes unnecessary access permissions and shrinks the surface for exploits to a minimum. The provided reference implementation further enables cheap revocation of all approvals on a per-owner or per-token basis.</p> <h2 id="motivation">Motivation</h2> <p>The NFT standard defined in ERC-721 allows token owners to "approve" arbitrary addresses to control their tokens—the approved addresses are known as "operators". Two types of approval were defined:</p> <ol> <li><code>approve(address,uint256)</code> provides a mechanism for only a single operator to be approved for a given <code>tokenId</code>; and</li> <li><code>setApprovalForAll(address,bool)</code> toggles whether an operator is approved for <em>every</em> token owned by <code>msg.sender</code>.</li> </ol> <p>With the introduction of multiple NFT marketplaces, the ability to approve multiple operators for a particular token is necessary if sellers wish to allow each marketplace to transfer a token upon sale. There is, however, no mechanism for achieving this without using <code>setApprovalForAll()</code>. This is in conflict with the principle of least privilege and creates an attack vector that is exploited by phishing for malicious (i.e. zero-cost) sell-side signatures that are executed by legitimate marketplace contracts.</p> <p>This EIP therefore defines a fine-grained approach for approving multiple operators but scoped to specific token(s).</p> <h3 id="goals">Goals</h3> <ol> <li>Ease of adoption for marketplaces; requires minimal changes to existing workflows.</li> <li>Ease of adoption for off-chain approval-indexing services.</li> <li>Simple revocation of approvals; i.e. not requiring one per grant.</li> </ol> <h3 id="non-goals">Non-goals</h3> <ol> <li>Security measures for protecting NFTs other than through limiting the scope of operator approvals.</li> <li>Compatibility with <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> semi-fungible tokens. However we note that the mechanisms described herein are also applicable to ERC-1155 token <em>types</em> without requiring approval for all other types.</li> </ol> <h2 id="specification">Specification</h2> <p>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>To comply with this EIP, a contract MUST implement <code>IERC6464</code> (defined herein) and the <code>ERC165</code> and <code>ERC721</code> interfaces; see <a href="https://wg-eips.ritovision.com/165/">ERC-165</a> and ERC-721 respectively.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Extends ERC-721 to include per-token approval for multiple operators.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Off-chain indexers of approvals SHOULD assume that an operator is approved if either of `ERC721.Approval(…)` or</span></span> <span class="giallo-l"><span class="z-comment"> * `ERC721.ApprovalForAll(…, true)` events are witnessed without the corresponding revocation(s), even if an</span></span> <span class="giallo-l"><span class="z-comment"> * `ExplicitApprovalFor(…, false)` is emitted.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-keyword"> TODO</span><span class="z-comment">: the ERC-165 identifier for this interface is TBD.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6464</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Emitted when approval is explicitly granted or revoked for a token.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ExplicitApprovalFor</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> approved</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Emitted when all explicit approvals, as granted by either `setExplicitApprovalFor()` function, are</span></span> <span class="giallo-l"><span class="z-comment"> * revoked for all tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST be emitted upon calls to `revokeAllExplicitApprovals()`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AllExplicitApprovalsRevoked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Emitted when all explicit approvals, as granted by either `setExplicitApprovalFor()` function, are</span></span> <span class="giallo-l"><span class="z-comment"> * revoked for the specific token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> MUST be `ownerOf(tokenId)` as per ERC721; in the case of revocation due to transfer, this MUST be</span></span> <span class="giallo-l"><span class="z-comment"> * the `from` address expected to be emitted in the respective `ERC721.Transfer()` event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AllExplicitApprovalsRevoked</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Approves the operator to manage the asset on behalf of its owner.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Throws if `msg.sender` is not the current NFT owner, or an authorised operator of the current owner.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Approvals set via this method MUST be revoked upon transfer of the token to a new owner; equivalent to</span></span> <span class="giallo-l"><span class="z-comment"> * calling `revokeAllExplicitApprovals(tokenId)`, including associated events.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST emit `ApprovalFor(operator, tokenId, approved)`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST NOT have an effect on any standard ERC721 approval setters / getters.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setExplicitApproval</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> operator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> approved</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Approves the operator to manage the token(s) on behalf of their owner.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST be equivalent to calling `setExplicitApprovalFor(operator, tokenId, approved)` for each `tokenId` in</span></span> <span class="giallo-l"><span class="z-comment"> * the array.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setExplicitApproval</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> operator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenIds</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> approved</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Revokes all explicit approvals granted by `msg.sender`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST emit `AllExplicitApprovalsRevoked(msg.sender)`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeAllExplicitApprovals</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Revokes all excplicit approvals granted for the specified token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Throws if `msg.sender` is not the current NFT owner, or an authorised operator of the current owner.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST emit `AllExplicitApprovalsRevoked(msg.sender, tokenId)`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeAllExplicitApprovals</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Query whether an address is an approved operator for a token.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isExplicitlyApprovedFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6464AnyApproval</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns true if any of the following criteria are met:</span></span> <span class="giallo-l"><span class="z-comment"> * 1. `isExplicitlyApprovedFor(operator, tokenId) == true`; OR</span></span> <span class="giallo-l"><span class="z-comment"> * 2. `isApprovedForAll(ownerOf(tokenId), operator) == true`; OR</span></span> <span class="giallo-l"><span class="z-comment"> * 3. `getApproved(tokenId) == operator`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The criteria MUST be extended if other mechanism(s) for approving operators are introduced. The criteria</span></span> <span class="giallo-l"><span class="z-comment"> * MUST include all approval approaches.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isApprovedFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="draft-notes-to-be-expanded-upon">Draft notes to be expanded upon</h3> <ol> <li>Approvals granted via the newly introduced methods are called <em>explicit</em> as a means of easily distinguishing them from those granted via the standard <code>ERC721.approve()</code> and <code>ERC721.setApprovalForAll()</code> functions. However they follow the same intent: authorising operators to act on the owner's behalf.</li> <li>Abstracting <code>isApprovedFor()</code> into <code>IERC6464AnyApproval</code> interface, as against keeping it in <code>IERC6464</code> allows for modularity of plain <code>IERC6464</code> implementations while also standardising the interface for checking approvals when interfacing with specific implementations and any future approval EIPs.</li> <li>Inclusion of an indexed owner address in <code>AllExplicitApprovalsRevoked(address,uint256)</code> assists off-chain indexing of existing approvals.</li> <li>Re <code>IERC6464AnyApproval</code>: With an increasing number of approval mechanisms it becomes cumbersome for marketplaces to integrate with them since they have to query multiple interfaces to check if they are approved to manage tokens. This provides a streamlined interface, intended to simplify data ingestion for them.</li> </ol> <!-- The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work, e.g. how the feature is supported in other languages. The current placeholder is acceptable for a draft. TODO: Remove this comment before submitting --> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This extension was written to allow for the smallest change possible to the original ERC-721 spec while still providing a mechanism to grant, revoke and track approvals of multiple operators on a per-token basis.</p> <p>Extended contracts remain fully compatible with all existing platforms.</p> <p><strong>Note</strong> the <code>Security Considerations</code> sub-section on <code>Other risks</code> regarding interplay of approval types.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>TODO: add internal link to assets directory when the implementation is in place.</p> <p>An efficient mechanism for broad revocation of approvals via incrementing nonces is included.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="threat-model">Threat model</h3> <h3 id="mitigations">Mitigations</h3> <h3 id="other-risks">Other risks</h3> <p>TODO: Interplay with <code>setApprovalForAll()</code>.</p> <!-- All EIPs must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. For example, include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed. EIP submissions missing the "Security Considerations" section will be rejected. An EIP cannot proceed to status "Final" without a Security Considerations discussion deemed sufficient by the reviewers. The current placeholder is acceptable for a draft. TODO: Remove this comment before submitting --> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2023-01-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Tal Be'erytal@zengo.com RoiVhttps://github.com/DeVaz1 https://wg-eips.ritovision.com/6384/

A method for retrieving a human-readable description of EIP-712 typed and structured data.

<h2 id="abstract">Abstract</h2> <p>This EIP introduces the <code>evalEIP712Buffer</code> function, which takes an <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> buffer and returns a human-readable text description.</p> <h2 id="motivation">Motivation</h2> <p>The use case of Web3 off-chain signatures intended to be used within on-chain transaction is gaining traction and being used in multiple leading protocols (e.g. OpenSea) and standards <a href="https://wg-eips.ritovision.com/2612/">EIP-2612</a>, mainly as it offers a fee-less experience. Attackers are known to actively and successfully abuse such off-chain signatures, leveraging the fact that users are blindly signing off-chain messages, since they are not humanly readable. While <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> originally declared in its title that being ”humanly readable” is one of its goals, it did not live up to its promise eventually and EIP-712 messages are not understandable by an average user.</p> <p>In one example, victims browse a malicious phishing website. It requests the victim to sign a message that will put their NFT token for sale on OpenSea platform, virtually for free.</p> <p>The user interface for some popular wallet implementations is not conveying the actual meaning of signing such transactions.</p> <p>In this proposal we offer a secure and scalable method to bring true human readability to EIP-712 messages by leveraging their bound smart contracts. As a result, once implemented this EIP wallets can upgrade their user experience from current state:</p> <p><img src="https://wg-eips.ritovision.com/6384/./assets/media/MiceyMask-non-compliant.png" alt="" /></p> <p>to a much clearer user experience:</p> <p><img src="https://wg-eips.ritovision.com/6384/./assets/media/ZenGo-EIP-compliant-warning.png" alt="" /></p> <p>The proposed solution solves the readability issues by allowing the wallet to query the <code>verifyingContract</code>. The incentives for keeping the EIP-712 message description as accurate as possible are aligned, as the responsibility for the description is now owned by the contract, that:</p> <ul> <li>Knows the message meaning exactly (and probably can reuse the code that handles this message when received on chain)</li> <li>Natively incentivized to provide the best explanation to prevent a possible fraud</li> <li>Not involving a third party that needs to be trusted</li> <li>Maintains the fee-less customer experience as the added function is in “view” mode and does not require an on-chain execution and fees.</li> <li>Maintains Web3’s composability property</li> </ul> <h2 id="specification">Specification</h2> <p>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> <p>EIP-712 already formally binds an off-chain signature to a contract, with the <code>verifyingContract</code> parameter. We suggest adding a “view” function (<code>"stateMutability":"view"</code>) to such contracts, that returns a human readable description of the meaning of this specific off-chain buffer.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the expected result of the offchain message.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> evalEIP712Buffer</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> domainHash</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> primaryType</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> typedDataBuffer</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> .</span><span>.</span><span>.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Every compliant contract MUST implement this function.</strong></p> <p>Using this function, wallets can submit the proposed off-chain signature to the contract and present the results to the user, allowing them to enjoy an “on-chain simulation equivalent” experience to their off-chain message.</p> <p>This function will have a well known name and signature, such that there is no need for updates in the EIP-712 structure.</p> <h3 id="function-s-inputs">Function's inputs</h3> <p>The inputs of the function:</p> <ul> <li><code>domainHash</code> is the EIP-712's domainSeparator, a hashed <code>eip712Domain</code> struct.</li> <li><code>primaryType</code>is the EIP-712's <code>primaryType</code>.</li> <li><code>typedDataBuffer</code> is an ABI encoded message part of the EIP-712 full message.</li> </ul> <h3 id="function-s-output-s">Function's output(s)</h3> <p>The output of the function is an array of strings. The wallet SHOULD display them to its end-users. The wallet MAY choose to augment the returned strings with additional data. (e.g. resolve contract addresses to their name)</p> <p>The strings SHOULD NOT be formatted (e.g. should not contain HTML code) and wallets SHOULD treat this string as an untrusted input and handle its rendering as such.</p> <h3 id="support-for-eip-712-messages-that-are-not-meant-to-be-used-on-chain">Support for EIP-712 messages that are not meant to be used on-chain</h3> <p>If <code>verifyingContract</code> is not included in the EIP-712 domain separator, wallets MUST NOT retrieve a human-readable description using this EIP. In this case, wallets SHOULD fallback to their original EIP-712 display.</p> <h2 id="rationale">Rationale</h2> <ul> <li>We chose to implement the <code>typeDataBuffer</code> parameter as abi encoded as it is a generic way to pass the data to the contract. The alternative was to pass the <code>typedData</code> struct, which is not generic as it requires the contract to specify the message data.</li> <li>We chose to return an array of strings and not a single string as there are potential cases where the message is composed of multiple parts. For example, in the case of a multiple assets transfers in the same <code>typedDataBuffer</code>, the contract is advised to describe each transfer in a separate string to allow the wallet to display each transfer separately.</li> </ul> <h3 id="alternative-solutions">Alternative solutions</h3> <h4 id="third-party-services">Third party services:</h4> <p>Currently, the best choice for users is to rely on some 3rd party solutions that get the proposed message as input and explain its intended meaning to the user. This approach is:</p> <ul> <li>Not scalable: 3rd party provider needs to learn all such proprietary messages</li> <li>Not necessarily correct: the explanation is based on 3rd party interpretation of the original message author</li> <li>Introduces an unnecessary dependency of a third party which may have some operational, security, and privacy implications.</li> </ul> <h4 id="domain-name-binding">Domain name binding</h4> <p>Alternatively, wallets can bind domain name to a signature. i.e. only accept EIP-712 message if it comes from a web2 domain that its <code>name</code> as defined by EIP-712 is included in <code>eip712Domain</code>. However this approach has the following disadvantages:</p> <ul> <li>It breaks Web3’s composability, as now other dapps cannot interact with such messages</li> <li>Does not protect against bad messages coming from the specified web2 domain, e.g. when web2 domain is hacked</li> <li>Some current connector, such as WalletConnect do not allow wallets to verify the web2 domain authenticity</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>For non-supporting contracts the wallets will default to showing whatever they are showing today. Non-supporting wallets will not call this function and will default to showing whatever they are showing today.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation can be found <a href="https://wg-eips.ritovision.com/6384/./assets/implementation/src/MyToken/MyToken.sol">here</a>. This toy example shows how an <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> contract supporting this EIP implements an EIP-712 support for "transferWithSig" functionality (a non-standard variation on Permit, as the point of this EIP is to allow readability to non-standard EIP-712 buffers). To illustrate the usability of this EIP to some real world use case, a helper function for the actual OpenSea's SeaPort EIP-712 is implemented too in <a href="https://wg-eips.ritovision.com/6384/./assets/implementation/src/SeaPort/SeaPort712ParserHelper.sol">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="the-threat-model">The threat model:</h3> <p>The attack is facilitated by a rogue web2 interface (“dapp”) that provides bad parameters for an EIP-712 formatted message that is intended to be consumed by a legitimate contract. Therefore, the message is controlled by attackers and cannot be trusted, however the contract is controlled by a legitimate party and can be trusted.</p> <p>The attacker intends to use that signed EIP-712 message on-chain later on, with a transaction crafted by the attackers. If the subsequent on-chain transaction was to be sent by the victim, then a regular transaction simulation would have sufficed.</p> <p>The case of a rogue contract is irrelevant, as such a rogue contract can already facilitate the attack regardless of the existence of the EIP-712 formatted message.</p> <p>Having said that, a rogue contract may try to abuse this functionality in order to send some maliciously crafted string in order to exploit vulnerabilities in wallet rendering of the string. Therefore wallets should treat this string as an untrusted input and handle its renderring it as such.</p> <h3 id="analysis-of-the-proposed-solution">Analysis of the proposed solution</h3> <p>The explanation is controlled by the relevant contract which is controlled by a legitimate party. The attacker must specify the relevant contract address, as otherwise it will not be accepted by it. Therefore, the attacker cannot create false explanations using this method. Please note that if the explanation was part of the message to sign it would have been under the control of the attacker and hence irrelevant for security purposes.</p> <p>Since the added functionality to the contract has the “view” modifier, it cannot change the on-chain state and harm the existing functionalities of the contract.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-12-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Andrei Maiborodahttps://github.com/gumb0 Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast Matt Garnetthttps://github.com/lightclient https://wg-eips.ritovision.com/6206/

Introduces instruction for chaining function calls.

<h2 id="abstract">Abstract</h2> <p>This EIP allows for tail call optimizations in EOF functions (<a href="https://wg-eips.ritovision.com/4750/">EIP-4750</a>) by introducing a new instruction <code>JUMPF</code>, which jumps to a code section without adding a new return stack frame.</p> <p>Additionally the format of the type sections is extended to allow declaring sections as non-returning, with simplified stack validation for <code>JUMPF</code> to such section.</p> <h2 id="motivation">Motivation</h2> <p>It is common for functions to make a call at the end of the routine only to then return. <code>JUMPF</code> optimizes this behavior by changing code sections without needing to update the return stack.</p> <p>Knowing at validation time that a function will never return control allows for <code>JUMPF</code> to such function to be treated similar to terminating instructions, where extra items may be left on the operand stack at execution termination. This provides opportunities for compilers to generate more optimal code, both in code size and in spent gas. It is particularly beneficial for small error handling helpers, that end execution with <code>REVERT</code>: they are commonly reused in multiple branches and extracting them into a helper function is efficient, when there is no need to pop extra stack items before <code>JUMPF</code> to such helper.</p> <h2 id="specification">Specification</h2> <h3 id="type-section-changes">Type section changes</h3> <p>We define a non-returning section as one that cannot return control to its caller section.</p> <p>Type section <code>outputs</code> field contains a special value <code>0x80</code> when corresponding code section is non-returning. See <a href="https://wg-eips.ritovision.com/6206/#non-returning-status-validation">Non-returning status validation</a> below for validation details.</p> <p>The first code section MUST have 0 inputs and be non-returning.</p> <h3 id="execution-semantics">Execution Semantics</h3> <p>A new instruction, <code>JUMPF (0xe5)</code>, is introduced.</p> <ol> <li><code>JUMPF</code> has one immediate argument, <code>target_section_index</code>, encoded as a 16-bit unsigned big-endian value.</li> <li>If the operand stack size exceeds <code>1024 - type[target_section_index].max_stack_increase</code> (i.e. if the called function may exceed the global stack height limit), execution results in an exceptional halt. This guarantees that the target function does not exceed global stack height limit.</li> <li><code>JUMPF</code> sets <code>current_section_index</code> to <code>target_section_index</code> and <code>PC</code> to <code>0</code>, but does not change the return stack. Execution continues in the target section.</li> <li><code>JUMPF</code> costs 5 gas.</li> <li><code>JUMPF</code> neither pops nor pushes anything to the operand stack.</li> </ol> <p>If the code is legacy bytecode, <code>JUMPF</code> instruction results in an <em>exceptional halt</em>. (<em>Note: This means no change to behaviour.</em>)</p> <h3 id="code-validation">Code Validation</h3> <p>Let the definition of <code>type[i]</code> be inherited from <a href="https://wg-eips.ritovision.com/4750/">EIP-4750</a> and define <code>stack_height_min</code> and <code>stack_height_max</code> to be the stack height bounds at a certain instruction during the instruction flow traversal.</p> <ul> <li>The immediate argument of <code>JUMPF</code> MUST be less than the total number of code sections.</li> <li>For each <code>JUMPF</code> instruction: <ul> <li>either <code>type[current_section_index].outputs</code> MUST be greater or equal <code>type[target_section_index].outputs</code>,</li> <li>or <code>type[target_section_index].outputs</code> MUST be <code>0x80</code></li> </ul> </li> <li>The stack height validation at <code>JUMPF</code> depends on whether the target section is non-returning: <ul> <li><code>JUMPF</code> into returning section (<code>type[target_section_index].outputs</code> does not equal <code>0x80</code>): <code>stack_height_min</code> and <code>stack_height_max</code> MUST be equal to <code>type[current_section_index].outputs - type[target_section_index].outputs + type[target_section_index].inputs</code>. This means that target section can output less stack elements than the original code section called by the top element on the return stack, if the current code section leaves the delta <code>type[current_section_index].outputs - type[target_section_index].outputs</code> element(s) on the stack.</li> <li><code>JUMPF</code> into non-returning section (<code>type[target_section_index].outputs</code> equals <code>0x80</code>): <code>stack_height_min</code> MUST be greater than or equal to <code>type[target_section_index].inputs</code>.</li> </ul> </li> <li>Stack overflow check at <code>JUMPF</code>: <code>stack_height_max</code> MUST be less than or equal to <code>1024 - types[target_section_index].max_stack_increase</code>.</li> <li><code>JUMPF</code> is considered terminating instruction, i.e. does not have successor instructions in code validation and MAY be final instruction in the section.</li> <li>The code validation defined in <a href="https://wg-eips.ritovision.com/4200/">EIP-4200</a> also fails if any <code>RJUMP*</code> offset points to one of the two bytes directly following a <code>JUMPF</code> instruction.</li> </ul> <p><code>CALLF</code> instruction validation is extended to include the rule:</p> <ul> <li>Code section is invalid in case an immediate argument <code>target_section_index</code> of any <code>CALLF</code> targets a non-returning section, i.e. <code>type[target_section_index].outputs</code> equals <code>0x80</code>.</li> </ul> <h4 id="non-returning-status-validation">Non-returning status validation</h4> <p>Section type MUST be non-returning if and only if the section contains no <code>RETF</code> instructions and no <code>JUMPF</code> instructions targeting returning sections (target section's status is checked via its output value in type section.) <em>Note: This implies that section containing only <code>JUMPF</code>s into non-returning sections is non-returning itself.</em></p> <h2 id="rationale">Rationale</h2> <h3 id="allowing-jumpf-to-section-with-less-outputs">Allowing <code>JUMPF</code> to section with less outputs</h3> <p>An alternative rule for <code>JUMPF</code> stack validation could require the target section's outputs to be exactly equal to the current section's outputs. Under such rule, a particular target section (a shared "helper" piece of code) would only "match" sections (requiring some shared "helper" code to execute before returning) <em>with the same number of outputs</em>.</p> <p>Instead, we allow a given <code>JUMPF</code> target section to be called from sections with more outputs, as long as these sections provide these extra stack elements (the "delta") themselves. This will reduce duplicated code as it will allow compilers more flexibility during code generation such that certain helpers can be used generically by functions, regardless of their output values.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is backward compatible as EOF does not allow undefined instructions to be used or deployed, meaning no contracts will be affected.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This new instruction needs to be carefully considered during implementation of the EOF container validation algorithm.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-12-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/6188/

Caps the nonce at 2^64-2

<h2 id="abstract">Abstract</h2> <p>This EIP caps the nonce at <code>2^64-2</code>, reserving it for contracts with unusual behavior, as defined in other EIPs.</p> <h2 id="motivation">Motivation</h2> <p>This EIP is not terribly useful on its own, as it adds additional computation without any useful side effects. However, it can be used by other EIPs.</p> <h2 id="specification">Specification</h2> <p>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 and RFC 8174.</p> <h3 id="eoa-transactions">EOA Transactions</h3> <p>The nonce of a transaction originating from an EOA MUST be less than <code>2^64-2</code>. If the nonce is either <code>2^64-1</code> or <code>2^64-2</code>, the transaction MUST be invalid.</p> <h3 id="create-and-create2"><code>CREATE</code> and <code>CREATE2</code></h3> <p>If a nonce would be incremented to <code>2^64-1</code> by <code>CREATE</code> or <code>CREATE2</code>, it is instead set to <code>2^64-2</code>. <code>2^64-1</code> is reserved for alias or other special contracts.</p> <h2 id="rationale">Rationale</h2> <p>Capping a nonce allows for contracts with special properties to be created, with their functionality based on their contract code. As such, only one nonce needs to be reserved.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a protocol upgrade, since it modifies consensus rules. The further restriction of nonce should not have an effect on accounts, as reaching a nonce of <code>2^64-2</code> is difficult.</p> <h2 id="security-considerations">Security Considerations</h2> <p>As it is not feasible for contract accounts to get to the nonce limit, any potential problems with opcodes that depend on the value of an account's nonce can be safely ignored.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-12-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/6189/

Allows the creation of contracts that forward calls to other contracts

<h2 id="abstract">Abstract</h2> <p>This EIP allows contracts to be turned into "alias contracts" using a magic nonce. Alias contracts automatically forward calls to other contracts.</p> <h2 id="motivation">Motivation</h2> <p>This EIP is not terribly useful on its own, as it adds additional computation and gas costs without any useful side effects. However, in conjunction with <a href="https://wg-eips.ritovision.com/6190/">EIP-6190</a>, it can be used to make SELFDESTRUCT compatible with Verkle trees.</p> <h2 id="specification">Specification</h2> <p>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 and RFC 8174.</p> <h3 id="definitions">Definitions</h3> <p>A contract is an alias contract if its nonce is <code>2^64-1</code>, and its contract code is equal to <code>0x1</code>.</p> <h3 id="prerequisites">Prerequisites</h3> <p><a href="https://wg-eips.ritovision.com/6188/">EIP-6188</a> MUST be used to protect the magic nonce value of <code>2^64-1</code>.</p> <h3 id="opcode-changes">Opcode Changes</h3> <h4 id="call-callcode-delegatecall-staticcall-pay-and-eoa-transactions"><code>CALL</code>, <code>CALLCODE</code>, <code>DELEGATECALL</code>, <code>STATICCALL</code>, <code>PAY</code>, and EOA Transactions</h4> <p>The "callee" refers to the account that is being called or being paid.</p> <p>If the nonce of the callee is <code>2^64-1</code>, the call MUST be forwarded to the address stored in the <code>0</code>th storage slot of the callee (as if the callee was the address stored in the <code>0</code>th storage slot of the callee). This MUST repeat until a non-alias contract is reached. The <code>CALLER</code> MUST remain unchanged.</p> <p>If there is more than one alias contract in the chain, the original callee and all subsequent callees (except the last one) MUST have their <code>0</code>th storage slot set to the address of the final non-alias contract. Then, the call MUST be forwarded as usual. <strong>This MUST occur, even in a read-only context like <code>STATICCALL</code>.</strong></p> <p>For example, if <code>A</code> is an alias contract that forwards calls to <code>B</code>, which is an alias contract that forwards calls to <code>C</code>, then <code>A</code>'s <code>0</code>th storage slot is set to <code>C</code>'s address. Then, the call is forwarded to <code>C</code>.</p> <p>Finally, the opcode MUST proceed as usual, using the final non-alias contract.</p> <p>The <code>CALL</code>, <code>CALLCODE</code>, <code>DELEGATECALL</code>, and <code>STATICCALL</code> opcodes and EOA Transactions MUST cost an <code>25</code> gas per account accessed in this manner (including the final one, and including if no aliased accounts were used), in addition to all the regular costs incurred by accessing accounts (see <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>). For every account whose <code>0</code>th storage slot is updated, those opcodes MUST also cost an additional <code>5000</code> gas.</p> <p>If an infinite loop occurs, the transaction MUST run out of gas and revert.</p> <h4 id="extcodehash-extcodecopy-extcodesize-and-balance"><code>EXTCODEHASH</code>, <code>EXTCODECOPY</code>, <code>EXTCODESIZE</code>, and <code>BALANCE</code></h4> <p>The "accessed account" refers to the account that is being accessed (i.e. the account whose code is being accessed, or the account whose balance is being accessed).</p> <p>Similar to the <code>CALL</code> family of opcodes, if the nonce of the accessed account is <code>2^64-1</code>, the accessed account's address MUST be replaced with the address stored in the <code>0</code>th storage slot of the accessed account. This MUST repeat until a non-alias contract is reached.</p> <p>If there is more than one alias contract in the chain, the original accessed account and all subsequent accessed accounts (except the last one) MUST have their <code>0</code>th storage slot set to the address of the final non-alias contract. Then, the accessed account MUST be replaced as usual. <strong>This MUST occur, even in a read-only context like <code>STATICCALL</code>.</strong></p> <p>Finally, the opcode MUST proceed as usual, using the final non-alias contract.</p> <p>The <code>EXTCODEHASH</code>, <code>EXTCODECOPY</code>, <code>EXTCODESIZE</code>, and <code>BALANCE</code> opcodes MUST cost an <code>25</code> gas per account accessed in this manner (including the final one, and including if no aliased accounts were used), in addition to all the regular costs incurred by accessing accounts (see <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>). For every account whose <code>0</code>th storage slot is updated, those opcodes MUST also cost an additional <code>5000</code> gas.</p> <p>If an infinite loop occurs, the transaction MUST run out of gas and revert.</p> <h4 id="create-and-create2"><code>CREATE</code> and <code>CREATE2</code></h4> <p>If <code>CREATE</code> or <code>CREATE2</code> would create (or fail to create, depending on which EIPs are used) an account at an address, and that account's code is <code>0x1</code>, and its nonce is <code>2^64-1</code>, then instead of reverting, an attempt MUST be made to create a contract at the address stored in the <code>0</code>th storage slot of the existing account. This MUST repeat until a non-alias contract is reached.</p> <p>If there is more than one alias contract in the chain, the original accessed account and all subsequent accessed accounts (except the last one) MUST have their <code>0</code>th storage slot set to the address of the final non-alias contract.</p> <p>Finally, the opcode MUST proceed as usual, returning the address of the newly-created contract.</p> <p>The <code>CREATE</code> and <code>CREATE2</code> opcodes MUST cost an <code>25</code> gas per account accessed in this manner (including the final one, and including if no aliased accounts were used), in addition to all the regular costs incurred by accessing accounts (see <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>). For every account whose <code>0</code>th storage slot is updated, those opcodes must also cost an additional <code>5000</code> gas.</p> <p>If an infinite loop occurs, the transaction runs out of gas and reverts.</p> <h4 id="address"><code>ADDRESS</code></h4> <p>This opcode remains unchanged; <code>ADDRESS</code> points to the address that doesn't have a nonce of <code>2^64-1</code>.33</p> <h3 id="transfers-to-the-zero-address">Transfers to the zero address</h3> <p>Transfers to the zero address continue to have the same effect as the <code>CREATE</code> opcode, and will cost extra gas as discussed in the <a href="https://wg-eips.ritovision.com/6189/#create-and-create2"><code>CREATE</code> and <code>CREATE2</code></a> section.</p> <h3 id="transaction-validity">Transaction Validity</h3> <p>The "origin" refers to the account that sent the transaction to be validated.</p> <p>If the nonce of the origin is <code>2^64-1</code>, the origin MUST be updated to the address stored in the <code>0</code>th storage slot of the current origin (as if the origin was the address stored in the <code>0</code>th storage slot of the current origin). This MUST repeat until a non-alias contract is reached.</p> <p>If there is more than one alias contract in the chain, the original origin and all subsequent origins (except the last one) MUST have their <code>0</code>th storage slot set to the address of the final non-alias contract. Then, the call MUST be forwarded as usual.</p> <p>An additional <code>25</code> gas per account accessed in this manner (including the final one, and including if no aliased accounts were used), in addition to all the regular costs incurred by accessing accounts (see <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>) is added to the validation costs. For every account whose <code>0</code>th storage slot is updated, it also costs an additional <code>5000</code> gas.</p> <p>Finally, validation proceeds as normal.</p> <h3 id="rpc-endpoint-changes">RPC Endpoint Changes</h3> <h4 id="eth-getstorageat"><code>eth_getStorageAt</code></h4> <p>The <code>eth_getStorageAt</code> RPC endpoint must error if the target contract has a contract code of <code>0x1</code> and a nonce of <code>2^64-1</code>.</p> <h2 id="rationale">Rationale</h2> <p>The additional gas cost of <code>25</code> represents the cost of fetching the nonce and comparing it to the given value.</p> <p><code>eth_getStorageAt</code> was modified to throw an error because of alias contracts' special behavior.</p> <p>The nonce of <code>2^64-1</code> was chosen since it is the nonce protected by <a href="https://wg-eips.ritovision.com/6188/">EIP-6188</a>.</p> <p>The contract code of <code>0x1</code> was chosen arbitrarily. A nonzero code was chosen just in case a non-alias contract with nonce <code>2^64-1</code> somehow had its code set to <code>0x0</code>, or an EOA had its nonce set to <code>2^64-1</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a protocol upgrade, since it modifies consensus rules. No existing contracts should be affected, as they will not have a nonce of <code>2^64-1</code>, nor will they have the contract code <code>0x1</code>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The additional gas costs may cause potential DoS attacks if they access an arbitrary contract's data or make frequent contract deactivations. Contract authors must be aware and design contracts accordingly. There may be an effect on existing deployed code performing autonomous destruction and revival.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-12-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gavin Johnhttps://github.com/Pandapip1 https://wg-eips.ritovision.com/6190/

Changes SELFDESTRUCT to only cause a finite number of state changes

<h2 id="abstract">Abstract</h2> <p>Changes <code>SELFDESTRUCT</code> to only cause a finite number of state changes.</p> <h2 id="motivation">Motivation</h2> <p>The <code>SELFDESTRUCT</code> instruction has a fixed price, but is unbounded in storage/account changes (it needs to delete all keys). This has been an outstanding concern for some time.</p> <p>Furthermore, with <em>Verkle trees</em> accounts will be organised differently. Account properties, including storage, would have individual keys. It would not be possible to traverse and find all used keys. This makes <code>SELFDESTRUCT</code> very challenging to support in Verkle trees. This EIP is a step towards supporting <code>SELFDESTRUCT</code> in Verkle trees.</p> <h2 id="specification">Specification</h2> <p>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 and RFC 8174.</p> <h3 id="prerequisites">Prerequisites</h3> <p><a href="https://wg-eips.ritovision.com/6188/">EIP-6188</a> and <a href="https://wg-eips.ritovision.com/6189/">EIP-6189</a> must be used for this EIP to function correctly.</p> <h3 id="selfdestruct-behaviour"><code>SELFDESTRUCT</code> Behaviour</h3> <p>Instead of destroying the contract at the end of the transaction, instead, the following will occur at the end of the transaction in which it is invoked:</p> <ol> <li>The contract's code is set to <code>0x1</code>, and its nonce is set to <code>2^64-1</code>.</li> <li>The contract's <code>0</code>th storage slot is set to the address that would be issued if the contract used the <code>CREATE</code> opcode (<code>keccak256(contractAddress, nonce)</code>). Note that the nonce is always <code>2^64-1</code>.</li> <li>If the contract was self-destructed after the call being forwarded by one or more alias contracts, the alias contract's <code>0</code>th storage slot is set to the address calculated in step 2.</li> <li>The contract's balance is transferred, in its entirety, to the address on the top of the stack.</li> <li>The top of the stack is popped.</li> </ol> <h3 id="gas-cost-of-selfdestruct">Gas Cost of <code>SELFDESTRUCT</code></h3> <p>The base gas cost of <code>SELFDESTRUCT</code> is set to <code>5000</code>. The gas cost of <code>SELFDESTRUCT</code> is increased by <code>5000</code> for each alias contract that forwarded to the contract being self-destructed. Finally, the <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> gas cost increase is applied.</p> <h2 id="rationale">Rationale</h2> <p>This EIP is designed to be a step towards supporting <code>SELFDESTRUCT</code> in Verkle trees while making the minimum amount of changes.</p> <p>The <code>5000</code> base gas cost and additional alias contracts represents the cost of setting the account nonce and first storage slot. The <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> gas cost increase is preserved for the reasons mentioned in said EIP's Rationale.</p> <p>The nonce of <code>2^64-1</code> was chosen since it is the nonce protected by <a href="https://wg-eips.ritovision.com/6188/">EIP-6188</a>. The account code of <code>0x1</code> was chosen since it was the code specified in <a href="https://wg-eips.ritovision.com/6189/">EIP-6189</a>.</p> <p>The address being the same as the one created by <code>CREATE</code> is designed to reduce possible attack vectors by not introducing a new mechanism by which accounts can be created at specific addresses.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a protocol upgrade, since it modifies consensus rules.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-11-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/6047/

Mandates emitting the Transfer event for ERC-721 NFTs during contract creation

<h2 id="abstract">Abstract</h2> <p>This EIP extends <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> to allow the tracking and indexing of NFTs by mandating that a pre-existing event be emitted during contract creation.</p> <p>ERC-721 requires a <code>Transfer</code> event to be emitted whenever a transfer or mint (i.e. transfer from <code>0x0</code>) or burn (i.g. transfer to <code>0x0</code>) occurs, <strong>except during contract creation</strong>. This EIP mandates that compliant contracts emit a <code>Transfer</code> event <strong>regardless of whether it occurs during or after contract creation.</strong></p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/721/">ERC-721</a> requires a <code>Transfer</code> event to be emitted whenever a transfer or mint (i.e. transfer from <code>0x0</code>) or burn (i.e. transfer to <code>0x0</code>) occurs, EXCEPT for during contract creation. Due to this exception, contracts can mint NFTs during contract creation without the event being emitted. Unlike ERC-721, the <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standard mandates events to be emitted regardless of whether such minting occurs during or outside of contract creation. This allows an indexing service or any off-chain service to reliably capture and account for token creation.</p> <p>This EIP removes this exception granted by ERC-721 and mandates emitting the <code>Transfer</code> for ERC-721 during contract creation. In this manner, indexers and off-chain applications can track token minting, burning, and transferring while relying only on ERC-721's <code>Transfer</code> event log.</p> <h2 id="specification">Specification</h2> <p>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> <ol> <li>Compliant contracts MUST implement <a href="https://wg-eips.ritovision.com/721/">ERC-721</a></li> <li>Compliant contracts MUST emit a <code>Transfer</code> event whenever a token is transferred, minted (i.e. transferred from <code>0x0</code>), or burned (i.g. transferred to <code>0x0</code>), <strong>including during contract creation.</strong></li> </ol> <h2 id="rationale">Rationale</h2> <p>Using the existing <code>Transfer</code> event instead of creating a new event (e.g. <code>Creation</code>) allows this EIP to be backward compatible with existing indexers.E</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>All contracts compliant with this EIP are compliant with ERC-721. However, not all contracts compliant with ERC-721 are compliant with this EIP.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No new security concerns.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-11-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/6046/

Change SELFDESTRUCT to not delete storage keys and use a special value in the account nonce to signal deactivation

<h2 id="abstract">Abstract</h2> <p>Change <code>SELFDESTRUCT</code> to not delete all storage keys, and to use a special value in the account nonce to signal <em>deactivated</em> accounts. Because the semantics of revival change (storage keys may exists), we also rename the instruction to <code>DEACTIVATE</code>.</p> <h2 id="motivation">Motivation</h2> <p>The <code>SELFDESTRUCT</code> instruction currently has a fixed price, but is unbounded in terms of how many storage/account changes it performs (it needs to delete all keys). This has been an outstanding concern for some time.</p> <p>Furthermore, with <em>Verkle trees</em>, accounts will be organised differently: account properties, including storage, will have individual keys. It will not be possible to traverse and find all used keys. This makes <code>SELFDESTRUCT</code> very challenging to support in Verkle trees.</p> <h2 id="specification">Specification</h2> <ol> <li> <p>Change the rules introduced by <a href="https://wg-eips.ritovision.com/2681/">EIP-2681</a> such that regular nonce increase is bound by <code>2^64-2</code> instead of <code>2^64-1</code>. This applies from genesis.</p> </li> <li> <p>The behaviour of <code>SELFDESTRUCT</code> is changed such that:</p> </li> </ol> <ul> <li>Does not delete any storage keys and also leave the account in place.</li> <li>Transfer the account balance to the target <strong>and</strong> set account balance to <code>0.</code></li> <li>Set the account nonce to <code>2^64-1</code>.</li> <li>Note that no refund is given since <a href="https://wg-eips.ritovision.com/3529/">EIP-3529</a>.</li> <li>Note that the rules of <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> regarding <code>SELFDESTRUCT</code> remain unchanged.</li> </ul> <ol start="2"> <li>Modify account execution (triggered both via external transactions or CALL* instructions), such that execution succeeds and returns an empty buffer if the nonce equals <code>2^64-1</code>.</li> </ol> <ul> <li>Note that the account can still receive non-executable value transfers (such as coinbase transactions or other <code>SELFDESTRUCT</code>s).</li> </ul> <ol start="3"> <li>Modify <code>CREATE2</code> such that it allows account creation if the nonce equals <code>2^64-1</code>.</li> </ol> <ul> <li>Note that the account (especially code and storage) might not be empty prior to <code>CREATE2</code>.</li> <li>Note that a successful <code>CREATE2</code> will change the account code, nonce and potentially balance.</li> </ul> <ol start="4"> <li>Rename the <code>SELFDESTRUCT</code> instruction to <code>DEACTIVATE</code>, because the semantics of "account revival" are changed: the old storage items will remain, and newly deployed code must be aware of this.</li> </ol> <h2 id="rationale">Rationale</h2> <p>There have been various proposals of removing <code>SELFDESTRUCT</code> and many would just outright remove the deletion capability. This breaks certain usage patterns, which the <em>deactivation</em> option leaves intact, albeit with minor changes. This only affects <em>newly</em> deployed code, and not existing one.</p> <p>All the proposals would leave data in the state, but this proposal provides the flexibility to reuse or remove storage slots one-by-one should the revived contract choose to do so.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a protocol upgrade, since it modifies consensus rules. The further restriction of nonce should not have an effect on accounts, as <code>2^64-2</code> is an unfeasibly high limit.</p> <p>Contracts using the revival pattern will still work, but the code deployed during revival may need to be made aware that storage keys can already exist in the account.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The new behaviour of preserving storage has a potential effect on security. Contract authors must be aware and design contracts accordingly. There may be an effect on existing deployed code performing autonomous destruction and revival.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-11-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Base Labshttps://github.com/Base-Labs Weiji Guohttps://github.com/weiji-cryptonatty https://wg-eips.ritovision.com/6051/

defines a specification for encapsulating private keys.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a mechanism to encapsulate a private key so that it could be securely relocated to another application without providing the seed. This EIP combines <code>ECIES</code> (Elliptic Curve Integrated Encryption Scheme) and optional signature verification under various choices to ensure that the private key is encapsulated for a known or trusted party.</p> <h2 id="motivation">Motivation</h2> <p>There are various cases in which we might want to export one of many private keys from a much more secure but less convenient wallet, which is controlled with a seed or passphrase.</p> <ol> <li>We might dedicate one of many private keys for messaging purposes, and that private key is probably managed in a not-so-secure manner;</li> <li>We might want to export one of many private keys from a hardware wallet, and split it with MPC technology so that a 3rd party service could help us identify potential frauds or known bad addresses, enforce 2FA, etc., meanwhile we can initiate transactions from a mobile device with much better UX and without carrying a hardware wallet.</li> </ol> <p>In both cases, it is safer not to provide the seed which controls the whole wallet and might contains many addresses in multiple chains.</p> <p>This EIP aims to enable such use cases.</p> <h2 id="specification">Specification</h2> <h3 id="sender-and-recipient">Sender and Recipient</h3> <p>We hereby define:</p> <ul> <li> <p><em>Sender</em> as the party who holds in custody the private key to be encapsulated; <em>Sender Application</em> as the client-side application that said <em>Sender</em> uses to send the encapsulated private key.</p> </li> <li> <p><em>Recipient</em> as the party who accepts the encapsulated private key, unwraps, and then uses it; <em>Recipient Application</em> as the client-side application that <em>Recipient</em> uses to receive the encapsulated private key.</p> </li> </ul> <h3 id="core-algorithms">Core Algorithms</h3> <p>The basic idea is to encapsulate the private key with ECIES. To ensure that the ephemeral public key to encapsulate the private key is indeed generated from a trusted party and has not been tampered with, we also provided an option to sign that ephemeral public key in this standard.</p> <p>There should be a mandatory <code>version</code> parameter. This allows various kinds of Key Encapsulation Mechanisms to be adopted depending on security considerations or preferences. The list shall be short to minimize compatibility issues among different vendors.</p> <p>In addition to a <code>version</code> parameter, the following keys and functions are involved:</p> <ol> <li>The Sender's private key <code>sk</code>, which is to be encapsulated to the Recipient, and the corresponding address <code>account</code>.</li> <li>The ephemeral Recipient key pair <code>(r, R)</code> such that <code>R = [r]G</code>. <code>G</code> denotes the base point of the elliptic curve, and <code>[r]G</code> denotes scalar multiplication. Optionally, <code>R</code> could be signed, and <code>signerPubKey</code> and <code>signature</code> are then provided for Sender to verify if <code>R</code> could be trusted or not.</li> <li>The ephemeral Sender key pair <code>(s, S)</code> such that <code>S = [s]G</code>.</li> <li>The share secret <code>ss := [s]R = [r]S</code> according to ECDH. Note that for secp256k1 this EIP follows RFC5903 and uses compact representation, which means to use <em>only</em> the <code>x</code> coordinate as the shared secret. For Curve25519 this EIP follows RFC7748.</li> <li>The out-of-band data <code>oob</code>, optional. This could be digits or an alpha-numeric string entered by the user.</li> <li>Let <code>derivedKey := HKDF(hash=SHA256, ikm=ss, info=oob, salt, length)</code>. HKDF is defined in RFC5869. The <code>length</code> should be determined by <code>skey</code> and <code>IV</code> requirements such that the symmetric key <code>skey = derivedKey[0:keySize]</code>, and <code>IV = derivedKey[keySize:length]</code>. <code>keySize</code> denotes the key size of the underlying symmetric algorithm, for example, 16 (bytes) for AES-128, and 32 (bytes) for Chacha20. See <strong>Security Considerations</strong> for the use of <code>salt</code>.</li> <li>Let <code>cipher := authenticated_encryption(symAlg, skey, IV, data=sk)</code>. The symmetric cipher algorithm <code>symAlg</code> and authentication scheme are decided by the version parameter. No additional authentication data <code>aad</code> is used.</li> </ol> <p>A much-simplified example flow without signature and verification is:</p> <ol> <li><em>Recipient Application</em> generates <code>(r, R)</code>.</li> <li>User inputs <code>R</code> to <em>Sender Application</em>, along with a six-digit code “123456” as <code>oob</code>.</li> <li><em>Sender Application</em> generates <code>(s, S)</code>, and computes <code>cipher</code>, then returns <code>S || cipher</code>.</li> <li><em>Recipient Application</em> scans to read <code>S</code> and <code>cipher</code>. The user enters “123456” as <code>oob</code> to <em>Recipient Application</em>.</li> <li><em>Recipient Application</em> decrypts <code>cipher</code> to get <code>sk</code>.</li> <li><em>Recipient Application</em> derives the address corresponding to <code>sk</code> so that the user can confirm the correctness.</li> </ol> <p>With signature and verification, the signature to <code>R</code> by <code>singerPubKey</code> is appended to <code>R</code>. <code>signerPubKey</code> itself could have been already signed by <code>trustedPubKey</code>, and that signature is appended to <code>signerPubKey</code>. Note that the signature is applied to the byte array data instead of its string representation, which might lead to confusion and interoperability issues (such as hex or base64, lower case v.s. upper case, etc.). See <a href="https://wg-eips.ritovision.com/6051/#requests">Requests</a> and <a href="https://wg-eips.ritovision.com/6051/#test-cases">Test Cases</a> for further clarification and examples.</p> <h3 id="requests">Requests</h3> <h4 id="encoding-of-data-and-messages">Encoding of data and messages</h4> <ul> <li>Raw bytes are encoded in hex and prefixed with '0x'.</li> <li>Unless specified otherwise, all parameters and return values are hex-encoded bytes.</li> <li><code>cipher</code> is encoded into a single byte buffer as: <code>[IV || encrypted_sk || tag]</code>.</li> <li><code>R</code>, <code>S</code>, <code>signerPubKey</code>, and <code>trustedPubKey</code> are compressed if applicable.</li> <li><code>R</code> or <code>signerPubKey</code> could be followed by a signature to it: <code>[pub || sig]</code>. Note that for the secp256k1 curve, the signature is just 64 bytes without the <code>v</code> indicator as found in a typical Ethereum signature.</li> </ul> <h4 id="r1-request-for-recipient-to-generate-ephemeral-key-pair">R1. Request for Recipient to generate ephemeral key pair</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_generateEphemeralKeyPair</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span><span class="z-variable z-other">version</span><span>,</span><span class="z-variable z-other"> signerPubKey</span><span>]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> expected return value: R</span></span></code></pre> <p><code>signerPubKey</code> is optional. If provided, it is assumed that the implementation has the corresponding private key and the implementation MUST sign the ephemeral public key (in the form of what is to be returned). The signature algorithm is determined by the curve part of the <code>version</code> parameter, that is, ECDSA for secp256k1, and Ed25519 for Curve25519. And in this situation, it should be the case that <em>Sender</em> trusts <code>signerPubKey</code>, no matter how this trust is maintained. If not, the next request WILL be rejected by <em>Sender Application</em>. Also, see <a href="https://wg-eips.ritovision.com/6051/#security-considerations">Security Considerations</a>.</p> <p>The implementation then MUST generate random private key <code>r</code> with a cryptographic secure random number generator (CSRNG), and derive ephemeral public key <code>R = [r]G</code>. The implementation SHOULD keep the generated key pair <code>(r, R)</code> in a secure manner in accordance with the circumstances, and SHOULD keep it only for a limited duration, but the specific duration is left to individual implementations. The implementation SHOULD be able to retrieve <code>r</code> when given back the corresponding public key <code>R</code> if within the said duration.</p> <p>The return value is <code>R</code>, compressed if applicable. If <code>signerPubKey</code> is provided, then the <code>signature</code> is appended to <code>R</code>, also hex-encoded.</p> <p>Alternatively, <code>signature</code> could be calculated separately, and then appended to the returned data.</p> <h4 id="r2-request-for-sender-to-encapsulate-the-private-key">R2. Request for Sender to encapsulate the private key</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_encapsulatePrivateKey</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> recipient</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> public key, may be followed by its signature, see signerPubKey</span></span> <span class="giallo-l"><span class="z-variable z-other"> signerPubKey</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> oob</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> account</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> expected return value: S || cipher</span></span></code></pre> <p><code>recipient</code> is the return value from the call to generate ephemeral key pair, with the optional <code>signature</code> appended either as returned or separately.</p> <p><code>oob</code> and <code>salt</code> are just byte arrays.</p> <p><code>account</code> is used to identify which private key to be encapsulated. With Ethereum, it is an address. Also, see <a href="https://wg-eips.ritovision.com/6051/#encoding-of-data-and-messages">Encoding of data and messages</a>.</p> <p>If <code>signerPubKey</code> is provided or <code>recipient</code> contains <code>signature</code> data, the implementation MUST perform signature verification. Missing data or incorrect format MUST either fail the call or result in an empty return and optional error logs.</p> <p><code>signerPubKey</code> could have been further signed by another key pair <code>(trusted, trustedPubKey)</code>, which is trusted by <em>Sender Application</em>. In that case, <code>signerPubKey</code> is appended with the corresponding signature data, which SHOULD be verified against <code>trustedPubKey</code>. See <a href="https://wg-eips.ritovision.com/6051/#test-cases">Test Cases</a> for further clarification.</p> <p>The implementation shall then proceed to retrieve the private key <code>sk</code> corresponding to <code>account</code>, and follow the <a href="https://wg-eips.ritovision.com/6051/#core-algorithms">Core Algorithms</a> to encrypt it.</p> <p>The return data is a byte array that contains first <em>Sender</em>'s ephemeral public key <code>S</code> (compressed if applicable), then <code>cipher</code> including any authentication tag, that is, <code>S || cipher</code>.</p> <h4 id="r3-request-for-recipient-to-unwrap-and-intake-the-private-key">R3. Request for Recipient to unwrap and intake the private key</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_intakePrivateKey</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> recipientPublicKey</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> no signature this time</span></span> <span class="giallo-l"><span class="z-variable z-other"> oob</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> salt</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> data</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> expected return value: account</span></span></code></pre> <p>This time <code>recipientPublicKey</code> is only the ephemeral public key <code>R</code> generated earlier in the Recipient side, just for the implementation to retrieve the corresponding private key <code>r</code>. <code>data</code> is the return value from the call to encapsulate private key, which is <code>S || cipher</code>.</p> <p>When the encapsulated private key <code>sk</code> is decrypted successfully, the implementation can process it further according to the designated purposes. Some general security guidelines SHALL be followed, for example, do <em>not</em> log the value, do securely wipe it after use, etc.</p> <p>The return value is the corresponding Ethereum address for <code>sk</code>, or empty if any error.</p> <h3 id="options-and-parameters">Options and Parameters</h3> <p>Available elliptic curves are:</p> <ul> <li>secp256k1 (mandatory)</li> <li>Curve25519</li> </ul> <p>Available authenticated encryption schemes are:</p> <ul> <li>AES-128-GCM (mandatory)</li> <li>AES-256-GCM</li> <li>Chacha20-Poly1305</li> </ul> <p>The version string is simply the concatenation of the elliptic curve and AE scheme, for example, secp256k1-AES-128-GCM. The above lists allow a combination of six different concrete schemes. Implementations are encouraged to implement curve-related logic separately from authenticated encryption schemes to avoid duplication and to promote interoperability.</p> <p>Signature algorithms for each curve are:</p> <ul> <li>secp256k1 --&gt; ECDSA</li> <li>Curve25519 --&gt; Ed25519</li> </ul> <h2 id="rationale">Rationale</h2> <p>A critical difference between this <a href="https://wg-eips.ritovision.com/6051/">EIP-6051</a> with <a href="https://wg-eips.ritovision.com/5630/">EIP-5630</a> is that, as the purpose of key encapsulation is to transport a private key securely, the public key from the key recipient should be ephemeral, and mostly used only one-time. While in EIP-5630 settings, the public key of the message recipient shall be stable for a while so that message senders can encrypt messages without key discovery every time.</p> <p>There is security implication to this difference, including perfect forward secrecy. We aim to achieve perfect forward secrecy by generating ephemeral key pairs on both sides every time:</p> <ol> <li>first <em>Recipient</em> shall generate an ephemeral key pair, retain the private key securely, and export the public key;</li> <li>then <em>Sender</em> can securely wrap the private key in ECIES, with another ephemeral key pair, then destroy the ephemeral key securely;</li> <li>finally <em>Recipient</em> can unwrap the private key, then destroy its ephemeral key pair securely. After these steps, the cipher text in transport intercepted by a malicious 3rd party is no longer decryptable.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues for this new proposal.</p> <h3 id="interoperability">Interoperability</h3> <p>To minimize potential compatibility issues among applications (including hardware wallets), this EIP requires that version secp256k1-AES-128-GCM MUST be supported.</p> <p>The version could be decided by the user or negotiated by both sides. When there is no user input or negotiation, secp256k1-AES-128-GCM is assumed.</p> <p>It is expected that implementations cover curve supports separately from encryption support, that is, all the versions that could be derived from the supported curve and supported encryption scheme should work.</p> <p>Signatures to <code>R</code> and <code>signerPubKey</code> are applied to byte array values instead of the encoded string.</p> <h3 id="ux-recommendations">UX Recommendations</h3> <p><code>salt</code> and/or <code>oob</code> data: both are inputs to the HKDF function (<code>oob</code> as “info” parameter). For better user experiences we suggest to require from users only one of them but this is up to the implementation.</p> <p><em>Recipient Application</em> is assumed to be powerful enough. <em>Sender Application</em> could have very limited computing power and user interaction capabilities.</p> <h2 id="test-cases">Test Cases</h2> <p>For review purposes, the program to generate the test vectors is open-sourced and provided in the corresponding discussion thread.</p> <h3 id="data-fixation">Data Fixation</h3> <p>Throughout the test cases, we fix values for the below data:</p> <ul> <li><code>sk</code>, the private key to be encapsulated, fixed to: <code>0xf8f8a2f43c8376ccb0871305060d7b27b0554d2cc72bccf41b2705608452f315</code>. The corresponding address is <code>0x001d3f1ef827552ae1114027bd3ecf1f086ba0f9</code>, called <code>account</code>. Note that these values come from the book <em>Mastering Ethereum</em> by Andreas M. Antonopoulos and Gavin Wood.</li> <li><code>r</code>, the Recipient private key, fixed to <code>0x6f2dd2a7804705d2d536bee92221051865a639efa23f5ca7c810e77048253a79</code></li> <li><code>s</code>, the Sender private key, fixed to <code>0x28fa2db9f916e44fcc88370bedaf5eb3ec45632f040f4c1450c0f101e1e8bac8</code></li> <li><code>signer</code>, the private key to sign the ephemeral public key, fixed to <code>0xac304db075d1685284ba5e10c343f2324ee32df3394fc093c98932517d36e344</code>. When used for Ed25519 signing, however, this value acts as <code>seed</code>, while the actual private key is calculated as <code>SHA512(seed)[:32]</code>. Or put another way, the public key is the scalar multiplication of hashed private key to the base point. Same for <code>trusted</code>.</li> <li><code>trusted</code>, the private key to sign <code>signerPubKey</code>, fixed to <code>0xda6649d68fc03b807e444e0034b3b59ec60716212007d72c9ddbfd33e25d38d1</code></li> <li><code>oob</code>, fixed to <code>0x313233343536</code> (string value: <code>123456</code>)</li> <li><code>salt</code>, fixed to <code>0x6569703a2070726976617465206b657920656e63617073756c6174696f6e</code> (string value: <code>eip: private key encapsulation</code>)</li> </ul> <h3 id="case-1">Case 1</h3> <p>Use <code>version</code> as <code>secp256k1-AES-128-GCM</code>. <strong>R1</strong> is provided as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_generateEphemeralKeyPair</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">secp256k1-AES-128-GCM</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signerPubKey</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x035a5ca16997f9b9ead9572c9bde36c5dab584b17bc965cdd7c2945c776e981b0b</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>Suppose the implementation generates an ephemeral key pair <code>(r, R)</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>r: &#39;0x6f2dd2a7804705d2d536bee92221051865a639efa23f5ca7c810e77048253a79&#39;,</span></span> <span class="giallo-l"><span>R: &#39;0x039ef98feddb39664450c3876878093c70652caba7e3fd04333c0558ffdf798d09&#39;</span></span></code></pre> <p>The return value could be:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&#39;0x039ef98feddb39664450c3876878093c70652caba7e3fd04333c0558ffdf798d09536da06b8d9207040ada179dc2c38f701a1a21c9ab5a7d52f5da50ea438e8ccf47dac77547fbdde194f71db52860b9e10ca2b089646f133d172124504ac1996a&#39;</span></span></code></pre> <p>Note that <code>R</code> is compressed and <code>R</code> leads the return value: <code>R || sig</code>.</p> <p>Therefore <strong>R2</strong> could be provided as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_encapsulatePrivateKey</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">secp256k1-AES-128-GCM</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> recipient</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x039ef98feddb39664450c3876878093c70652caba7e3fd04333c0558ffdf798d09536da06b8d9207040ada179dc2c38f701a1a21c9ab5a7d52f5da50ea438e8ccf47dac77547fbdde194f71db52860b9e10ca2b089646f133d172124504ac1996a</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signerPubKey</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x035a5ca16997f9b9ead9572c9bde36c5dab584b17bc965cdd7c2945c776e981b0b5bd427c527b7f1012b8edfd179b9002a7f2d7fc326bb6ae9aaf38b44eb93c397631fd8bb05fd78fa16ecca1eb19652b200f9048611265bc81f485cf60f29d6de</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> oob</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x313233343536</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> salt</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x6569703a2070726976617465206b657920656e63617073756c6174696f6e</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> account</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x001d3f1ef827552ae1114027bd3ecf1f086ba0f9</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p><em>Sender Application</em> first verifies first layer signature as ECDSA over secp256k1:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// actual message to be signed should be the decoded byte array</span></span> <span class="giallo-l"><span>msg: &#39;0x039ef98feddb39664450c3876878093c70652caba7e3fd04333c0558ffdf798d09&#39;,</span></span> <span class="giallo-l"><span>sig: &#39;0x536da06b8d9207040ada179dc2c38f701a1a21c9ab5a7d52f5da50ea438e8ccf47dac77547fbdde194f71db52860b9e10ca2b089646f133d172124504ac1996aaf4a811661741a43587dd458858b75c582ca7db82fa77b&#39;,</span></span> <span class="giallo-l"><span>//signerPubKey</span></span> <span class="giallo-l"><span>pub: &#39;0x035a5ca16997f9b9ead9572c9bde36c5dab584b17bc965cdd7c2945c776e981b0b&#39;</span></span></code></pre> <p>Then it proceeds to verify the second layer signature, also as ECDSA over secp256k1:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// actual message to be signed should be the decoded byte array</span></span> <span class="giallo-l"><span>msg: &#39;0x035a5ca16997f9b9ead9572c9bde36c5dab584b17bc965cdd7c2945c776e981b0b&#39;,</span></span> <span class="giallo-l"><span>sig: &#39;0x5bd427c527b7f1012b8edfd179b9002a7f2d7fc326bb6ae9aaf38b44eb93c397631fd8bb05fd78fa16ecca1eb19652b200f9048611265bc81f485cf60f29d6de&#39;,</span></span> <span class="giallo-l"><span>//trustedPubKey</span></span> <span class="giallo-l"><span>pub: &#39;0x027fb72176f1f9852ce7dd9dc3aa4711675d3d8dc5102b86d758d853002137e839&#39;</span></span></code></pre> <p>Since <em>Sender Application</em> trusts <code>trustedPubKey</code>, the signature verification succeeds.</p> <p>Suppose the implementation generates an ephemeral key pair <code>(s, S)</code> as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>s: &#39;0x28fa2db9f916e44fcc88370bedaf5eb3ec45632f040f4c1450c0f101e1e8bac8&#39;,</span></span> <span class="giallo-l"><span>S: &#39;0x02ced2278d9ebb193f166d4ee5bbbc5ab8ca4b9ddf23c4172ad11185c079944c02&#39;</span></span></code></pre> <p>The shared secret, symmetric key, and IV should be:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ss: &#39;0x8e83bc5a9c77b11afc12c9a8262b16e899678d1720459e3b73ca2abcfed1fca3&#39;,</span></span> <span class="giallo-l"><span>skey: &#39;0x6ccc02a61aa16d6c66a1277e5e2434b8&#39;,</span></span> <span class="giallo-l"><span>IV: &#39;0x9c7a0f870d17ced2d2c3d1cf&#39;</span></span></code></pre> <p>Then the return value should be:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&#39;0x02ced2278d9ebb193f166d4ee5bbbc5ab8ca4b9ddf23c4172ad11185c079944c02abff407e8901bb37d13d724a2e3a8a1a5af300adc286aa2ec65ef2a38c10c5cec68a949d0a20dbad2a8e5dfd7a14bbcb&#39;</span></span></code></pre> <p>With compressed public key <code>S</code> leading <code>cipher</code>, which in turn is (added prefix '0x'):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&#39;0xabff407e8901bb37d13d724a2e3a8a1a5af300adc286aa2ec65ef2a38c10c5cec68a949d0a20dbad2a8e5dfd7a14bbcb&#39;</span></span></code></pre> <p>Then <strong>R3</strong> is provided as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_intakePrivateKey</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">secp256k1-AES-128-GCM</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> recipientPublicKey</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x039ef98feddb39664450c3876878093c70652caba7e3fd04333c0558ffdf798d09</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> oob</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x313233343536</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> salt</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x6569703a2070726976617465206b657920656e63617073756c6174696f6e</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> data</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x02ced2278d9ebb193f166d4ee5bbbc5ab8ca4b9ddf23c4172ad11185c079944c02abff407e8901bb37d13d724a2e3a8a1a5af300adc286aa2ec65ef2a38c10c5cec68a949d0a20dbad2a8e5dfd7a14bbcb</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>The return value should be <code>0x001d3f1ef827552ae1114027bd3ecf1f086ba0f9</code>. This matches the <code>account</code> parameter in <strong>R2</strong>.</p> <h3 id="case-2">Case 2</h3> <p>Use <code>version</code> as <code>secp256k1-AES-256-GCM</code>. The calculated symmetric key <code>skey</code>, <code>IV</code>, and <code>cipher</code> will be different. <strong>R1</strong> is provided as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_generateEphemeralKeyPair</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">secp256k1-AES-256-GCM</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signerPubKey</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x035a5ca16997f9b9ead9572c9bde36c5dab584b17bc965cdd7c2945c776e981b0b</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>Note that only the <code>version</code> is different (AES key size). We keep using the same <code>(r, R)</code> (this is just a test vector).</p> <p>Therefore <strong>R2</strong> is provided as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_encapsulatePrivateKey</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">secp256k1-AES-256-GCM</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> recipient</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x039ef98feddb39664450c3876878093c70652caba7e3fd04333c0558ffdf798d09536da06b8d9207040ada179dc2c38f701a1a21c9ab5a7d52f5da50ea438e8ccf47dac77547fbdde194f71db52860b9e10ca2b089646f133d172124504ac1996a</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signerPubKey</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x035a5ca16997f9b9ead9572c9bde36c5dab584b17bc965cdd7c2945c776e981b0b5bd427c527b7f1012b8edfd179b9002a7f2d7fc326bb6ae9aaf38b44eb93c397631fd8bb05fd78fa16ecca1eb19652b200f9048611265bc81f485cf60f29d6de</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> oob</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x313233343536</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> salt</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x6569703a2070726976617465206b657920656e63617073756c6174696f6e</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> account</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x001d3f1ef827552ae1114027bd3ecf1f086ba0f9</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>Suppose the implementation generates the same <code>(s, S)</code> as <a href="https://wg-eips.ritovision.com/6051/#case-1">Case 1</a>. The shared secret, symmetric key, and IV should be:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ss: &#39;0x8e83bc5a9c77b11afc12c9a8262b16e899678d1720459e3b73ca2abcfed1fca3&#39;,</span></span> <span class="giallo-l"><span>skey: &#39;0x6ccc02a61aa16d6c66a1277e5e2434b89c7a0f870d17ced2d2c3d1cfd0e6f199&#39;,</span></span> <span class="giallo-l"><span>IV: &#39;0x3369b9570b9d207a0a8ebe27&#39;</span></span></code></pre> <p>With shared secret <code>ss</code> remaining the same as <a href="https://wg-eips.ritovision.com/6051/#case-1">Case 1</a>, symmetric key <code>skey</code> contains both the <code>skey</code> and <code>IV</code> from <a href="https://wg-eips.ritovision.com/6051/#case-1">Case 1</a>. IV is changed.</p> <p>Then the return value should be the following, with the <code>S</code> part the same as <a href="https://wg-eips.ritovision.com/6051/#case-1">Case 1</a> and the <code>cipher</code> part different:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&#39;0x02ced2278d9ebb193f166d4ee5bbbc5ab8ca4b9ddf23c4172ad11185c079944c0293910a91270b5deb0a645cc33604ed91668daf72328739d52a5af5a4760c4f3a9592b8f6d9b3ebe25127e7bf1c43b839&#39;</span></span></code></pre> <p>Then <strong>R3</strong> is provided as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_intakePrivateKey</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">secp256k1-AES-256-GCM</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> recipientPublicKey</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x039ef98feddb39664450c3876878093c70652caba7e3fd04333c0558ffdf798d09</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> oob</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x313233343536</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> salt</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x6569703a2070726976617465206b657920656e63617073756c6174696f6e</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> data</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x02ced2278d9ebb193f166d4ee5bbbc5ab8ca4b9ddf23c4172ad11185c079944c0293910a91270b5deb0a645cc33604ed91668daf72328739d52a5af5a4760c4f3a9592b8f6d9b3ebe25127e7bf1c43b839</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>The return value should be <code>0x001d3f1ef827552ae1114027bd3ecf1f086ba0f9</code>. This matches the <code>account</code> parameter in <strong>R2</strong>.</p> <h3 id="case-3">Case 3</h3> <p>Use <code>version</code> as: <code>Curve-25519-Chacha20-Poly1305</code>. <strong>R1</strong> is provided as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_generateEphemeralKeyPair</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">Curve25519-Chacha20-Poly1305</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signerPubKey</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0xe509fb840f6d5a69333ef68d69b86de55b9b905e45b16e3591912c097ba69938</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>Note that with Curve25519 the size is 32 (bytes) for both the public key and private key. And there is no compression for the public key. <code>signerPubKey</code> is calculated as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>//signer is &#39;0xac304db075d1685284ba5e10c343f2324ee32df3394fc093c98932517d36e344&#39;</span></span> <span class="giallo-l"><span>s := SHA512(signer)[:32]</span></span> <span class="giallo-l"><span>signerPubKey := Curve25519.ScalarBaseMult(s).ToHex()</span></span></code></pre> <p>The same technique applies to <code>trustedPubKey</code>. With <code>r</code> the same as in <a href="https://wg-eips.ritovision.com/6051/#case-1">Case 1</a> and <a href="https://wg-eips.ritovision.com/6051/#case-2">Case 2</a> and the curve being changed, the return value is <code>R = [r]G || sig</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>R = &#39;0xc0ea3514b0ab83b2fe4f4ef96159cda8fa836ce549ef09569b901eef0723bf79cac06de279ec7f65f6b75f6bee740496df0650a6de61da5e691d7c5da1c7cb1ece61c669dd588a1029c38f11ad1714c1c9742232f9562ca6bbc7bad57882da04&#39;</span></span></code></pre> <p><strong>R2</strong> is provided as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_encapsulatePrivateKey</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">Curve25519-Chacha20-Poly1305</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> recipient</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0xc0ea3514b0ab83b2fe4f4ef96159cda8fa836ce549ef09569b901eef0723bf79879d900f04a955078ff6ae86f1d1b69b3e1265370e64bf064adaecb895c51effa3bdae7964bf8f9a6bfaef3b66306c1bc36afa5607a51b9768aa42ac2c961f02</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> signerPubKey</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0xe509fb840f6d5a69333ef68d69b86de55b9b905e45b16e3591912c097ba69938d43e06a0f32c9e5ddb39fce34fac2b6f5314a1b1583134f27426d50af7094b0c101e848737e7f717da8c8497be06bab2a9536856c56eee194e89e94fd1bba509</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> oob</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x313233343536</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> salt</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x6569703a2070726976617465206b657920656e63617073756c6174696f6e</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> account</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x001d3f1ef827552ae1114027bd3ecf1f086ba0f9</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>Both <code>recipient</code> and <code>signerPubKey</code> have been signed in Ed25519. Verifying signature to <code>R</code> is carried out as:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// actual message to be signed should be the decoded byte array</span></span> <span class="giallo-l"><span>msg: &#39;0xc0ea3514b0ab83b2fe4f4ef96159cda8fa836ce549ef09569b901eef0723bf79&#39;,</span></span> <span class="giallo-l"><span>sig: &#39;0x879d900f04a955078ff6ae86f1d1b69b3e1265370e64bf064adaecb895c51effa3bdae7964bf8f9a6bfaef3b66306c1bc36afa5607a51b9768aa42ac2c961f02&#39;,</span></span> <span class="giallo-l"><span>//signerPubKey</span></span> <span class="giallo-l"><span>pub: &#39;0xe509fb840f6d5a69333ef68d69b86de55b9b905e45b16e3591912c097ba69938&#39;</span></span></code></pre> <p>After successfully verifying the signature (and the one by <code>trustedPubKey</code>), the implementation then generates ephemeral key pair <code>(s, S)</code> in Curve25519:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// s same as Case 1 and Case 2</span></span> <span class="giallo-l"><span>s = &#39;0x28fa2db9f916e44fcc88370bedaf5eb3ec45632f040f4c1450c0f101e1e8bac8&#39;,</span></span> <span class="giallo-l"><span>S = &#39;0xd2fd6fcaac231d08363e736e61edb7e7696b13a727e3d2a239415cb8dc6ee278&#39;</span></span></code></pre> <p>The shared secret, symmetric key, and IV should be:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ss: &#39;0xe0b36f56cdb63c27e933a5a67a5e97db4b566c9276a36aeee5dc6e87da118867&#39;,</span></span> <span class="giallo-l"><span>skey: &#39;0x7c6fa749e6df13c8578dc44cb24cdf46a44cb163e1e570c2e590c720aed5783f&#39;,</span></span> <span class="giallo-l"><span>IV: &#39;0x3c98ef6fc34b0d6e7e16bd78&#39;</span></span></code></pre> <p>Then the return value should be <code>S || cipher</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&#39;0xd2fd6fcaac231d08363e736e61edb7e7696b13a727e3d2a239415cb8dc6ee2786a7e2e40efb86dc68f44f3e032bbedb1259fa820e548ac5adbf191784c568d4f642ca5b60c0b2142189dff6ee464b95c&#39;</span></span></code></pre> <p>Then <strong>R3</strong> is provided as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">request</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_intakePrivateKey</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-variable z-other"> version</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">Curve25519-Chacha20-Poly1305</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> recipientPublicKey</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0xc0ea3514b0ab83b2fe4f4ef96159cda8fa836ce549ef09569b901eef0723bf79</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> oob</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x313233343536</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> salt</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x6569703a2070726976617465206b657920656e63617073756c6174696f6e</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> data</span><span>: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0xd2fd6fcaac231d08363e736e61edb7e7696b13a727e3d2a239415cb8dc6ee2786a7e2e40efb86dc68f44f3e032bbedb1259fa820e548ac5adbf191784c568d4f642ca5b60c0b2142189dff6ee464b95c</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span></code></pre> <p>The return value should be <code>0x001d3f1ef827552ae1114027bd3ecf1f086ba0f9</code>. This matches the <code>account</code> parameter in <strong>R2</strong>.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="perfect-forward-secrecy">Perfect Forward Secrecy</h3> <p>PFS is achieved by using ephemeral key pairs on both sides.</p> <h3 id="optional-signature-and-trusted-public-keys">Optional Signature and Trusted Public Keys</h3> <p><code>R</code> could be signed so that <em>Sender Application</em> can verify if <code>R</code> could be trusted or not. This involves both signature verification and if the signer could be trusted or not. While signature verification is quite straightforward in itself, the latter should be managed with care. To facilitate this trust management issue, <code>signerPubKey</code> could be further signed, creating a dual-layer trust structure:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>R &lt;-- signerPubKey &lt;-- trustedPubKey</span></span></code></pre> <p>This allows various strategies to manage trust. For example:</p> <ul> <li>A hardware wallet vendor which takes it very seriously about the brand reputation and the fund safety for its customers, could choose to trust only its own public keys, all instances of <code>trustedPubKey</code>. These public keys only sign <code>signerPubKey</code> from selected partners.</li> <li>A MPC service could publish its <code>signerPubKey</code> online so that <em>Sender Application</em> won't verify the signature against a wrong or fake public key.</li> </ul> <p>Note that it is advised that a separate key pair should be used for signing on each curve.</p> <h3 id="security-level">Security Level</h3> <ol> <li>We are not considering post-quantum security. If the quantum computer becomes a materialized threat, the underlying cipher of Ethereum and other L1 chains would have been replaced, and this EIP will be outdated then (as the EC part of ECIES is also broken).</li> <li>The security level shall match that of the elliptic curve used by the underlying chains. It does not make much sense to use AES-256 to safeguard a secp256k1 private key but implementations could choose freely.</li> <li>That being said, a key might be used in multiple chains. So the security level shall cover the most demanding requirement and potential future developments.</li> </ol> <p>AES-128, AES-256, and ChaCha20 are provided.</p> <h3 id="randomness">Randomness</h3> <p><code>r</code> and <code>s</code> must be generated with a cryptographic secure random number generator (CSRNG).</p> <p><code>salt</code> could be random bytes generated the same way as <code>r</code> or <code>s</code>. <code>salt</code> could be in any length but the general suggestion is 12 or 16, which could be displayed as a QR code by the screen of some hardware wallet (so that another application could scan to read). If <code>salt</code> is not provided, this EIP uses the default value as <code>EIP-6051</code>.</p> <h3 id="out-of-band-data">Out of Band Data</h3> <p><code>oob</code> data is optional. When non-empty, its content is digits or an alpha-numeric string from the user. <em>Sender Application</em> may mandate <code>oob</code> from the user.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-11-15T00:00:00+00:00 2026-02-11T14:49:28+00:00 Abdelhamid Bakhtahttps://github.com/abdelhamidbakhta Eli Ben Sassonhttps://github.com/Elistark Avihu Levyhttps://github.com/avihu28 David Levit Gurevichhttps://github.com/DavidLevitGurevich https://wg-eips.ritovision.com/5988/

Add a precompiled contract which implements the hash function used in the Poseidon cryptographic hashing algorithm

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new precompiled contract which implements the hash function used in the Poseidon cryptographic hashing algorithm, for the purpose of allowing interoperability between the EVM and ZK / Validity rollups, as well as introducing more flexible cryptographic hash primitives to the EVM.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/5988/./assets/papers/poseidon_paper.pdf">Poseidon</a> is an arithmetic hash function that is designed to be efficient for Zero-Knowledge Proof Systems. Ethereum adopts a rollup centric roadmap and hence must adopt facilities for L2s to be able to communicate with the EVM in an optimal manner.</p> <p>ZK-Rollups have particular needs for cryptographic hash functions that can allow for efficient verification of proofs.</p> <p>The Poseidon hash function is a set of permutations over a prime field, which makes it particularly well-suited for the purpose of building efficient ZK / Validity rollups on Ethereum.</p> <p>Poseidon is one of the most efficient hashing algorithms that can be used in this context. Moreover it is compatible with all major proof systems (SNARKs, STARKs, Bulletproofs, etc...). This makes it a good candidate for a precompile that can be used by many different ZK-Rollups.</p> <p>An important point to note is that ZK rollups using Poseidon have chosen different sets of parameters, which makes it harder to build a single precompile for all of them.</p> <p>However, we can still build a generic precompile that supports arbitrary parameters, and allow the ZK rollups to choose the parameters they want to use.</p> <p>This is the approach that we have taken in this EIP.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLKNUM</code></td><td><code>TBD</code></td></tr> <tr><td><code>GAS_COST</code></td><td><code>TBD</code></td></tr> <tr><td><code>POSEIDON_PRECOMPILE_ADDRESS</code></td><td><code>0xA</code></td></tr> </tbody></table> <p>Here are the Poseidon parameters that the precompile will support:</p> <table><thead><tr><th>Parameter name</th><th>Description</th><th>Encoding size (in bytes)</th><th>Comments</th></tr></thead><tbody> <tr><td><code>p</code></td><td>Prime field modulus</td><td>32</td><td></td></tr> <tr><td><code>security_level</code></td><td>Security level measured in bits. Denoted <code>M</code> in the Poseidon paper</td><td>2</td><td></td></tr> <tr><td><code>alpha</code></td><td>Power of S-box</td><td>1</td><td></td></tr> <tr><td><code>input_rate</code></td><td>Size of input</td><td>2</td><td></td></tr> <tr><td><code>t</code></td><td>Size of the state</td><td>1</td><td></td></tr> <tr><td><code>full_round</code></td><td>Number of full rounds. Denoted as <code>R_F</code> in the Poseidon paper.</td><td>1</td><td></td></tr> <tr><td><code>partial_round</code></td><td>Number of partial rounds. Denoted as <code>R_P</code> in the Poseidon paper.</td><td>1</td><td></td></tr> <tr><td><code>input</code></td><td>Input to the hash function</td><td><code>input_rate</code> * 32</td><td></td></tr> </tbody></table> <p>The encoding of the precompile input is the following:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[32 bytes for p][2 bytes for security_level][1 byte for alpha][2 bytes for input_rate][1 byte for t][1 byte for full_round][1 byte for partial_round][input_rate * 32 bytes for input]</span></span></code></pre> <p>The precompile should compute the hash function as <a href="https://wg-eips.ritovision.com/5988/./assets/papers/poseidon_paper.pdf">specified in the Poseidon paper</a> and return hash output.</p> <!--### Example Usage in Solidity The precompile can be wrapped easily in Solidity to provide a more development-friendly interface to `poseidon_hash` function. ```solidity // TODO: Add solidity example ```--> <!--### Gas Costs ``` TODO: Fill gas costs section ```--> <h2 id="rationale">Rationale</h2> <p>TODO: Add rationale</p> <p>TODO: Add rationale for gas cost e.g. benchmark and computation cost estimation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There is very little risk of breaking backwards-compatibility with this EIP, the sole issue being if someone were to build a contract relying on the address at <code>0xPOSEIDON_PRECOMPILE_ADDRESS</code> being empty. The likelihood of this is low, and should specific instances arise, the address could be chosen to be any arbitrary value with negligible risk of collision.</p> <h2 id="test-cases">Test Cases</h2> <p>The Poseidon reference implementation contains test vectors that can be used to test the precompile. Those tests are available <a href="https://wg-eips.ritovision.com/5988/./assets/test/poseidon/test_vectors.txt">here</a>.</p> <!--## Reference Implementation TODO: Add initial Geth implementation--> <h2 id="security-considerations">Security Considerations</h2> <p>Quoting Vitalik Buterin from <code>Arithmetic hash based alternatives to KZG for proto-danksharding</code> thread on EthResearch:</p> <blockquote> <p>The Poseidon hash function was officially introduced in 2019. Since then it has seen considerable attempts at cryptanalysis and optimization. However, it is still very young compared to popular “traditional” hash functions (eg. SHA256 and Keccak), and its general approach of accepting a high level of algebraic structure to minimize constraint count is relatively untested. There are layer-2 systems live on the Ethereum network and other systems that already rely on these hashes for their security, and so far they have seen no bugs for this reason. Use of Poseidon in production is still somewhat “brave” compared to decades-old tried-and-tested hash functions, but this risk should be weighed against the risks of proposed alternatives (eg. pairings with trusted setups) and the risks associated with centralization that might come as a result of dependence on powerful provers that can prove SHA256.</p> </blockquote> <p>It is true that arithmetic hash functions are relatively untested compared to traditional hash functions. However, Poseidon has been thoroughly tested and is considered secure by multiple independent research groups and layers 2 systems are already using it in production (StarkWare, Polygon, Loopring) and also by other projects (e.g. Filecoin).</p> <p>Moreover, the impact of a potential vulnerability in the Poseidon hash function would be limited to the rollups that use it.</p> <p>We can see the same rationale for the KZG ceremony in the <a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>, arguing that the risk of a vulnerability in the KZG ceremony is limited to the rollups that use it.</p> <p>List of projects (non exhaustive) using Poseidon:</p> <ul> <li>StarkWare plans to use Poseidon as the main hash function for StarkNet, and to add a Poseidon built-in in Cairo.</li> <li>Filecoin employs POSEIDON for Merkle tree proofs with different arities and for two-value commitments.</li> <li>Dusk Network uses POSEIDON to build a Zcash-like protocol for securities trading.11 It also uses POSEIDON for encryption as described above.</li> <li>Sovrin uses POSEIDON for Merkle-tree based revocation.</li> <li>Loopring uses POSEIDON for private trading on Ethereum.</li> <li>Polygon uses Poseidon for Hermez ZK-EVM.</li> </ul> <p>In terms of security, the choice of parameters is important.</p> <h3 id="security-of-the-poseidon-parameters">Security of the Poseidon parameters</h3> <h4 id="choice-of-the-mds-matrix">Choice of the MDS matrix</h4> <p>The MDS matrix is a square matrix of size <code>t</code> * <code>t</code> that is used to mix the state.</p> <p>This matrix is used during the <code>MixLayer</code> phase of the Poseidon hash function.</p> <p>The matrix must be chosen s.t. no subspace trail with inactive/active S-boxes can be set up for more than <code>t -1</code> rounds.</p> <p>There are some efficient algorithms to detect weak MDS matrices.</p> <p>Those algorithms are described in the <a href="https://wg-eips.ritovision.com/5988/./assets/papers/proving_resistance_linear_layer.pdf">Proving Resistance Against Infinitely Long Subspace Trails: How to Choose the Linear Layer</a> paper.</p> <p>The process of the generation of the matrix should look like this, as recommended in the Poseidon paper:</p> <ol> <li>Generate a random matrix.</li> <li>Check if the matrix is secure using Algorithm 1, Algorithm 2, and Algorithm 3 provided <a href="https://wg-eips.ritovision.com/5988/./assets/papers/proving_resistance_linear_layer.pdf">Proving Resistance Against Infinitely Long Subspace Trails: How to Choose the Linear Layer</a> paper.</li> <li>If the matrix is not secure, go back to step 1.</li> </ol> <h3 id="papers-and-research-related-to-poseidon-security">Papers and research related to Poseidon security</h3> <ul> <li><a href="https://wg-eips.ritovision.com/5988/./assets/papers/poseidon_paper.pdf">Poseidon: A New Hash Function for Zero-Knowledge Proof Systems</a></li> <li><a href="https://wg-eips.ritovision.com/5988/./assets/papers/security_poseidon_non_binary_differential_attacks.pdf">Security of the Poseidon Hash Function Against Non-Binary Differential and Linear Attacks</a></li> <li><a href="https://wg-eips.ritovision.com/5988/./assets/papers/report_security_stark_friendly_hash.pdf">Report on the Security of STARK-friendly Hash Functions</a></li> <li><a href="https://wg-eips.ritovision.com/5988/./assets/papers/practical_algebraic_attacks.pdf">Practical Algebraic Attacks against some Arithmetization-oriented Hash Functions</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-11-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Simon Brownhttps://github.com/orbmis https://wg-eips.ritovision.com/5902/

Format that allows contracts to semi-autonoumously respond to events emitted by other contracts

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a standard for creating "hooks" that allow a smart contract function to be called automatically in response to a trigger fired by another contract, by using a public relayer network as a messaging bus.</p> <p>While there are many similar solutions in existence already, this proposal describes a simple yet powerful primitive that can be employed by many applications in an open, permissionless and decentralized manner.</p> <p>It relies on two interfaces, one for a publisher contract and one for a subscriber contract. The publisher contract emits events that are picked up by "relayers", who are independent entities that subscribe to "hook" events on publisher contracts, and call a function on the respective subscriber contracts, whenever a hook event is fired by the publisher contracts. Whenever a relayer calls the respective subscriber's contract with the details of the hook event emitted by the publisher contract, they are paid a fee by the subscriber. Both the publisher and subscriber contracts are registered in a central registry smart contract that relayers can use to discover hooks.</p> <h2 id="motivation">Motivation</h2> <p>There exists a number of use cases that require some off-chain party to monitor the chain and respond to on-chain events by broadcasting a transaction. Such cases usually require some off-chain process to run alongside an Ethereum node in order to subscribe to events emitted by smart contract, and then execute some logic in response and subsequently broadcast a transaction to the network. This requires an Ethereum node and an open websocket connection to some long-running process that may only be used infrequently, resulting in a sub-optimal use of resources.</p> <p>This proposal would allow for a smart contract to contain the logic it needs to respond to events without having to store that logic in some off-chain process. The smart contract can subscribe to events fired by other smart contracts and would only execute the required logic when it is needed. This method would suit any contract logic that does not require off-chain computation, but usually requires an off-chain process to monitor the chain state. With this approach, subscribers do not need their own dedicated off-chain processes for monitoring and responding to contract events. Instead, a single incentivized relayer can subscribe to many different events on behalf of multiple different subscriber contracts.</p> <p>Examples of use cases that would benefit from this scheme include:</p> <h3 id="collateralised-lending-protocols">Collateralised Lending Protocols</h3> <p>Collateralised lending protocols or stablecoins can emit events whenever they receive price oracle updates, which would allow borrowers to automatically "top-up" their open positions to avoid liquidation.</p> <p>For example, Maker uses the "medianizer" smart contract which maintains a whitelist of price feed contracts which are allowed to post price updates. Every time a new price update is received, the median of all feed prices is re-computed and the medianized value is updated. In this case, the medianizer smart contract could fire a hook event that would allow subscriber contracts to decide to re-collateralize their CDPs.</p> <h3 id="automated-market-makers">Automated Market Makers</h3> <p>AMM liquidity pools could fire a hook event whenever liquidity is added or removed. This could allow a subscriber smart contracts to add or remove liquidity once the total pool liquidity reaches a certain point.</p> <p>AMMs can fire a hook whenever there is a trade within a trading pair, emitting the time-weighted-price-oracle update via an hook event. Subscribers can use this to create an automated Limit-Order-Book type contract to buy/sell tokens once an asset's spot price breaches a pre-specified threshold.</p> <h3 id="dao-voting">DAO Voting</h3> <p>Hook events can be emitted by a DAO governance contract to signal that a proposal has been published, voted on, carried or vetoed, and would allow any subscriber contract to automatically respond accordingly. For example, to execute some smart contract function whenever a specific proposal has passed, such as an approval for payment of funds.</p> <h3 id="scheduled-function-calls">Scheduled Function Calls</h3> <p>A scheduler service can be created whereby a subscriber can register for a scheduled funtion call, this could be done using unix cron format and the service can fire events from a smart contract on separate threads. Subscriber contracts can subscriber to the respective threads in order to subscribe to certain schedules (e.g. daily, weekly, hourly etc.), and could even register customer cron schedules.</p> <h3 id="recurring-payments">Recurring Payments</h3> <p>A service provider can fire Hook events that will allow subscriber contracts to automatically pay their service fees on a regular schedule. Once the subscriber contracts receive a hook event, they can call a function on the service provider's contract to transfer funds due.</p> <h3 id="coordination-via-delegation">Coordination via Delegation</h3> <p>Hook event payloads can contain any arbitrary data, this means you can use things like the Delegatable framework to sign off-chain delegations which can faciliate a chain of authorized entities to publish valid Hook events. You can also use things like BLS threshold signatures, to facilitate multiple off-chain publishers to authorize the firing of a Hook.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="registering-a-publisher">Registering a Publisher</h3> <p>Both the publisher and subscriber contracts <strong>MUST</strong> register in a specific register contract, similarly to how smart contracts register an interface in the <a href="https://wg-eips.ritovision.com/1820/">ERC-1820</a> contract. The registry contract <strong>MUST</strong> must use a deterministic deployment mechanism, i.e. using a factory contract and a specific salt.</p> <p>To register a publisher contract's hook, the <code>registerHook</code> function <strong>MUST</strong> be called on the registry contract. The parameters that need to be supplied are:</p> <ul> <li>(address) The publisher contract address</li> <li>(uint256) The thread id that the hooks events will reference (a single contract can fire hook events with any number of threads, subscribers can choose which threads to subscribe to)</li> <li>(bytes) The public key associated with the hook events (optional)</li> </ul> <p>When the <code>registerHook</code> function is called on the registry contract, the registry contract <strong>MUST</strong> make a downstream call to the publisher contract address, by calling the publisher contract's <code>verifyEventHookRegistration</code> function, with the same arguments as passed to the <code>registerHook</code> function on the registry contract. The <code>verifyEventHookRegistration</code> function in the publisher contract <strong>MUST</strong> return true in order to indicate that the contract will allow itself to be added to the registry as a publisher. The registry contract <strong>MUST</strong> emit a <code>HookRegistered</code> event to indicate that a new publisher contract has been added.</p> <h3 id="updating-a-hook">Updating a Hook</h3> <p>Publishers may want to update the details associated with a Hook event, or indeed remove support for a Hook event completely. The registry contract <strong>MUST</strong> implement the <code>updatePublisher</code> function to allow for an existing publisher contract to be updated in the registry. The registry contract <strong>MUST</strong> emit a <code>PublisherUpdated</code> event to indicate that the publisher contract was updated.</p> <h3 id="removing-a-hook">Removing a Hook</h3> <p>To remove a previously registered Hook, the function <code>removeHook</code> function must be called on the Registry contract, with the same parameters as the <code>updateHook</code> function. The registry contract <strong>MUST</strong> emit a <code>HookRemoved</code> event with the same parameters as passed to the 'removeHook' function and the <code>msg.sender</code> value.</p> <h3 id="registering-a-subscriber">Registering a Subscriber</h3> <p>To register a subscriber to a hook, the <code>registerSubscriber</code> function <strong>MUST</strong> be called on the registry contract with the following parameters:</p> <ul> <li>(address) The publisher contract address</li> <li>(bytes32) The subscriber contract address</li> <li>(uint256) The thread id to subscribe to</li> <li>(uint256) The fee that the subscriber is willing to pay to get updates</li> <li>(uint256) The maximum gas that the subscriber will allow for updates, to prevent griefing attacks, or 0 to indicate no maximum</li> <li>(uint256) The maximum gas price that the subscriber is willing to repay the relayer on top of the fee, or 0 to indicate no rebates</li> <li>(uint256) The chain id that the subscriber wants updates from</li> <li>(address) The address of the token that the fee will be paid in or 0x0 for the chain's native asset (e.g. ETH, MATIC etc.)</li> </ul> <p>The subscriber contract <strong>MAY</strong> implement gas refunds on top of the fixed fee per update. Where a subscriber chooses to do this, then they <strong>SHOULD</strong> specify the <code>maximum gas</code> and <code>maximum gas price</code> parameters in order to protect themselves from griefing attacks. This is so that a malicious or careless relay doesn't set an exorbitantly high gas price and ends up draining the subscriber contracts. Subscriber contracts can otherwise choose to set a fee that is estimated to be sufficiently high to cover gas fees.</p> <p>Note that while the chain id and the token address were not included in the original version of the spec, the simple addition of these two parameters allows for leveraging the relayers for cross chain messages, should the subscriber wish to do this, and also allows for paying relayer fees in various tokens.</p> <h3 id="updating-a-subscription">Updating a Subscription</h3> <p>To update a subscription, the <code>updateSubscriber</code> function <strong>MUST</strong> be called with the same set of parameters as the <code>registerSubscriber</code> function. This might be done in order to cancel a subscription, or to change the subscription fee. Note that the <code>updateSubscriber</code> function <strong>MUST</strong> maintain the same <code>msg.sender</code> that the <code>registerSubscriber</code> function was called with.</p> <h3 id="removing-a-subscription">Removing a Subscription</h3> <p>To remove a previously registered subscription, the function <code>removeSubscriber</code> <strong>MUST</strong> be called on the Registry contract, with the same parameters as the <code>updateSubscriber</code> function, but without the <code>fee</code> parameter (i.e. publisher and subscriber contract addresses and thread id). The fee will be subsequently set to 0 to indicate that the subscriber no longer wants updates for this subscription. The registry contract <strong>MUST</strong> emit a <code>SubscriptionRemoved</code> event with publisher contract address, subscriber contract address and the thread id as topics.</p> <h3 id="publishing-an-event">Publishing an Event</h3> <p>A publisher contract <strong>SHOULD</strong> emit a hook event from at least one function. The emitted event <strong>MUST</strong> be called <code>Hook</code> and <strong>MUST</strong> contain the following parameters:</p> <ul> <li>uint256 (indexed) - threadId</li> <li>uint256 (indexed) - nonce</li> <li>bytes32 digest</li> <li>bytes payload</li> <li>bytes32 checksum</li> </ul> <p>The <code>nonce</code> value <strong>MUST</strong> be incremented every time a Hook event is fired by a publisher contract. Every Hook event <strong>MUST</strong> have a unique <code>nonce</code> value. The <code>nonce</code> property is initiated to 1, but the first Hook event ever fired <strong>MUST</strong> be set to 2. This is to prevent ambiguity between an uninitiated nonce variable and a nonce variable that is explicitly initiated to zero.</p> <p>The <code>digest</code> parameter of the event <strong>MUST</strong> be the keccak256 hash of the payload, and the <code>checksum</code> <strong>MUST</strong> be the keccak256 hash of the concatenation of the digest with the current blockheight, e.g.:</p> <p><code>bytes32 checksum = keccak256(abi.encodePacked(digest, block.number));</code></p> <p>The <code>Hook</code> event can be triggered by a function call from any EOA or external contract. This allows the payload to be created dynamically within the publisher contract. The subscriber contract <strong>SHOULD</strong> call the <code>verifyEventHook</code> function on the publisher contract to verify that the received Hook payload is valid.</p> <p>The payload <strong>MAY</strong> be passed to the function firing the Hook event instead of being generated within the publisher contract itself, but if a signature is provided it <strong>MUST</strong> sign a hash of the payload, and it is strongly recommended to use the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> standard, and to follow the data structure outlined at the end of this proposal. This signature <strong>SHOULD</strong> be verified by the subscribers to ensure they are getting authentic events. The signature <strong>MUST</strong> correspond to the public key that was registered with the event. With this approach, the signature <strong>SHOULD</strong> be placed at the start of the payload (e.g. bytes 0 to 65 for an ECDSA signature with r, s, v properties). This method of verification can be used for cross-chain Hook events, where subscribers will not be able to call the <code>verifyHookEvent</code> of the publisher contract on another chain.</p> <p>The payload <strong>MUST</strong> be passed to subscribers as a byte array in calldata. The subscriber smart contract <strong>SHOULD</strong> convert the byte array into the required data type. For example, if the payload is a snark proof, the publisher would need to serialize the variables into a byte array, and the subscriber smart contract would need to deserialize it on the other end, e.g.:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>struct SnarkProof {</span></span> <span class="giallo-l"><span> uint256[2] a;</span></span> <span class="giallo-l"><span> uint256[2][2] b;</span></span> <span class="giallo-l"><span> uint256[2] c;</span></span> <span class="giallo-l"><span> uint256[1] input;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>SnarkProof memory zkproof = abi.decode(payload, SnarkProof);</span></span></code></pre><h3 id="relayers">Relayers</h3> <p>Relayers are independent parties that listen to <code>Hook</code> events on publisher smart contracts. Relayers retrieve a list of subscribers for different hooks from the registry, and listen for hook events being fired on the publisher contracts. Once a hook event has been fired by a publisher smart contract, relayers can decide to relay the hook event's payload to the subscriber contracts by broadcasting a transaction that executes the subscriber contract's <code>verifyHook</code> function. Relayers are incentivised to do this because it is expected that the subscriber contract will remunerate them with ETH, or some other asset.</p> <p>Relayers <strong>SHOULD</strong> simulate the transaction locally before broadcasting it to make sure that the subscriber contract has sufficient balance for payment of the fee. This requires subscriber contracts to maintain a balance of ETH (or some asset) in order to provision payment of relayer fees. A subscriber contract <strong>MAY</strong> decide to revert a transaction based on some logic, which subsequently allows the subscriber contract to conditionally respond to events, depending on the data in the payload. In this case the relayer will simulate the transaction locally and determine not to relay the Hook event to the subscriber contract.</p> <h3 id="verifying-a-hook-event">Verifying a Hook Event</h3> <p>The <code>verifyHook</code> function of the subscriber contracts <strong>SHOULD</strong> include logic to ensure that they are retrieving authentic events. In the case where the Hook event contains a signature, then subscriber contracts <strong>SHOULD</strong> create a hash of the required parameters, and <strong>SHOULD</strong> verify that the signature in the hook event is valid against the derived hash and the publisher's public key (see the reference implemenetation for an example). The hook function <strong>SHOULD</strong> also verify the nonce of the hook event and record it internally, in order to prevent replay attacks.</p> <p>For Hook events without signatures, the subscriber contract <strong>SHOULD</strong> call the <code>verifyHookEvent</code> on the publisher contract in order to verify that the hook event is valid. The publisher smart contract <strong>MUST</strong> implement the <code>verifyHookEvent</code>, which accepts the hash of the payload, the thread id, the nonce, and the block height associated with the Hook event, and returns a boolean value to indicate the Hook event's authenticity.</p> <h3 id="interfaces">Interfaces</h3> <p>IRegistry.sol</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment">/ @title IRegistry</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment">/ @dev Implements the registry contract</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Registers a new hook event by a publisher</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param publisherContract The address of the publisher contract</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The id of the thread these hook events will be fired on</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param signingKey The public key that corresponds to the signature of externally generated payloads (optional)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @return Returns true if the hook is successfully registered</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerHook</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> publisherContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> signingKey</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Verifies a hook with the publisher smart contract before adding it to the registry</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param publisherAddress The address of the publisher contract</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The id of the thread these hook events will be fired on</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param signingKey The public key used to verify the hook signatures</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @return Returns true if the hook is successfully verified</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyHook</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> publisherAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> signingKey</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Update a previously registered hook event</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Can be used to transfer hook authorization to a new address</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev To remove a hook, transfer it to the burn address</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param publisherContract The address of the publisher contract</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The id of the thread these hook events will be fired on</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param signingKey The public key used to verify the hook signatures</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @return Returns true if the hook is successfully updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateHook</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> publisherContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> signingKey</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Remove a previously registered hook event</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param publisherContract The address of the publisher contract</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The id of the thread these hook events will be fired on</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param signingKey The public key used to verify the hook signatures</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @return Returns true if the hook is successfully updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeHook</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> publisherContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> signingKey</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Registers a subscriber to a hook event</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param publisherContract The address of the publisher contract</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param subscriberContract The address of the contract subscribing to the event hooks</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The id of the thread these hook events will be fired on</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param fee The fee that the subscriber contract will pay the relayer</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param maxGas The maximum gas that the subscriber allow to spend, to prevent griefing attacks</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param maxGasPrice The maximum gas price that the subscriber is willing to rebate</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param chainId The chain id that the subscriber wants updates on</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param feeToken The address of the token that the fee will be paid in or 0x0 for the chain&#39;s native asset (e.g. ETH)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @return Returns true if the subscriber is successfully registered</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerSubscriber</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> publisherContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> subscriberContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> fee</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> maxGas</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> maxGasPrice</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> chainId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> feeToken</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Registers a subscriber to a hook event</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param publisherContract The address of the publisher contract</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param subscriberContract The address of the contract subscribing to the event hooks</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The id of the thread these hook events will be fired on</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param fee The fee that the subscriber contract will pay the relayer</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @return Returns true if the subscriber is successfully updated</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateSubscriber</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> publisherContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> subscriberContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> fee</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Removes a subscription to a hook event</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param publisherContract The address of the publisher contract</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param subscriberContract The address of the contract subscribing to the event hooks</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The id of the thread these hook events will be fired on</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @return Returns true if the subscriber is subscription removed</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeSubscription</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> publisherContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> subscriberContract</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>IPublisher.sol</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment">/ @title IPublisher</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment">/ @dev Implements a publisher contract</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IPublisher</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Example of a function that fires a hook event when it is called</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param payload The actual payload of the hook event</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param digest Hash of the hook event payload that was signed</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The thread number to fire the hook event on</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fireHook</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> payload</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> bytes32</span><span class="z-variable"> digest</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Adds / updates a new hook event internally</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The thread id of the hook</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param signingKey The public key associated with the private key that signs the hook events</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addHook</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> threadId</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> signingKey</span><span>)</span><span class="z-entity z-name"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Called by the registry contract when registering a hook, used to verify the hook is valid before adding</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The thread id of the hook</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param signingKey The public key associated with the private key that signs the hook events</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @return Returns true if the hook is valid and is ok to add to the registry</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyEventHookRegistration</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> signingKey</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Returns true if the specified hook is valid</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param payloadhash The hash of the hook&#39;s data payload</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The thread id of the hook</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param nonce The nonce of the current thread</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param blockheight The blockheight that the hook was fired at</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @return Returns true if the specified hook is valid</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyEventHook</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> bytes32</span><span class="z-variable"> payloadhash</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> blockheight</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>ISubscriber.sol</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment">/ @title ISubscriber</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment">/ @dev Implements a subscriber contract</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ISubscriber</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @dev Example of a function that is called when a hook is fired by a publisher</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param publisher The address of the publisher contract in order to verify hook event with</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param payload Hash of the hook event payload that was signed</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param threadId The id of the thread this hook was fired on</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param nonce Unique nonce of this hook</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">/ @param blockheight The block height at which the hook event was fired</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verifyHook</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> address</span><span class="z-variable"> publisher</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> payload</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> threadId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> uint256</span><span class="z-variable"> blockheight</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <p>The rationale for this design is that it allows smart contract developers to write contract logic that listens and responds to events fired in other smart contracts, without requiring them to run some dedicated off-chain process to achieve this. This best suits any simple smart contract logic that runs relatively infrequently in response to events in other contracts.</p> <p>This improves on the existing solutions to achieve a pub/sub design pattern. To elaborate: a number of service providers currently offer "webhooks" as a way to subscribe to events emitted by smart contracts, by having some API endpoint called when the events are emitted, or alternatively offer some serverless feature that can be triggered by some smart contract event. This approach works very well, but it does require that some API endpoint or serverless function be always available, which may require some dedicated server / process, which in turn will need to have some private key, and some amount of ETH in order to re-broadcast transactions, no to mention the requirement to maintain an account with some third party provider.</p> <p>This approach offers a more suitable alternative for when an "always-on" server instance is not desirable, e.g. in the case that it will be called infrequently.</p> <p>This proposal incorporates a decentralized market-driven relay network, and this decision is based on the fact that this is a highly scalable approach. Conversely, it is possible to implement this functionality without resorting to a market-driven approach, by simply defining a standard for contracts to allow other contracts to subscribe directly. That approach is conceptually simpler, but has its drawbacks, in so far as it requires a publisher contract to record subscribers in its own state, creating an overhead for data management, upgradeability etc. That approach would also require the publisher to call the <code>verifyHook</code> function on each subscriber contract, which will incur potentially significant gas costs for the publisher contract.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="griefing-attacks">Griefing Attacks</h3> <p>It is imperative that subscriber contracts trust the publisher contracts not to fire events that hold no intrinsic interest or value for them, as it is possible that malicious publisher contracts can publish a large number of events that will in turn drain the ETH from the subscriber contracts.</p> <h3 id="front-running-attacks">Front-running Attacks</h3> <p>It is advised not to rely on signatures alone to validate Hook events. It is important for publishers and subscribers of hooks to be aware that it is possible for a relayer to relay hook events before they are published, by examining the publisher's transaction in the mempool before it actually executes in the publisher's smart contract. The normal flow is for a "trigger" transaction to call a function in the publisher smart contract, which in turn fires an event which is then picked up by relayers. Competitive relayers will observe that it is possible to pluck the signature and payload from the trigger transaction in the public mempool and simply relay it to subscriber contracts before the trigger transaction has been actually included in a block. In fact, it is possible that the subscriber contracts process the event before the trigger transaction is processed, based purely on gas fee dynamics. This can mitigated against by subscriber contracts calling the <code>verifyEventHook</code> function on the publisher contract when they receive a Hook event.</p> <p>Another risk from front-running affects relayers, whereby the relayer's transactions to the subscriber contracts can be front-run by generalized MEV searchers in the mempool. It is likely that this sort of MEV capture will occur in the public mempool, and therefore it is advised that relayers use private channels to block builders to mitigate against this issue.</p> <h3 id="relayer-competition">Relayer Competition</h3> <p>By broadcasting transactions to a segregated mempool, relayers protect themselves from front-running by generalized MEV bots, but their transactions can still fail due to competition from other relayers. If two or more relayers decide to start relaying hook events from the same publisher to the same subscribers, then the relay transactions with the highest gas price will be executed before the others. This will result in the other relayer's transactions potentially failing on-chain, by being included later in the same block. For now, there are certain transaction optimization services that will prevent transactions from failing on-chain, which will offer a solution to this problem, though this is out-of-scope for this document.</p> <h3 id="optimal-fees">Optimal Fees</h3> <p>The fees that are paid to relayers are at the discretion of the subscribers, but it can be non-trivial to set fees to their optimal level, especially when considering volatile gas fees and competition between relayers. This will result in subscribers setting fees to a perceived "safe" level, which they are confident will incentivize relayers to relay Hook events. This will inevitably lead to poor price discovery and subscribers over-paying for updates.</p> <p>The best way to solve this problem is through an auction mechanism that would allow relayers to bid against each other for the right to relay a transaction, which would guarantee that subscribers are paying the optimal price for their updates. Describing an auction mechanism that would satisfy this requirements is out of scope for this proposal, but there exists proposals for general purpose auction mechanisms that can faciliate this without introducing undue latency. One exampe of such as proposal is SUAVE from Flashbots, and there will likely be several others in time.</p> <h3 id="without-an-auction">Without an Auction</h3> <p>In order to cultivate and maintain a reliable relayer market without the use of an auction mechanism, subscriber contracts would need to implement logic to either rebate any gas fees up to a specified limit, (while still allowing for execution of hook updates under normal conditions).</p> <p>Another approach would be to implement a logical condition that checks the gas price of the transaction that is calling the <code>verifyHook</code> function, to ensure that the gas price does not effectively reduce the fee to zero. This would require that the subscriber smart contract has some knowledge of the approximate gas used by it's <code>verifyHook</code> function, and to check that the condition <code>minFee &gt;= fee - (gasPrice * gasUsed)</code> is true. This will mitigate against competitive bidding that would drive the <em>effective</em> relayer fee to zero, by ensuring that there is some minimum fee below which the effective fee is not allowed to drop. This would mean that the highest gas price that can be paid before the transaction reverts is <code>fee - minFee + ε</code> where <code>ε ~= 1 gwei</code>. This will require careful estimation of the gas cost of the <code>verifyHook</code> function and an awareness that the gas used may change over time as the contract's state changes. The key insight with this approach is that competition between relayers will result in the fee that the subscribers pay always being the maximum, which is why the use of an auction mechanism is preferable.</p> <h3 id="relayer-transaction-batching">Relayer Transaction Batching</h3> <p>Another important consideration is with batching of Hook events. Relayers are logically incentivized to batch Hook updates to save on gas, seeing as gas savings amount to 21,000 * n where n is the number of hooks being processed in a block by a single relayer. If a relayer decides to batch multiple Hook event updates to various subscriber contracts into a single transaction, via a multi-call proxy contract, then they increase the risk of the entire batch failing on-chain if even one of the transactions in the batch fails on-chain. For example, if relayer A batches x number of Hook updates, and relayer B batches y number of Hook updates, it is possible that relayer A's batch is included in the same block in front of relayer B's batch, and if both batches contain at least one duplicate, (i.e. the same Hook event to the same subscriber), then this will cause relayer B's batch transaction to revert on-chain. This is an important consideration for relayers, and suggests that relayers should have access to some sort of bundle simulation service to identify conflicting transactions before they occur.</p> <h3 id="replay-attacks">Replay Attacks</h3> <p>When using signature verification, it is advised to use the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> standard in order to prevent cross network replay attacks, where the same contract deployed on more than one network can have its hook events pushed to subscribers on other networks, e.g. a publisher contract on Polygon can fire a hook event that could be relayed to a subscriber contract on Gnosis Chain. Whereas the keys used to sign the hook events should ideally be unique, in reality this may not always be the case.</p> <p>For this reason, it is recommended to use <a href="https://wg-eips.ritovision.com/712/">ERC-721</a> Typed Data Signatures. In this case the process that initiates the hook should create the signature according to the following data structure:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> domain</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span> {</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chainId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">verifyingContract</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">salt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bytes32</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span></span> <span class="giallo-l"><span>]</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> hook</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span> {</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">payload</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nonce</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">blockheight</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span> type</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">threadId</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span>]</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> domainData</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> name</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Name of Publisher Dapp</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> version</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> chainId</span><span>:</span><span class="z-entity z-name"> parseInt</span><span>(</span><span class="z-variable z-other">web3</span><span>.</span><span class="z-variable z-other">version</span><span>.</span><span class="z-variable z-other">network</span><span>,</span><span class="z-constant"> 10</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> verifyingContract</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x123456789abcedf....publisher contract address</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> salt</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x123456789abcedf....random hash unique to publisher contract</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> message</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> payload</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bytes array serialized payload</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-variable z-other"> nonce</span><span>: </span><span class="z-constant">1</span><span>,</span></span> <span class="giallo-l"><span> blockheight</span><span>:</span><span class="z-constant"> 999999</span><span>,</span></span> <span class="giallo-l"><span> threadId</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> eip712TypedData</span><span class="z-keyword"> =</span><span> {</span></span> <span class="giallo-l"><span> types</span><span>:</span><span> {</span></span> <span class="giallo-l"><span> EIP712Domain</span><span>:</span><span class="z-variable z-other"> domain</span><span>,</span></span> <span class="giallo-l"><span> Hook</span><span>:</span><span class="z-variable z-other"> hook</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> domain</span><span>:</span><span class="z-variable z-other"> domainData</span><span>,</span></span> <span class="giallo-l"><span> primaryType</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Hook</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> message</span><span>:</span><span class="z-variable z-other"> message</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note: please refer to the unit tests in the reference implmenetation for an example of how a hook event should be constructed properly by the publisher.</p> <p>Replay attacks can also occur on the same network that the event hook was fired, by simply re-broadcasting an event hook that was already broadcast previously. For this reason, subscriber contracts should check that a nonce is included in the event hook being received, and record the nonce in the contract's state. If the hook nonce is not valid, or has already been recorded, the transaction should revert.</p> <h3 id="cross-chain-messaging">Cross-chain Messaging</h3> <p>There is also the possibility to leverage the <code>chainId</code> for more than preventing replay attacks, but also for accepting messages from other chains. In this use-case the subscriber contracts should register on the same chain that the subscriber contract is deployed on, and should set the <code>chainId</code> to the chain it wants to receive hook events from.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> 2022-10-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Paul Edgehttps://github.com/genkifs https://wg-eips.ritovision.com/5850/

Store real and imaginary parts of complex numbers in the least significant and most significant 16 bytes respectively of a `bytes32` type.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a natural way for complex numbers to be stored in and retrieved from the <code>bytes32</code> data-type. It splits the storage space exactly in half and, most importantly, assigns the real number part to the least significant 16 bytes and the imaginary number part to the most significant 16 bytes.</p> <h2 id="motivation">Motivation</h2> <p>Complex numbers are an essential tool for many mathematical and scientific calculations. For example, Fourier Transforms, Characteristic functions, AC Circuits and Navier-Stokes equations all require the concept.</p> <p>Complex numbers can be represented in many different forms (polynomial, cartesian, polar, exponential). The EIP creates a standard that can accommodate cartesian, polar and exponential formats with example code given for the Cartesian representation, where a complex number is just the pair of real numbers which gives the real and imaginary co-ordinates of the complex number. Equal storage capacity is assigned to both components and the order they appear is explicitly defined.</p> <p>Packing complex numbers into a single <code>bytes32</code> data object halves storage costs and creates a more natural code object that can be passed around the solidity ecosystem. Existing code may not need to be rewritten for complex numbers. For example, mappings by <code>bytes32</code> are common and indexing in the 2D complex plane may improve code legibility.</p> <p>Decimal numbers, either fix or floating, are not yet fully supported by Solidity so enforcing similar standards for complex versions is premature. It can be suggested that fixed point methods such as prb-math be used with 18 decimal places, or floating point methods like abdk. However, it should be noted that this EIP supports any decimal number representation so long as it fits inside the 16 bytes space.</p> <h2 id="specification">Specification</h2> <p>A complex number would be defined as <code>bytes32</code> and a cartesian representation would be initialized with the <code>cnNew</code> function and converted back with <code>RealIm</code>, both given below.</p> <p>To create the complex number one would use</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> cnNew</span><span>(</span><span class="z-support">int128</span><span class="z-variable z-parameter z-function"> _Real</span><span>,</span><span class="z-support"> int128</span><span class="z-variable z-parameter z-function"> _Imag</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Imag32 </span><span class="z-keyword">=</span><span class="z-support"> bytes16</span><span>(</span><span class="z-support">uint128</span><span>(</span><span>_Imag</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Real32 </span><span class="z-keyword">=</span><span class="z-support"> bytes16</span><span>(</span><span class="z-support">uint128</span><span>(</span><span>_Real</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>Real32</span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 128</span><span>)</span><span class="z-keyword"> |</span><span> Imag32</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>and to convert back</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> RealIm</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _cn</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">int128</span><span class="z-storage z-type"> Real</span><span>,</span><span class="z-support"> int128</span><span class="z-storage z-type"> Imag</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> bytes16</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-storage z-type"> memory</span><span> tmp </span><span class="z-keyword">=</span><span> [</span><span class="z-support">bytes16</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-constant"> 0</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span>tmp</span><span>,</span><span> _cn</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> mstore</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>tmp</span><span>,</span><span class="z-constant"> 16</span><span>)</span><span>,</span><span> _cn</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> Imag</span><span class="z-keyword">=</span><span class="z-support">int128</span><span>(</span><span class="z-support">uint128</span><span>(</span><span>tmp</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> Real</span><span class="z-keyword">=</span><span class="z-support">int128</span><span>(</span><span class="z-support">uint128</span><span>(</span><span>tmp</span><span>[</span><span class="z-constant">1</span><span>]</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>An EIP is required as this proposal defines a complex numbers storage/type standard for multiple apps to use.</p> <p>This EIP proposes to package both the real and imaginary within one existing data type, <code>bytes32</code>. This allows compact storage without the need for structures and facilitates easy library implementations. The <code>bytes32</code> would remain available for existing, non-complex number uses. Only the split and position of the real &amp; imaginary parts is defined in this EIP. Manipulation of complex numbers (addition, multiplication etc.), number of decimal places and other such topics are left for other EIP discussions. This keeps this EIP more focused and therefore more likely to succeed.</p> <p>Defining real numbers in the 16 least-significant bytes allows direct conversion from <code>uint128</code> to <code>bytes32</code> for positive integers less than 2**127.<br /> Direct conversion back from <code>bytes32</code> -&gt; <code>uint</code> -&gt; <code>int</code> are not recommended as the complex number may contain imaginary parts and/or the real part may be negative. It is better to always use <code>RealIm</code> for separating the complex part.</p> <p>Libraries for complex number manipulation can be implemented with the <code>Using Complex for bytes32</code> syntax where <code>Complex</code> would be the name of the library.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There is no impact on other uses of the <code>bytes32</code> datatype.</p> <h2 id="security-considerations">Security Considerations</h2> <p>If complex numbers are manipulated in <code>bytes32</code> form then overflow checks must be performed manually during the manipulation.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-10-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 zlacehttps://github.com/zlace0x zhongfuhttps://github.com/zhongfu edison0xyzhttps://github.com/edison0xyz https://wg-eips.ritovision.com/5827/

Extension to enable automatic renewals on allowance approvals

<h2 id="abstract">Abstract</h2> <p>This extension adds a renewable allowance mechanism to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> allowances, in which a <code>recoveryRate</code> defines the amount of token per second that the allowance regains towards the initial maximum approval <code>amount</code>.</p> <h2 id="motivation">Motivation</h2> <p>Currently, ERC-20 tokens support allowances, with which token owners can allow a spender to spend a certain amount of tokens on their behalf. However, this is not ideal in circumstances involving recurring payments (e.g. subscriptions, salaries, recurring direct-cost-averaging purchases).</p> <p>Many existing DApps circumvent this limitation by requesting that users grant a large or unlimited allowance. This presents a security risk as malicious DApps can drain users' accounts up to the allowance granted, and users may not be aware of the implications of granting allowances.</p> <p>An auto-renewable allowance enables many traditional financial concepts like credit and debit limits. An account owner can specify a spending limit, and limit the amount charged to the account based on an allowance that recovers over time.</p> <h2 id="specification">Specification</h2> <p>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> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5827</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC20, ERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x93cd7af6.</span></span> <span class="giallo-l"><span class="z-comment"> * 0x93cd7af6 ===</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;approveRenewable(address,uint256,uint256)&#39;)) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;renewableAllowance(address,address)&#39;)) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;approve(address,uint256)&#39;) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;transferFrom(address,address,uint256)&#39;) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;allowance(address,address)&#39;) ^</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Thrown when the available allowance is less than the transfer amount.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> available</span><span class="z-comment"> allowance available; 0 if unset</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> InsufficientRenewableAllowance</span><span>(</span><span class="z-support">uint256</span><span> available</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Emitted when any allowance is set.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST be emitted even if a non-renewable allowance is set; if so, the</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `_recoveryRate` MUST be 0.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> owner of token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _spender</span><span class="z-comment"> allowed spender of token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _value</span><span class="z-comment"> initial and maximum allowance granted to spender</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _recoveryRate</span><span class="z-comment"> recovery amount per second</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RenewableApproval</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _spender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _recoveryRate</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Grants an allowance of `_value` to `_spender` initially, which recovers over time </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> at a rate of `_recoveryRate` up to a limit of `_value`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> SHOULD cause `allowance(address _owner, address _spender)` to return `_value`, </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> SHOULD throw when `_recoveryRate` is larger than `_value`, and MUST emit a </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `RenewableApproval` event.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _spender</span><span class="z-comment"> allowed spender of token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _value</span><span class="z-comment"> initial and maximum allowance granted to spender</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _recoveryRate</span><span class="z-comment"> recovery amount per second</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approveRenewable</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _recoveryRate</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns approved max amount and recovery rate of allowance granted to `_spender` </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> by `_owner`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `amount` MUST also be the initial approval amount when a non-renewable allowance </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> has been granted, e.g. with `approve(address _spender, uint256 _value)`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> owner of token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _spender</span><span class="z-comment"> allowed spender of token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> amount</span><span class="z-comment"> initial and maximum allowance granted to spender</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> recoveryRate</span><span class="z-comment"> recovery amount per second</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> renewableAllowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> recoveryRate</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Overridden ERC-20 functions</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Grants a (non-increasing) allowance of _value to _spender and clears any existing </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> renewable allowance.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST clear set `_recoveryRate` to 0 on the corresponding renewable allowance, if </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> any.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _spender</span><span class="z-comment"> allowed spender of token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _value</span><span class="z-comment"> allowance granted to spender</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Moves `amount` tokens from `from` to `to` using the caller&#39;s allowance.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> When deducting `amount` from the caller&#39;s allowance, the allowance amount used </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> SHOULD include the amount recovered since the last transfer, but MUST NOT exceed </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> the maximum allowed amount returned by `renewableAllowance(address _owner, address </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> _spender)`. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> SHOULD also throw `InsufficientRenewableAllowance` when the allowance is </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> insufficient.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> from</span><span class="z-comment"> token owner address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> to</span><span class="z-comment"> token recipient</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> amount</span><span class="z-comment"> amount of token to transfer</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amount</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns amount currently spendable by `_spender`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The amount returned MUST be as of `block.timestamp`, if a renewable allowance </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> for the `_owner` and `_spender` is present.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> owner of token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _spender</span><span class="z-comment"> allowed spender of token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> remaining</span><span class="z-comment"> allowance at the current point in time</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> remaining</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Base method <code>approve(address _spender, uint256 _value)</code> MUST set <code>recoveryRate</code> to 0.</p> <p>Both <code>allowance()</code> and <code>transferFrom()</code> MUST be updated to include allowance recovery logic.</p> <p><code>approveRenewable(address _spender, uint256 _value, uint256 _recoveryRate)</code> MUST set both the initial allowance amount and the maximum allowance limit (to which the allowance can recover) to <code>_value</code>.</p> <p><code>supportsInterface(0x93cd7af6)</code> MUST return <code>true</code>.</p> <h3 id="additional-interfaces">Additional interfaces</h3> <p><strong>Token Proxy</strong></p> <p>Existing ERC-20 tokens can delegate allowance enforcement to a proxy contract that implements this specification. An additional query function exists to get the underlying ERC-20 token.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5827Proxy</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC5827 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0xc55dae63.</span></span> <span class="giallo-l"><span class="z-comment"> * 0xc55dae63 ===</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;baseToken()&#39;)</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the underlying base token being proxied.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> baseToken</span><span class="z-comment"> address of the base token</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> baseToken</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>transfer()</code> function on the proxy MUST NOT emit the <code>Transfer</code> event (as the underlying token already does so).</p> <p><strong>Automatic Expiration</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5827Expirable</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC5827 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x46c5b619.</span></span> <span class="giallo-l"><span class="z-comment"> * 0x46c5b619 ===</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;approveRenewable(address,uint256,uint256,uint64)&#39;)) ^</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;renewableAllowance(address,address)&#39;)) ^</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Grants an allowance of `_value` to `_spender` initially, which recovers over time </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> at a rate of `_recoveryRate` up to a limit of `_value` and expires at </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> `_expiration`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> SHOULD throw when `_recoveryRate` is larger than `_value`, and MUST emit </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `RenewableApproval` event.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _spender</span><span class="z-comment"> allowed spender of token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _value</span><span class="z-comment"> initial allowance granted to spender</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _recoveryRate</span><span class="z-comment"> recovery amount per second</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _expiration</span><span class="z-comment"> Unix time (in seconds) at which the allowance expires</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approveRenewable</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _recoveryRate</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable z-parameter z-function"> _expiration</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Returns approved max amount, recovery rate, and expiration timestamp.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> amount</span><span class="z-comment"> initial and maximum allowance granted to spender</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> recoveryRate</span><span class="z-comment"> recovery amount per second</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> expiration</span><span class="z-comment"> Unix time (in seconds) at which the allowance expires</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> renewableAllowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> recoveryRate</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> expiration</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Renewable allowances can be implemented with discrete resets per time cycle. However, a continuous <code>recoveryRate</code> allows for more flexible use cases not bound by reset cycles and can be implemented with simpler logic.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing ERC-20 token contracts can delegate allowance enforcement to a proxy contract that implements this specification.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>An minimal implementation is included <a href="https://wg-eips.ritovision.com/5827/./assets/ERC5827.sol">here</a></p> <p>An audited, open source implemention of this standard as a <code>IERC5827Proxy</code> can be found at <code>https://github.com/suberra/funnel-contracts</code></p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP introduces a stricter set of constraints compared to ERC-20 with unlimited allowances. However, when <code>_recoveryRate</code> is set to a large value, large amounts can still be transferred over multiple transactions.</p> <p>Applications that are not <a href="https://wg-eips.ritovision.com/5827/">ERC-5827</a>-aware may erroneously infer that the value returned by <code>allowance(address _owner, address _spender)</code> or included in <code>Approval</code> events is the maximum amount of tokens that <code>_spender</code> can spend from <code>_owner</code>. This may not be the case, such as when a renewable allowance is granted to <code>_spender</code> by <code>_owner</code>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-10-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Hadrien Crouboishttps://github.com/Amxx https://wg-eips.ritovision.com/5806/

Adds a new transaction type that allows EOAs to execute arbitrary code through delegation

<h2 id="abstract">Abstract</h2> <p>This EIP adds a new transaction type that allows EOAs to execute arbitrary code using a delegate-call-like mechanism.</p> <h2 id="motivation">Motivation</h2> <p>EOA are the most widely used type of account, yet their ability to perform operations is limited to deploying contracts and sending "call" transactions. It is currently not possible for an EOA to execute arbitrary code, which greatly limits the interactions users can have with the blockchain. Account abstraction has been extensively discussed but the path toward mainstream adoption is still unclear. Some approaches, such as <a href="https://wg-eips.ritovision.com/4337/">ERC-4337</a> hope to improve the usability of smart wallets, without addressing the issue of smart wallet support by applications.</p> <p>While smart contract wallets have a lot to offer in terms of UX, it is unlikely that all users will migrate any time soon because of the associated cost and the fact that some EOAs have custody of non-transferable assets.</p> <p>This EIP proposes an approach to allow the execution of arbitrary code by EOAs, with minimal change over the EVM, and using the same security model users are used to. By allowing EOAs to perform delegate calls to a contract (similarly to how contracts can delegate calls to other contracts using <a href="https://wg-eips.ritovision.com/7/">EIP-7</a>), EOAs will be able to have more control over what operations they want to execute. This proposal's goal is NOT to provide an account abstraction primitive.</p> <p>By performing a delegate call to a multicall contract (such as the one deployed to <code>0xcA11bde05977b3631167028862bE2a173976CA11</code>), EOAs would be able to batch multiple transactions into a single one (being the <code>msg.sender</code> of all the sub calls). This would provide a better UX for users that want to interact with protocols (no need for multiple transactions, with variable gas prices and 21k gas overhead) and increase the security of such interactions (by avoiding unsafe token approvals being exploited between an <code>approval</code> and the following <code>transferFrom</code>).</p> <p>Other unforeseen logic could be implemented in smart contracts and used by EOA. This includes emitting events.</p> <p>This EIP doesn't aim to replace other account abstraction proposals. It hopes to be an easy-to-implement alternative that would significantly improve the user experience of EOA owners in the near future.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="parameters">Parameters</h3> <ul> <li><code>FORK_BLKNUM</code> = <code>TBD</code></li> <li><code>TX_TYPE</code> = TBD, &gt; 0x03 (<a href="https://wg-eips.ritovision.com/4844/">EIP-4844</a>)</li> </ul> <p>As of <code>FORK_BLOCK_NUMBER</code>, a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction is introduced with <code>TransactionType</code> = <code>TX_TYPE(TBD)</code>.</p> <p>The intrinsic cost of the new transaction is inherited from <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a>, specifically <code>21000 + 16 * non-zero calldata bytes + 4 * zero calldata bytes + 1900 * access list storage key count + 2400 * access list address count</code>.</p> <p>The <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>TransactionPayload</code> for this transaction is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>rlp([chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, destination, data, access_list, signature_y_parity, signature_r, signature_s])</span></span></code></pre> <p>The definitions of all fields follow the same semantics as <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>. Note the absence of <code>amount</code> field in this transaction!</p> <p>The <code>to</code> field deviates slightly from the semantics with the exception that it MUST NOT be nil and therefore must always represent a 20-byte address. This means that delegate transactions cannot have the form of a create transaction.</p> <p>The <code>signature_y_parity, signature_r, signature_s</code> elements of this transaction represent a secp256k1 signature over <code>keccak256(TX_TYPE || rlp([chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, destination, data, access_list]))</code>.</p> <p>The <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>ReceiptPayload</code> for this transaction is <code>rlp([status, cumulative_transaction_gas_used, logs_bloom, logs])</code>.</p> <p>The execution of this new transaction type is equivalent to the delegate call mechanism introduced in <a href="https://wg-eips.ritovision.com/7/">EIP-7</a>, but performed by an EOA (the transaction sender). This implies that the code present at <code>destination</code>, if any, should be executed in the context of the sender. As a consequence, such a transaction emit an event from the EOA or use <code>Create2</code> with the address of the EOA as the creator. This transaction includes some restrictions though.</p> <h3 id="opcode-restriction">Opcode restriction</h3> <p>For security reasons, some opcodes should not be executed in the context of an EOA:</p> <ul> <li> <p><code>SSTORE</code> (0x55): Setting storage under an EOA breaks many assumptions. In particular storage set through a delegate transaction could cause issues if the accounts later "migrates" using <a href="https://wg-eips.ritovision.com/7377/">EIP-7377</a> or similar. Additionally, storage may be a source of conflicts if a single EOA uses delegate transactions to target codes that interpret the storage layout under this account differently. For all these reasons, EOA should be forbidden from performing <code>SSTORE</code> in the context of a delegate transaction. If a delegate transaction performs a CALL, the target of the call is free to manipulate storage normally.</p> </li> <li> <p><code>CREATE</code> (0xF0), <code>CREATE2</code> (0xF5) and <code>SELFDESTRUCT</code> (0xFF): There may be an expectation that transactions from a given sender should have consecutive nonces. This assumption would be broken if an EOA was able to execute one or multiple operations that alter the sender account's nonce. Consequently, EOA performing a delegate transaction should not be able to use the <code>CREATE</code>, <code>CREATE2</code> or <code>SELFDESTRUCT</code> opcodes. If a delegate transaction performs a CALL, the target of the call is free to create contracts normally.</p> </li> </ul> <p>Any attempts to make execute one of these restricted operations will instead throw an exception.</p> <h2 id="rationale">Rationale</h2> <p>EOAs are the most widely used type of wallet.</p> <p>This EIP would drastically expand the ability of EOAs to interact with smart contracts by using the pre-existing and well-understood delegation mechanism introduced in <a href="https://wg-eips.ritovision.com/7/">EIP-7</a> and without adding new complexity to the EVM.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No known backward compatibility issues thanks to the transaction envelope (<a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a>).</p> <p>Due to the inclusion logic and the gas cost being similar to type 2 transactions, it should be possible to include this new transaction type in the same mempool.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The nonce mechanism, already used in other transaction types, prevents replay attacks. Similar to existing transaction types, a delegate transaction can be cancelled by replacing it with a dummy transaction that pays more fees.</p> <p>Since the object signed by the wallet is a transaction and not a signature that could potentially be processed in many ways (as is the case for <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a>), the risks associated with the miss-use of the signature are reduced. A wallet could simulate the execution of this delegate transaction and provide good guarantees that the operation that the user signs won't be manipulated.</p> <p>Contracts being called through this mechanism can execute any operation on behalf of the signer. As with other transaction types, signers should be extremely careful when signing a delegate transaction.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-10-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yu Liuhttps://github.com/yuliu-debond Junyi Zhonghttps://github.com/Jooeys https://wg-eips.ritovision.com/5851/

Interface for contracts that manage verifiable claims and identifiers as Soulbound tokens.

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a method of certifying that a particular address meets a claim, and a method of verifying those certifications using on-chain metadata. Claims are assertions or statements made about a subject having certain properties that may be met conditions (for example: <code>age &gt;= 18</code>), and are certified by issuers using a Soundbound Token (SBT).</p> <h2 id="motivation">Motivation</h2> <p>On-chain issuance of verifiable attestations are essential for use-case like:</p> <ul> <li>Avoiding Sybil attacks with one person one vote</li> <li>Participation in certain events with credentials</li> <li>Compliance to government financial regulations etc.</li> </ul> <p>We are proposing a standard claims structure for Decentralized Identity (DID) issuers and verifier entities to create smart contracts in order to provide on-chain commitment of the off-chain verification process, and once the given address is associated with the given attestation of the identity verification off-chain, the issuers can then onboard other verifiers (i.e. governance, financial institution, non-profit organization, web3 related cooperation) to define the condition of the ownership of the user in order to reduce the technical barriers and overhead of current implementations.</p> <p>The motivation behind this proposal is to create a standard for verifier and issuer smart contracts to communicate with each other in a more efficient way. This will reduce the cost of KYC processes, and provide the possibility for on-chain KYC checks. By creating a standard for communication between verifiers and issuers, it will create an ecosystem in which users can be sure their data is secure and private. This will ultimately lead to more efficient KYC processes and help create a more trustful environment for users. It will also help to ensure that all verifier and issuer smart contracts are up-to-date with the most recent KYC regulations.</p> <h2 id="specification">Specification</h2> <p>The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.</p> <h3 id="definitions">Definitions</h3> <ul> <li> <p>Zero-Knowledge Proof (ZKP): a cryptographic device that can convince a verifier that an assertion is correct without revealing all of the inputs to the assertion.</p> </li> <li> <p>Soulbound Token (SBT): A non-fungible and non-transferrable token that is used for defining the identity of the users.</p> </li> <li> <p>SBT Certificate: An SBT that represents the ownership of ID signatures corresponding to the claims defined in <code>function standardClaim()</code>.</p> </li> <li> <p>Verifiable Credential (VC): A collection of claims made by an issuer. These are temper evident credentials that allow the holders to prove that they posses certain characteristics (for example, passport verification, constraints like value of tokens in your wallet, etc) as demanded by the verifier entity.</p> </li> <li> <p>Claim: An assertion that the DID Holder must fulfill to be verified.</p> </li> <li> <p>Holder: The entity that stores the claim, such as a digital identity provider or a DID registry. The holder is responsible for validating the claim and providing verifiable evidence of the claim.</p> </li> <li> <p>Claimer: The party making a claim, such as in an identity verification process.</p> </li> <li> <p>Issuer: The entity that creates a verifiable credential from claims about one or more subjects to a holder. Example issuers include governments, corporations, non-profit organizations, trade associations, and individuals.</p> </li> <li> <p>Verifier: An entity that validates data provided by an issuer of verifiable credentials, determining its accuracy, origin, currency and trustworthiness.</p> </li> </ul> <h3 id="metadata-standard">Metadata Standard</h3> <p>Claims MUST be exposed in the following structures:</p> <h4 id="1-metadata-information">1. Metadata information</h4> <p>Each claim requirement MUST be exposed using the following structure:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Metadata</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> title</span><span class="z-comment"> defines the name of the claim field</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _type</span><span class="z-comment"> is the type of the data (bool,string,address,bytes,..)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> description</span><span class="z-comment"> additional information about claim details.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Metadata</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> title</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> _type</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> description</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h4 id="2-values-information">2. Values Information</h4> <p>This following structure will be used to define the actual claim information, based on the description of the <code>Metadata</code> structure, the structure is the same as <code>Values</code> structure of <a href="https://wg-eips.ritovision.com/3475/">EIP-3475</a>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Values</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> stringValue</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> uintValue</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> addressValue</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> boolValue</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h4 id="3-claim-structure">3. Claim structure</h4> <p>Claims (eg. <code>age &gt;= 18</code>, jurisdiction in allowlist, etc.) are represented by one or many instances of the <code>Claim</code> structure below:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Claims</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Claims structure consist of the conditions and value that holder claims to associate and verifier has to validate them.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> the below given parameters are for reference purposes only, developers can optimize the fields that are needed to be represented on-chain by using schemes like TLV, encoding into base64 etc.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> structure that defines the parameters for specific claims of the SBT certificate</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> this structure is used for the verification process, it contains the metadata, logic and expectation</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> logic can represent either the enum format for defining the different operations, or they can be logic operators (stored in form of ASCII figure based on unicode standard). like e.g: </span></span> <span class="giallo-l"><span class="z-comment">(&quot;⊄&quot; = U+2284, &quot;⊂&quot; = U+2282, &quot;&lt;&quot; = U+003C , &quot;&lt;=&quot; = U + 2265,&quot;==&quot; = U + 003D, &quot;!=&quot;U + 2260, &quot;&gt;=&quot; = U + 2265,&quot;&gt;&quot; = U + 2262).</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Claim</span><span> {</span></span> <span class="giallo-l"><span> Metadata metadata</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> logic</span><span>;</span></span> <span class="giallo-l"><span> Values expectation</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>description of some logic functions that can be used are as follows:</p> <table><thead><tr><th>Symbol</th><th>Description</th></tr></thead><tbody> <tr><td>⊄</td><td>does not belong to the set of values (or range) defined by the corresponding <code>Values</code></td></tr> <tr><td>⊂</td><td>condition that the parameter belongs to one of values defined by the <code>Values</code></td></tr> <tr><td>&lt;</td><td>condition that the parameter is greater than value defined by the <code>Values</code></td></tr> <tr><td>==</td><td>condition that the parameter is strictly equal to the value defined by the <code>Values</code> structure</td></tr> </tbody></table> <h4 id="claim-example">Claim Example</h4> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">age</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">unit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">age of the person based on the birth date on the legal document</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">logic</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">&gt;=</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">18</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Defines the condition encoded for the index 1 (i.e the holder must be equal or more than 18 years old).</p> <h3 id="interface-specification">Interface specification</h3> <h4 id="verifier">Verifier</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> getter function to validate if the address `claimer` is the holder of the claim defined by the tokenId `SBTID`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> it MUST be defining the conditional operator (logic explained below) to allow the application to convert it into code logic </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> logic given here MUST be the conditiaonl operator, MUST be one of (&quot;⊄&quot;, &quot;⊂&quot;, &quot;&lt;&quot;, &quot;&lt;=&quot;, &quot;==&quot;, &quot;!=&quot;, &quot;&gt;=&quot;, &quot;&gt;&quot;)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> claimer</span><span class="z-comment"> is the EOA address that wants to validate the SBT issued to it by the issuer. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> SBTID</span><span class="z-comment"> is the Id of the SBT that user is the claimer.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> true</span><span class="z-comment"> if the assertion is valid, else false</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> example ifVerified(0xfoo, 1) =&gt; true will mean that 0xfoo is the holder of the SBT identity token defined by tokenId of the given collection. </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ifVerified</span><span>(</span><span class="z-support">address</span><span class="z-variable"> claimer</span><span>,</span><span class="z-support"> uint256</span><span class="z-storage z-type"> SBTID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="issuer">Issuer</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> getter function to fetch the on-chain identification logic for the given identity holder.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> it MUST not be defined for address(0). </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> SBTID</span><span class="z-comment"> is the Id of the SBT that the user is the claimer.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> struct array of all the descriptions of condition metadata that is defined by the administrator for the given KYC provider.</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> ex: standardClaim(1) --&gt; {</span></span> <span class="giallo-l"><span class="z-comment"> { &quot;title&quot;:&quot;age&quot;,</span></span> <span class="giallo-l"><span class="z-comment"> &quot;type&quot;: &quot;uint&quot;,</span></span> <span class="giallo-l"><span class="z-comment"> &quot;description&quot;: &quot;age of the person based on the birth date on the legal document&quot;,</span></span> <span class="giallo-l"><span class="z-comment"> },</span></span> <span class="giallo-l"><span class="z-comment"> &quot;logic&quot;: &quot;&gt;=&quot;,</span></span> <span class="giallo-l"><span class="z-comment"> &quot;value&quot;:&quot;18&quot; </span></span> <span class="giallo-l"><span class="z-comment"> }</span></span> <span class="giallo-l"><span class="z-comment"> Defines the condition encoded for the identity index 1, defining the identity condition that holder must be equal or more than 18 years old.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> standardClaim</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> SBTID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">Claim</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> function for setting the claim requirement logic (defined by Claims metadata) details for the given identity token defined by SBTID.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> it should only be called by the admin address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> SBTID</span><span class="z-comment"> is the Id of the SBT-based identity certificate for which the admin wants to define the Claims.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-comment"> `claims` is the struct array of all the descriptions of condition metadata that is defined by the administrator. check metadata section for more information.</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> example: changeStandardClaim(1, { &quot;title&quot;:&quot;age&quot;,</span></span> <span class="giallo-l"><span class="z-comment"> &quot;type&quot;: &quot;uint&quot;,</span></span> <span class="giallo-l"><span class="z-comment"> &quot;description&quot;: &quot;age of the person based on the birth date on the legal document&quot;,</span></span> <span class="giallo-l"><span class="z-comment"> },</span></span> <span class="giallo-l"><span class="z-comment"> &quot;logic&quot;: &quot;&gt;=&quot;,</span></span> <span class="giallo-l"><span class="z-comment"> &quot;value&quot;:&quot;18&quot; </span></span> <span class="giallo-l"><span class="z-comment"> }); </span></span> <span class="giallo-l"><span class="z-comment"> will correspond to the functionality that admin needs to adjust the standard claim for the identification SBT with tokenId = 1, based on the conditions described in the Claims array struct details.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> changeStandardClaim</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> SBTID</span><span>,</span><span class="z-storage z-type"> Claim</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _claims</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> function which uses the ZKProof protocol to validate the identity based on the given </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> it should only be called by the admin address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> SBTID</span><span class="z-comment"> is the Id of the SBT-based identity certificate for which admin wants to define the Claims.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> claimer</span><span class="z-comment"> is the address that needs to be proven as the owner of the SBT defined by the tokenID.</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> example: certify(0xA....., 10) means that admin assigns the DID badge with id 10 to the address defined by the `0xA....` wallet.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> certify</span><span>(</span><span class="z-support">address</span><span class="z-variable"> claimer</span><span>,</span><span class="z-support"> uint256</span><span class="z-storage z-type"> SBTID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> function which uses the ZKProof protocol to validate the identity based on the given </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> it should only be called by the admin address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> SBTID</span><span class="z-comment"> is the Id of the SBT-based identity certificate for which the admin wants to define the Claims.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> claimer</span><span class="z-comment"> is the address that needs to be proven as the owner of the SBT defined by the tokenID.</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> eg: revoke(0xfoo,1): means that KYC admin revokes the SBT certificate number 1 for the address &#39;0xfoo&#39;. </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revoke</span><span>(</span><span class="z-support">address</span><span class="z-variable"> certifying</span><span>,</span><span class="z-support"> uint256</span><span class="z-storage z-type"> SBTID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span></code></pre><h4 id="events">Events</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> * standardChanged</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> standardChanged MUST be triggered when claims are </span><span class="z-keyword">changed</span><span class="z-comment"> by the admin. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> standardChanged MUST also be triggered for the creation of a new SBTID.</span></span> <span class="giallo-l"><span class="z-comment"> e.g : emit StandardChanged(1, Claims(Metadata(&#39;age&#39;, &#39;uint&#39;, &#39;age of the person based on the birth date on the legal document&#39; ), &quot;&gt;=&quot;, &quot;18&quot;);</span></span> <span class="giallo-l"><span class="z-comment"> is emitted when the Claim condition is </span><span class="z-keyword">changed</span><span class="z-comment"> which allows the certificate holder to call the functions with the modifier, claims that the holder must be equal or more than 18 years old.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> StandardChanged</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> SBTID</span><span>, </span><span class="z-variable">Claim</span><span>[</span><span>]</span><span class="z-variable"> _claims</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> * certified</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> certified MUST be triggered when the SBT certificate is given to the certifying address. </span></span> <span class="giallo-l"><span class="z-comment"> * eg: Certified(0xfoo,2); means that wallet holder address `0xfoo` is certified to hold a certificate issued with id 2, and thus can satisfy all the conditions defined by the required interface.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Certified</span><span>(</span><span class="z-support">address</span><span class="z-variable"> claimer</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> SBTID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> * revoked</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> revoked MUST be triggered when the SBT certificate is revoked. </span></span> <span class="giallo-l"><span class="z-comment"> * eg: Revoked( 0xfoo,1); means that entity user 0xfoo has been revoked to all the function access defined by the SBT ID 1.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Revoked</span><span>(</span><span class="z-support">address</span><span class="z-variable"> claimer</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> SBTID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>TBD</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ul> <li>This EIP is backward compliant for the contracts that keep intact the metadata structure of previous issued SBT's with their ID and claim requirement details. <ul> <li>For e.g if the DeFI provider (using the modifiers to validate the ownership of required SBT by owner) wants the admin to change the logic of verification or remove certain claim structure, the previous holders of the certificates will be affected by these changes.</li> </ul> </li> </ul> <h2 id="test-cases">Test Cases</h2> <p>Test cases for the minimal reference implementation can be found <a href="https://wg-eips.ritovision.com/5851/./assets/contracts/test.sol">here</a> for using transaction verification regarding whether the users hold the tokens or not. Use Remix IDE to compile and test the contracts.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The <a href="https://wg-eips.ritovision.com/5851/./assets/contracts/interfaces/IERC5851.sol">interface</a> is divided into two separate implementations:</p> <ul> <li> <p><a href="https://wg-eips.ritovision.com/5851/./assets/contracts/ERC5851Verifier.sol">EIP-5851 Verifier</a> is a simple modifier that needs to be imported by functions that are to be only called by holders of the SBT certificates. Then the modifier will call the issuer contract to verifiy if the claimer has the SBT certifcate in question.</p> </li> <li> <p><a href="https://wg-eips.ritovision.com/5851/./assets/contracts/ERC5851Issuer.sol">EIP-5851 Issuer</a> is an example of an identity certificate that can be assigned by a KYC controller contract. This is a full implementation of the standard interface.</p> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <ol> <li>Implementation of functional interfaces for creating KYC on SBT (i.e <code>changeStandardClaim()</code>, <code>certify()</code> and <code>revoke()</code>) are dependent on the admin role. Thus the developer must insure security of admin role and rotation of this role to the entity entrusted by the KYC attestation service provider and DeFI protocols that are using this attestation service.</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-10-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Filipp Makarovhttps://github.com/filmakarov https://wg-eips.ritovision.com/5753/

Interface for disabling token transfers (locking) and re-enabling them (unlocking).

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>. It introduces lockable NFTs. The locked asset can be used in any way except by selling and/or transferring it. The owner or operator can lock the token. When a token is locked, the unlocker address (an EOA or a contract) is set. Only the unlocker is able to <code>unlock</code> the token.</p> <h2 id="motivation">Motivation</h2> <p>With NFTs, digital objects become digital goods, which are verifiably ownable, easily tradable, and immutably stored on the blockchain. That's why it's very important to continuously improve UX for non-fungible tokens, not just inherit it from one of the fungible tokens.</p> <p>In DeFi there is an UX pattern when you lock your tokens on a service smart contract. For example, if you want to borrow some $DAI, you have to provide some $ETH as collateral for a loan. During the loan period this $ETH is being locked into the lending service contract. Such a pattern works for $ETH and other fungible tokens.</p> <p>However, it should be different for NFTs because NFTs have plenty of use cases that require the NFT to stay in the holder's wallet even when it is used as collateral for a loan. You may want to keep using your NFT as a verified PFP on Twitter, or use it to authorize a Discord server through collab.land. You may want to use your NFT in a P2E game. And you should be able to do all of this even during the lending period, just like you are able to live in your house even if it is mortgaged.</p> <p>The following use cases are enabled for lockable NFTs:</p> <ul> <li><strong>NFT-collateralised loans</strong> Use your NFT as collateral for a loan without locking it on the lending protocol contract. Lock it on your wallet instead and continue enjoying all the utility of your NFT.</li> <li><strong>No collateral rentals of NFTs</strong> Borrow NFT for a fee, without a need for huge collateral. You can use NFT, but not transfer it, so the lender is safe. The borrowing service contract automatically transfers NFT back to the lender as soon as the borrowing period expires.</li> <li><strong>Primary sales</strong> Mint NFT for only the part of the price and pay the rest when you are satisfied with how the collection evolves.</li> <li><strong>Secondary sales</strong> Buy and sell your NFT by installments. Buyer gets locked NFT and immediately starts using it. At the same time he/she is not able to sell the NFT until all the installments are paid. If full payment is not received, NFT goes back to the seller together with a fee.</li> <li><strong>S is for Safety</strong> Use your exclusive blue chip NFTs safely and conveniently. The most convenient way to use NFT is together with MetaMask. However, MetaMask is vulnerable to various bugs and attacks. With <code>Lockable</code> extension you can lock your NFT and declare your safe cold wallet as an unlocker. Thus, you can still keep your NFT on MetaMask and use it conveniently. Even if a hacker gets access to your MetaMask, they won’t be able to transfer your NFT without access to the cold wallet. That’s what makes <code>Lockable</code> NFTs safe.</li> <li><strong>Metaverse ready</strong> Locking NFT tickets can be useful during huge Metaverse events. That will prevent users, who already logged in with an NFT, from selling it or transferring it to another user. Thus we avoid double usage of one ticket.</li> <li><strong>Non-custodial staking</strong> There are different approaches to non-custodial staking proposed by communities like CyberKongz, Moonbirds and other. Approach suggested in this impementation supposes that the token can only be staked in one place, not several palces at a time (it is like you can not deposit money in two bank accounts simultaneously). Also it doesn't require any additional code and is available with just locking feature. Another approach to the same concept is using locking to provide proof of HODL. You can lock your NFTs from selling as a manifestation of loyalty to the community and start earning rewards for that. It is better version of the rewards mechanism, that was originally introduced by The Hashmasks and their $NCT token.</li> <li><strong>Safe and convenient co-ownership and co-usage</strong> Extension of safe co-ownership and co-usage. For example, you want to purchase an expensive NFT asset together with friends, but it is not handy to use it with multisig, so you can safely rotate and use it between wallets. The NFT will be stored on one of the co-owners' wallet and he will be able to use it in any way (except transfers) without requiring multi-approval. Transfers will require multi-approval.</li> </ul> <h2 id="specification">Specification</h2> <p>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> <p>EIP-721 compliant contracts MAY implement this EIP to provide standard methods of locking and unlocking the token at its current owner address. If the token is locked, the <code>getLocked</code> function MUST return an address that is able to unlock the token. For tokens that are not locked, the <code>getLocked</code> function MUST return <code>address(0)</code>. The user MAY permanently lock the token by calling <code>lock(address(1), tokenId)</code>.</p> <p>When the token is locked, all the <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> transfer functions MUST revert, except if the transaction has been initiated by an unlocker. When the token is locked, the <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> <code>approve</code> method MUST revert for this token. When the token is locked, the <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> <code>getApproved</code> method SHOULD return <code>unlocker</code> address for this token so the unlocker is able to transfer this token. When the token is locked, the <code>lock</code> method MUST revert for this token, even when it is called with the same <code>unlocker</code> as argument. When the locked token is transferred by an unlocker, the token MUST be unlocked after the transfer.</p> <p>Marketplaces should call <code>getLocked</code> method of an EIP-721 Lockable token contract to learn whether a token with a specified tokenId is locked or not. Locked tokens SHOULD NOT be available for listings. Locked tokens can not be sold. Thus, marketplaces SHOULD hide the listing for the tokens that has been locked, because such orders can not be fulfilled.</p> <h3 id="contract-interface">Contract Interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface for the Lockable extension</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ILockable</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `id` token is locked, and `unlocker` is stated as unlocking wallet.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Lock</span><span> (</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> unlocker</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> id</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `id` token is unlocked.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Unlock</span><span> (</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> id</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Locks the `id` token and gives the `unlocker` address permission to unlock.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lock</span><span>(</span><span class="z-support">address</span><span class="z-variable"> unlocker</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Unlocks the `id` token.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unlock</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the wallet, that is stated as unlocking wallet for the `tokenId` token.</span></span> <span class="giallo-l"><span class="z-comment"> * If address(0) returned, that means token is not locked. Any other result means token is locked.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLocked</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0x72b68110</code>.</p> <h2 id="rationale">Rationale</h2> <p>This approach proposes a solution that is designed to be as minimal as possible. It only allows to lock the item (stating who will be able to unlock it) and unlock it when needed if a user has permission to do it.</p> <p>At the same time, it is a generalized implementation. It allows for a lot of extensibility and any of the potential use cases (or all of them), mentioned in the Motivation section.</p> <p>When there is a need to grant temporary and/or redeemable rights for the token (rentals, purchase with instalments) this EIP involves the real transfer of the token to the temporary user's wallet, not just assigning a role. This choice was made to increase compatibility with all the existing NFT eco-system tools and dApps, such as Collab.land. Otherwise, it would require from all of such dApps implementing additional interfaces and logic.</p> <p>Naming and reference implementation for the functions and storage entities mimics that of Approval flow for [EIP-721] in order to be intuitive.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with current <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> standards.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;../ILockable.sol&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;@openzeppelin/contracts/token/ERC721/ERC721.sol&#39;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> Lockable Extension for ERC721</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">abstract</span><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> ERC721Lockable</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">ILockable</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">///////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> LOCKABLE EXTENSION STORAGE </span></span> <span class="giallo-l"><span class="z-comment"> //////////////////////////////////////////////////////////////</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> address</span><span>)</span><span class="z-storage z-type"> internal</span><span> unlockers</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">///////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> LOCKABLE LOGIC</span></span> <span class="giallo-l"><span class="z-comment"> //////////////////////////////////////////////////////////////</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Public function to lock the token. Verifies if the msg.sender is the owner</span></span> <span class="giallo-l"><span class="z-comment"> * or approved party.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lock</span><span>(</span><span class="z-support">address</span><span class="z-variable"> unlocker</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> tokenOwner </span><span class="z-keyword">=</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span>id</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> tokenOwner </span><span class="z-keyword">||</span><span class="z-entity z-name"> isApprovedForAll</span><span>(</span><span>tokenOwner</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span></span> <span class="giallo-l"><span> ,</span><span class="z-string"> &quot;NOT_AUTHORIZED&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>unlockers</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> ==</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;ALREADY_LOCKED&quot;</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span> unlockers</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> =</span><span> unlocker</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _approve</span><span>(</span><span>unlocker</span><span>,</span><span> id</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Public function to unlock the token. Only the unlocker (stated at the time of locking) can unlock</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unlock</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> unlockers</span><span>[</span><span>id</span><span>]</span><span>,</span><span class="z-string"> &quot;NOT_UNLOCKER&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> unlockers</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the unlocker for the tokenId</span></span> <span class="giallo-l"><span class="z-comment"> * address(0) means token is not locked</span></span> <span class="giallo-l"><span class="z-comment"> * reverts if token does not exist</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLocked</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;Lockable: locking query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> unlockers</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Locks the token</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _lock</span><span>(</span><span class="z-support">address</span><span class="z-variable"> unlocker</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span> unlockers</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> =</span><span> unlocker</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Unlocks the token</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _unlock</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span> unlockers</span><span>[</span><span>id</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">///////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> OVERRIDES</span></span> <span class="giallo-l"><span class="z-comment"> //////////////////////////////////////////////////////////////</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span> (</span><span class="z-entity z-name">getLocked</span><span>(</span><span>tokenId</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;Can not approve locked token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span>to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _beforeTokenTransfer</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if it is a Transfer or Burn</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>from </span><span class="z-keyword">!=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> token should not be locked or msg.sender should be unlocker to do that</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">getLocked</span><span>(</span><span>tokenId</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> ||</span><span class="z-variable z-language"> msg.sender</span><span class="z-keyword"> ==</span><span class="z-entity z-name"> getLocked</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;LOCKED&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _afterTokenTransfer</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if it is a Transfer or Burn, we always deal with one token, that is startTokenId</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>from </span><span class="z-keyword">!=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> clear locks</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> unlockers</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Optional override, if to clear approvals while the tken is locked</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getApproved</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-entity z-name">getLocked</span><span>(</span><span>tokenId</span><span>)</span><span class="z-keyword"> !=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">getApproved</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">///////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> ERC165 LOGIC</span></span> <span class="giallo-l"><span class="z-comment"> //////////////////////////////////////////////////////////////</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</span></span> <span class="giallo-l"><span class="z-storage z-type"> override</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC721Lockable</span><span>)</span><span>.</span><span>interfaceId </span><span class="z-keyword">||</span></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>There are no security considerations related directly to the implementation of this standard for the contract that manages <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> tokens.</p> <h3 id="considerations-for-the-contracts-that-work-with-lockable-tokens">Considerations for the contracts that work with lockable tokens</h3> <ul> <li>Make sure that every contract that is stated as <code>unlocker</code> can actually unlock the token in all cases.</li> <li>There are use cases, that involve transferring the token to a temporary owner and then lock it. For example, NFT rentals. Smart contracts that manage such services should always use <code>transferFrom</code> instead of <code>safeTransferFrom</code> to avoid re-entrancies.</li> <li>There are no MEV considerations regarding lockable tokens as only authorized parties are allowed to lock and unlock.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a></p> 2022-09-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Cozy Financehttps://github.com/cozyfinance Tony Shenghttps://github.com/tonysheng Matt Solomonhttps://github.com/mds1 David Lapradehttps://github.com/davidlaprade Payom Doustihttps://github.com/payomdousti Chad Fleminghttps://github.com/chad-js Franz Chenhttps://github.com/Dendrimer https://wg-eips.ritovision.com/5744/

An interface for tokens that become fungible after a period of time.

<h2 id="abstract">Abstract</h2> <p>The following standard is an extension of <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> that enables tokens to become fungible after some initial non-fungible period. Once minted, tokens are non-fungible until they reach maturity. At maturity, they become fungible and can be transferred, traded, and used in any way that a standard EIP-20 token can be used.</p> <h2 id="motivation">Motivation</h2> <p>Example use cases include:</p> <ul> <li>Receipt tokens that do not become active until a certain date or condition is met. For example, this can be used to enforce minimum deposit durations in lending protocols.</li> <li>Vesting tokens that cannot be transferred or used until the vesting period has elapsed.</li> </ul> <h2 id="specification">Specification</h2> <p>All latent fungible tokens MUST implement EIP-20 to represent the token. The <code>balanceOf</code> and <code>totalSupply</code> return quantities for all tokens, not just the matured, fungible tokens. A new method called <code>balanceOfMatured</code> MUST be added to the ABI. This method returns the balance of matured tokens for a given address:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOfMatured</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <p>An additional method called <code>getMints</code> MUST be added, which returns an array of all mint metadata for a given address:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> MintMetadata</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Amount of tokens minted.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Timestamp of the mint, in seconds.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> time</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Delay in seconds until these tokens mature and become fungible. When the</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> delay is not known (e.g. if it&#39;s dependent on other factors aside from</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> simply elapsed time), this value must be `type(uint256).max`.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> delay</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getMints</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">MintMetadata</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre> <p>Note that the implementation does not require that each of the above metadata parameters are stored as a <code>uint256</code>, just that they are returned as <code>uint256</code>.</p> <p>An additional method called <code>mints</code> MAY be added. This method returns the metadata for a mint based on its ID:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> mints</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">MintMetadata</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre> <p>The ID is not prescriptive—it may be an index in an array, or may be generated by other means.</p> <p>The <code>transfer</code> and <code>transferFrom</code> methods MAY be modified to revert when transferring tokens that have not matured. Similarly, any methods that burn tokens MAY be modified to revert when burning tokens that have not matured.</p> <p>All latent fungible tokens MUST implement EIP-20’s optional metadata extensions. The <code>name</code> and <code>symbol</code> functions MUST reflect the underlying token’s <code>name</code> and <code>symbol</code> in some way.</p> <h2 id="rationale">Rationale</h2> <p>The <code>mints</code> method is optional because the ID is optional. In some use cases such as vesting where a user may have a maximum of one mint, an ID is not required.</p> <p>Similarly, vesting use cases may want to enforce non-transferrable tokens until maturity, whereas lending receipt tokens with a minimum deposit duration may want to support transfers at all times.</p> <p>It is possible that the number of mints held by a user is so large that it is impractical to return all of them in a single <code>eth_call</code>. This is unlikely so it was not included in the spec. If this is likely for a given use case, the implementer may choose to implement an alternative method that returns a subset of the mints, such as <code>getMints(address user, uint256 startId, uint256 endId)</code>. However, if IDs are not sequential, a different signature may be required, and therefore this was not included in the specification.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward compatible with the EIP-20 standard and has no known compatibility issues with other standards.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Iterating over large arrays of mints is not recommended, as this is very expensive and may cause the protocol, or just a user's interactions with it, to be stuck if this exceeds the block gas limit and reverts. There are some ways to mitigate this, with specifics dependent on the implementation.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-09-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Agustin Aguilarhttps://github.com/Agusx1211 https://wg-eips.ritovision.com/5719/

Non-interactive replacing of smart contract wallet signatures that became stale due to configuration changes.

<h2 id="abstract">Abstract</h2> <p>Smart contract wallet signed messages can become stale, meaning a signature that once was valid could become invalid at any point.</p> <p>Signatures MAY become stale for reasons like:</p> <ul> <li>The internal set of signers changed</li> <li>The wallet makes signatures expirable</li> <li>The contract was updated to a new implementation</li> </ul> <p>The following standard allows smart contract wallets to expose a URI that clients can use to replace a stale signature with a valid one.</p> <h2 id="motivation">Motivation</h2> <p>In contrast to EOA signatures, <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> signatures are not necessarily idempotent; they can become invalid at any point in time. This poses a challenge to protocols that rely on signatures remaining valid for extended periods of time.</p> <p>A signature MAY need to be mutated due to one of the following scenarios:</p> <ol> <li>The wallet removes a signer that contributed to signing the initial message.</li> <li>The wallet uses a Merkle tree to store signers, adding a new signer.</li> <li>The wallet uses a Merkle tree to store signatures, adding new signatures.</li> <li>The wallet is updated to a new implementation, and the signature schema changes.</li> </ol> <p>Non-interactive signature replacement SHOULD be possible, since the wallet that originally signed the message MAY NOT be available when the signature needs to be validated. An example use-case is the settlement of a trade in an exchange that uses an off-chain order book.</p> <h2 id="specification">Specification</h2> <p>The wallet contract MUST implement the following function:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getAlternativeSignature</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _digest</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span>)</span><span>;</span></span></code></pre> <p>The returned string MUST be a URI pointing to a JSON object with the following schema:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Signature alternative</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">blockHash</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A block.hash on which the signature should be valid.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signature</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The alternative signature for the given digest.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="client-process-for-replacing-a-signature">Client process for replacing a signature</h3> <p>A client is an entity that holds a signature and intends to validate it, either for off-chain or on-chain use. To use the smart contract wallet signature, the client MUST perform the following actions:</p> <ol> <li>Try validating the signature using <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a>; if the signature is valid, then the signature can be used as-is.</li> <li>If the signature is not valid, call <code>getAlternativeSignature(_digest)</code>, passing the <code>digest</code> corresponding to the old signature.</li> <li>If the call fails, no URI is returned, or the content of the URI is not valid, then the signature MUST be considered invalid.</li> <li>Try validating the new signature using <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a>; if the signature is valid, it can be used as a drop-in replacement of the original signature.</li> <li>If the validation fails, repeat the process from step (2) (notice: if the URI returns the same signature, the signature MUST be considered invalid).</li> </ol> <p>Clients MUST implement a retry limit when fetching alternative signatures. This limit is up to the client to define.</p> <h2 id="rationale">Rationale</h2> <p>A URI is chosen because it can accommodate centralized and decentralized solutions. For example, a server can implement live re-encoding for Merkle proofs, or an IPFS link could point to a directory with all the pre-computed signature mutations.</p> <p>The <code>getAlternativeSignature</code> method points to an off-chain source because it's expected that the smart contract wallet doesn't contain on-chain records for all signed digests, if that were the case then such contract wouldn't need to use this EIP since it could directly validate the <code>digest</code> on<code>isValidSignature</code> ignoring the stale signature.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing wallets that do not implement the <code>getAlternativeSignature</code> method can still sign messages without any changes; if any signatures become invalidated, clients will drop them on step (3).</p> <h2 id="security-considerations">Security Considerations</h2> <p>Some applications use signatures as secrets; these applications would risk leaking such secrets if the EIP exposes the signatures.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-09-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 cygaarhttps://github.com/cygaar https://wg-eips.ritovision.com/5643/

Add subscription-based functionality to EIP-721 tokens

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>. It proposes an additional interface for NFTs to be used as recurring, expirable subscriptions. The interface includes functions to renew and cancel the subscription.</p> <h2 id="motivation">Motivation</h2> <p>NFTs are commonly used as accounts on decentralized apps or membership passes to communities, events, and more. However, it is currently rare to see NFTs like these that have a finite expiration date. The "permanence" of the blockchain often leads to memberships that have no expiration dates and thus no required recurring payments. However, for many real-world applications, a paid subscription is needed to keep an account or membership valid.</p> <p>The most prevalent on-chain application that makes use of the renewable subscription model is the Ethereum Name Service (ENS), which utilizes a similar interface to the one proposed below. Each domain can be renewed for a certain period of time, and expires if payments are no longer made. A common interface will make it easier for future projects to develop subscription-based NFTs. In the current Web2 world, it's hard for a user to see or manage all of their subscriptions in one place. With a common standard for subscriptions, it will be easy for a single application to determine the number of subscriptions a user has, see when they expire, and renew/cancel them as requested.</p> <p>Additionally, as the prevalence of secondary royalties from NFT trading disappears, creators will need new models for generating recurring income. For NFTs that act as membership or access passes, pivoting to a subscription-based model is one way to provide income and also force issuers to keep providing value.</p> <h2 id="specification">Specification</h2> <p>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> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5643</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when a subscription expiration changes</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> When a subscription is canceled, the expiration value should also be 0.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SubscriptionUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> expiration</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Renews the subscription to an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if `tokenId` is not a valid NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT to renew the subscription for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> duration</span><span class="z-comment"> The number of seconds to extend a subscription for</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> renewSubscription</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> duration</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Cancels the subscription of an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if `tokenId` is not a valid NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT to cancel the subscription for</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelSubscription</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets the expiration date of a subscription</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if `tokenId` is not a valid NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT to get the expiration date of</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> expiration date of the subscription</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> expiresAt</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint64</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Determines whether a subscription can be renewed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if `tokenId` is not a valid NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT to get the expiration date of</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> renewability of a the subscription</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRenewable</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>expiresAt(uint256 tokenId)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>isRenewable(uint256 tokenId)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>renewSubscription(uint256 tokenId, uint64 duration)</code> function MAY be implemented as <code>external</code> or <code>public</code>.</p> <p>The <code>cancelSubscription(uint256 tokenId)</code> function MAY be implemented as <code>external</code> or <code>public</code>.</p> <p>The <code>SubscriptionUpdate</code> event MUST be emitted whenever the expiration date of a subscription is changed.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0x8c65f84d</code>.</p> <h2 id="rationale">Rationale</h2> <p>This standard aims to make on-chain subscriptions as simple as possible by adding the minimal required functions and events for implementing on-chain subscriptions. It is important to note that in this interface, the NFT itself represents ownership of a subscription, there is no facilitation of any other fungible or non-fungible tokens.</p> <h3 id="subscription-management">Subscription Management</h3> <p>Subscriptions represent agreements to make advanced payments in order to receive or participate in something. In order to facilitate these agreements, a user must be able to renew or cancel their subscriptions hence the <code>renewSubscription</code> and <code>cancelSubscription</code> functions. It also important to know when a subscription expires - users will need this information to know when to renew, and applications need this information to determine the validity of a subscription NFT. The <code>expiresAt</code> function provides this functionality. Finally, it is possible that a subscription may not be renewed once expired. The <code>isRenewable</code> function gives users and applications that information.</p> <h3 id="easy-integration">Easy Integration</h3> <p>Because this standard is fully EIP-721 compliant, existing protocols will be able to facilitate the transfer of subscription NFTs out of the box. With only a few functions to add, protocols will be able to fully manage a subscription's expiration, determine whether a subscription is expired, and see whether it can be renewed.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard can be fully EIP-721 compatible by adding an extension function set.</p> <p>The new functions introduced in this standard add minimal overhead to the existing EIP-721 interface, which should make adoption straightforward and quick for developers.</p> <h2 id="test-cases">Test Cases</h2> <p>The following tests require Foundry.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.13</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;forge-std/Test.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../src/ERC5643.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC5643Mock</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC5643</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name_</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> symbol_</span><span>)</span><span class="z-entity z-name"> ERC5643</span><span>(</span><span>name_, symbol_) </span><span>{</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mint</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _mint</span><span>(</span><span>to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC5643Test</span><span class="z-storage"> is</span><span class="z-entity z-name"> Test</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SubscriptionUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> expiration</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span> user1</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> tokenId</span><span>;</span></span> <span class="giallo-l"><span> ERC5643Mock erc5643</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setUp</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> tokenId </span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span> user1 </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0x1</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> erc5643 </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> ERC5643Mock</span><span>(</span><span class="z-string">&quot;erc5369&quot;</span><span>,</span><span class="z-string"> &quot;ERC5643&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> erc5643</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span>user1</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> testRenewalValid</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">warp</span><span>(</span><span class="z-constant">1000</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">prank</span><span>(</span><span>user1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">expectEmit</span><span>(</span><span class="z-constant">true</span><span>,</span><span class="z-constant"> true</span><span>,</span><span class="z-constant"> false</span><span>,</span><span class="z-constant"> true</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> SubscriptionUpdate</span><span>(</span><span>tokenId</span><span>,</span><span class="z-constant"> 3000</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> erc5643</span><span>.</span><span class="z-entity z-name">renewSubscription</span><span>(</span><span>tokenId</span><span>,</span><span class="z-constant"> 2000</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> testRenewalNotOwner</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">expectRevert</span><span>(</span><span class="z-string">&quot;Caller is not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> erc5643</span><span>.</span><span class="z-entity z-name">renewSubscription</span><span>(</span><span>tokenId</span><span>,</span><span class="z-constant"> 2000</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> testCancelValid</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">prank</span><span>(</span><span>user1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">expectEmit</span><span>(</span><span class="z-constant">true</span><span>,</span><span class="z-constant"> true</span><span>,</span><span class="z-constant"> false</span><span>,</span><span class="z-constant"> true</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> SubscriptionUpdate</span><span>(</span><span>tokenId</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> erc5643</span><span>.</span><span class="z-entity z-name">cancelSubscription</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> testCancelNotOwner</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">expectRevert</span><span>(</span><span class="z-string">&quot;Caller is not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> erc5643</span><span>.</span><span class="z-entity z-name">cancelSubscription</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> testExpiresAt</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">warp</span><span>(</span><span class="z-constant">1000</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>erc5643</span><span>.</span><span class="z-entity z-name">expiresAt</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> vm</span><span>.</span><span class="z-entity z-name">startPrank</span><span>(</span><span>user1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> erc5643</span><span>.</span><span class="z-entity z-name">renewSubscription</span><span>(</span><span>tokenId</span><span>,</span><span class="z-constant"> 2000</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>erc5643</span><span>.</span><span class="z-entity z-name">expiresAt</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-constant"> 3000</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> erc5643</span><span>.</span><span class="z-entity z-name">cancelSubscription</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> assertEq</span><span>(</span><span>erc5643</span><span>.</span><span class="z-entity z-name">expiresAt</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>Implementation: <code>ERC5643.sol</code></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.13</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC721/ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC5643.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC5643</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IERC5643</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint64</span><span>)</span><span class="z-storage z-type"> private</span><span> _expirations</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name_</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> symbol_</span><span>)</span><span class="z-entity z-name"> ERC721</span><span>(</span><span>name_, symbol_) </span><span>{</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> renewSubscription</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> duration</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_isApprovedOrOwner</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;Caller is not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> currentExpiration </span><span class="z-keyword">=</span><span> _expirations</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> newExpiration</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>currentExpiration </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> newExpiration </span><span class="z-keyword">=</span><span class="z-support"> uint64</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>timestamp</span><span>)</span><span class="z-keyword"> +</span><span> duration</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span class="z-entity z-name">_isRenewable</span><span>(</span><span>tokenId</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> SubscriptionNotRenewable</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> newExpiration </span><span class="z-keyword">=</span><span> currentExpiration </span><span class="z-keyword">+</span><span> duration</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _expirations</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span> newExpiration</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> SubscriptionUpdate</span><span>(</span><span>tokenId</span><span>,</span><span> newExpiration</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelSubscription</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_isApprovedOrOwner</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;Caller is not owner nor approved&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _expirations</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> SubscriptionUpdate</span><span>(</span><span>tokenId</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> expiresAt</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint64</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _expirations</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRenewable</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC5643</span><span>)</span><span>.</span><span>interfaceId </span><span class="z-keyword">||</span><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This EIP standard does not affect ownership of an NFT and thus can be considered secure.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-09-09T00:00:00+00:00 2026-02-11T14:48:26+00:00 HonorLabshttps://github.com/honorworldio https://wg-eips.ritovision.com/5633/

Add composable soulbound property to EIP-1155 tokens

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>. It proposes a smart contract interface that can represent any number of soulbound and non-soulbound NFT types. Soulbound is the property of a token that prevents it from being transferred between accounts. This standard allows for each token ID to have its own soulbound property.</p> <h2 id="motivation">Motivation</h2> <p>The soulbound NFTs similar to World of Warcraft’s soulbound items are attracting more and more attention in the Ethereum community. In a real world game like World of Warcraft, there are thousands of items, and each item has its own soulbound property. For example, the amulate Necklace of Calisea is of soulbound property, but another low level amulate is not. This proposal provides a standard way to represent soulbound NFTs that can coexist with non-soulbound ones. It is easy to design a composable NFTs for an entire collection in a single contract.</p> <p>This standard outline a interface to EIP-1155 that allows wallet implementers and developers to check for soulbound property of token ID using <a href="https://wg-eips.ritovision.com/165/">EIP-165</a>. the soulbound property can be checked in advance, and the transfer function can be called only when the token is not soulbound.</p> <h2 id="specification">Specification</h2> <p>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> <p>A token type with a <code>uint256 id</code> is soulbound if function <code>isSoulbound(uint256 id)</code> returning true. In this case, all EIP-1155 functions of the contract that transfer the token from one account to another MUST throw, except for mint and burn.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5633</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when a token type `id` is set or cancel to soulbound, according to `bounded`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Soulbound</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> id</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> bounded</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns true if a token type `id` is soulbound.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isSoulbound</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Smart contracts implementing this standard MUST implement the EIP-165 supportsInterface function and MUST return the constant value true if 0x911ec470 is passed through the interfaceID argument.</p> <h2 id="rationale">Rationale</h2> <p>If all tokens in a contract are soulbound by default, <code>isSoulbound(uint256 id)</code> should return true by default during implementation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is fully EIP-1155 compatible.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are included in <a href="https://wg-eips.ritovision.com/5633/./assets/test/test.js">test.js</a>.</p> <p>Run in terminal:</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-support">cd</span><span class="z-string"> ../assets/eip-5633</span></span> <span class="giallo-l"><span class="z-entity z-name">npm</span><span class="z-string"> install</span></span> <span class="giallo-l"><span class="z-entity z-name">npx</span><span class="z-string"> hardhat</span><span class="z-string"> test</span></span></code></pre> <p>Test contract are included in <a href="https://wg-eips.ritovision.com/5633/./assets/contracts/ERC5633Demo.sol"><code>ERC5633Demo.sol</code></a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>See <a href="https://wg-eips.ritovision.com/5633/./assets/contracts/ERC5633.sol"><code>ERC5633.sol</code></a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no security considerations related directly to the implementation of this standard.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-09-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Yan Zhuhttps://github.com/diracdeltas Brian R. Bondyhttps://github.com/bbondy Andrea Brancaleonihttps://github.com/thypon Kyle Den Hartoghttps://github.com/kdenhartog https://wg-eips.ritovision.com/5593/

Wallet guidance for restricting Ethereum Provider API access to secure contexts for improved privacy and security for wallet users.

<h2 id="abstract">Abstract</h2> <p>Historically the web platform has had a notion of “powerful” APIs like those defined in W3C's Geolocation specification and W3C's Mediastreams specification, which are subject to additional security restrictions such as those defined by W3C's secure contexts specification. Since the Ethereum Provider APIs allow dApp websites to request access to sensitive user data and to request use of user funds, new Ethereum Provider APIs generally should align to the security considerations defined by W3C's Secure Context specification in order to better protect the users data and users funds managed via the web.</p> <h3 id="author-s-note">Author's Note</h3> <p>Unfortunately, because of a difference in interpretations by EIP editors of RFC 2119 terminology around linking in <a href="https://wg-eips.ritovision.com/1/">EIP-1</a>, the authors cannot directly link to other W3C specifications which this EIP builds upon. The author's attempted to provide as much context as possible within the text while complying with the editor bot in order to get this merged. If this policy is updated or further clarified before this EIP reaches final call in the future this EIP will be updated with links.</p> <h2 id="motivation">Motivation</h2> <p>Wallets are oftentimes maintaining security and safety of users' funds that can be equivalent to large portions of money. For this reason, it's a good idea to restrict access to the Ethereum Provider APIs to align it with other powerful APIs on the web platform. This will assist in reducing the surface area that attacks can be conducted to access users funds or data. Additionally, by adding in restrictions we're reducing the surface area that malicious web pages could fingerprint the user via the Ethereum Provider APIs providing some additional privacy benefits. An example of a specific attack that's avoided by this is one where a malicious advertisement is loaded on a legitimate dApp that attempts to interact with a users wallet to maliciously request the user to access funds. With this EIP implemented the advertisement frame would be considered a third-party iframe and therefore would not have the Ethereum Provider API injected into it's sub frame because it's not a secure context.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="restrictions-for-providers">Restrictions for providers</h3> <p>The provider objects, e.g. <code>window.ethereum</code>, are expected to only inject the Ethereum Provider APIs in secure context when conforming with this specification. The following restrictions are REQUIRED for conformant wallets:</p> <ul> <li>Provider objects MAY be accessible in private (incognito) windows.</li> <li>The origin MUST be a "potentially trustworthy origin" (defined in W3C's Secure Contexts specification in section 3.1) to have access to <code>window.ethereum</code>. This can be checked using <code>window.isSecureContext</code>, including inside iframes. <ul> <li>Secure contexts include sites that are served from HTTPS but also HTTP <code>localhost</code>.</li> <li>The User Agent implementation MAY also support configured [potentially trustworthy origins] that would normally not be considered trustworthy if the user configures their User Agent to do so. See section 7.2 titled "Development Environments" of W3C's Secure Contexts specification for additional details. For example, in Chromium based User Agents this is done via the <code>chrome://flags/#unsafely-treat-insecure-origin-as-secure</code> flag.</li> </ul> </li> <li>By default the Ethereum Provider APIs MUST NOT be exposed to third-party iframes.</li> <li><code>window.ethereum</code> MUST be <code>undefined</code> in an iframe where <code>window.isSecureContext</code> returns <code>false</code> in that iframe.</li> <li>If the iframe is a third party to the top-level secure origin, it SHOULD be blocked. Some implementations MAY provide a mechanism (e.g., via the <code>allow</code> attribute and Permissions API) for pages to request access, subject to user approval.</li> <li>If the iframe is first-party to the top-level origin AND the <code>sandbox</code> attribute is set on the iframe, the provider object MUST be blocked. If the <code>sandbox</code> attribute is set to <code>sandbox="allow-same-origin"</code> it MUST be injected for a first party frame. <ul> <li>Note <code>"allow-same-origin"</code> does nothing if the iframe is third-party. Third-party iframes SHOULD be blocked by default, but implementations MAY allow access through user-approved mechanisms such as the Permissions API.</li> </ul> </li> </ul> <h2 id="rationale">Rationale</h2> <p>By limiting the capabilities of where the Ethereum Provider APIs are being injected we can reduce the surface area of where attacks can be executed. Given the sensitivity of data that's passed to the Ethereum Provider APIs some basic levels of authentication and confidentiality should be met in order to ensure that request data is not being intercepted or tampered with. While there have been attempts to <a href="https://wg-eips.ritovision.com/2255/">limit request access via the wallet</a> interface itself, there have not been limitations that have been set to where these Ethereum Provider APIs are expected to be or not be injected. Since the secure contexts web platform API is a well developed boundary that's been recommended by W3C and the fact that the Ethereum Provider APIs are extending the traditional web platform APIs, no other alternative solutions have been considered in order to extend current established prior art.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Wallet extensions SHOULD consider adding a "developer mode" toggle via a UX so that dApp developers have the capability to disable the insecure context (http) check for the <code>http://localhost:&lt;any-port&gt;</code> origin only in the event that localhost does not return <code>true</code> for secure context. See section 5.2 of W3C's Secure Context specification for more details. This will allow dApp developers to be able to continue to host dApps on the localhost origin if a User Agent has chosen to not already consider localhost a secure context. All major User Agent implementations tested do consider localhost a secure context already. This toggle MUST be set to disabled by default.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="required-test-cases">Required Test Cases</h3> <ul> <li>Top level <code>http://a.com</code> -&gt; blocked (insecure/top level)</li> <li>Top level <code>https://a.com</code> -&gt; allowed</li> <li>Top level <code>https://a.com</code> with <code>&lt;iframe src="http://a.com/"&gt;</code> -&gt; blocked (insecure first party iframe)</li> <li>Top level <code>http://a.com</code> with <code>&lt;iframe src="https://a.com/"&gt;</code> -&gt; blocked (insecure top level window)</li> <li>Top level <code>https://a.com</code> with <code>&lt;iframe src="https://a.com"&gt;</code> -&gt; allowed</li> <li>Top level <code>https://a.com</code> with <code>&lt;iframe src="https://b.com"&gt;</code> -&gt; blocked (third-party iframe without sufficient privileges)</li> <li>Top level <code>https://b.com</code> with <code>&lt;iframe src="http://a.com/"&gt;</code> with <code>&lt;iframe src="https://b.com"&gt;</code> -&gt; blocked (insecure iframe)</li> <li>Top level <code>https://b.com</code> with <code>&lt;iframe src="https://a.com"&gt;</code> with <code>&lt;iframe src="https://b.com"&gt;</code> -&gt; blocked (third-party iframe without sufficient privileges)</li> <li>Top level <code>https://a.com</code> with <code>&lt;iframe src="https://sub.a.com"&gt;</code> -&gt; blocked (third-party iframe without sufficient privileges)</li> <li>Top level <code>https://a.com</code> with <code>&lt;iframe src="https://a.com" sandbox&gt;</code> -&gt; blocked (sandbox attribute without "allow-same-origin")</li> <li>Top level <code>https://a.com</code> with <code>&lt;iframe src="https://a.com" sandbox="allow-same-origin allow-scripts"&gt;</code> -&gt; allowed (Note this case is discouraged by User Agent implementer's such as Mozilla's MDN documents because it’d allow the iframe to remove its own <code>sandbox</code> attribute. See the <code>sandbox</code> attribute section of the iframes document in MDN for more details.)</li> <li>Top level <code>data://foo with &lt;iframe src="data://bar"&gt;</code> -&gt; blocked (insecure top level scheme)</li> <li>Top level <code>file://foo with &lt;iframe src="file://bar"&gt;</code> -&gt; blocked (third-party iframe)</li> <li>Top level <code>https://a.com</code> with <code>&lt;iframe src="https://b.com" sandbox="allow-same-origin allow-scripts"&gt;</code> -&gt; blocked (third-party iframe without sufficient privileges)</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <h3 id="user-enables-developer-mode">User Enables Developer Mode</h3> <p>Oftentimes developers require the ability to develop dApps locally in order to test their website and develop while hosting their dApp on <code>http://localhost</code>. In this case localhost would be blocked and compatibility issues would arise when developing a dApp locally. In order to increase compatibility for dApp developers a toggle to disable the check for the localhost can be considered. If this were to be extended beyond the localhost origin it could be used as a means to convince users to enable developer mode in order to subvert the guards put in place by this EIP. Therefore, implementations should be cautious when extending this developer toggle beyond the scope of the localhost origin.</p> <h3 id="privacy-considerations">Privacy Considerations</h3> <h4 id="web3-provider-fingerprinting">Web3 Provider Fingerprinting</h4> <p>Due to the nature of how the provider object is injected by default into most webpages, there's a risk that a malicious web page could utilize the provider object to fingerprint the user more precisely as a Web3 user. Implementers of this EIP are expected to consider the risks of injecting the Ethereum provider APIs into pages by default in order to consider what privacy characteristics they wish to enable for their users.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-09-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Omnus Sunmohttps://github.com/omnus https://wg-eips.ritovision.com/4886/

A proxy ownership register allowing trustless proof of ownership between Ethereum addresses, with delegated asset delivery

<h2 id="abstract">Abstract</h2> <p>A proxy protocol that allows users to nominate a proxy address to act on behalf of another wallet address, together with a delivery address for new assets. Smart contracts and applications making use of the protocol can take a proxy address and lookup holding information for the nominator address. This has a number of practical applications, including allowing users to store valuable assets safely in a cold wallet and interact with smart contracts using a proxy address of low value. The assets in the nominator are protected as all contract interactions take place with the proxy address. This eliminates a number of exploits seen recently where users' assets are drained through a malicious contract interaction. In addition, the register holds a delivery address, allowing new assets to be delivered directly to a cold wallet address.</p> <h2 id="motivation">Motivation</h2> <p>To make full use of Ethereum users often need to prove their ownership of existing assets. For example:</p> <ul> <li>Discord communities require users to sign a message with their wallet to prove they hold the tokens or NFTs of that community.</li> <li>Whitelist events (for example recent airdrops, or NFT mints), require the user to interact using a given address to prove eligibility.</li> <li>Voting in DAOs and other protocols require the user to sign using the address that holds the relevant assets.</li> </ul> <p>There are more examples, with the unifying theme being that the user must make use of the address with the assets to derive the platform benefit. This means the addresses holding these assets cannot be truly 'cold', and is a gift to malicious developers seeking to steal valuable assets. For example, a new project can offer free NFTs to holders of an existing NFT asset. The existing holders have to prove ownership by minting from the wallet with the asset that determined eligibility. This presents numerous possible attack vectors for a malicious developer who knows that all users interacting with the contract have an asset of that type.</p> <p>Possibly even more damaging is the effect on user confidence across the whole ecosystem. Users become reluctant to interact with apps and smart contracts for fear of putting their assets at risk. They may also decide not to store assets in cold wallet addresses as they need to prove they own them on a regular basis. A pertinent example is the user trying to decide whether to 'vault' their NFT and lose access to a discord channel, or keep their NFT in another wallet, or even to connect their 'vault' to discord.</p> <p>Ethereum is amazing at providing trustless proofs. The <em>only</em> time a user should need to interact using the wallet that holds an asset is if they intend to sell or transfer that asset. If a user merely wishes to prove ownership (to access a resource, get an airdrop, mint an NFT, or vote in a DAO), they should do this through a trustless proof stored on-chain.</p> <p>Furthermore, users should be able to decide where new assets are delivered, rather than them being delivered to the wallet providing the interaction. This allows hot wallets to acquire assets sent directly to a cold wallet 'vault', possibly even the one they are representing in terms of asset ownership.</p> <p>The aim of this EIP is to provide a convenient method to avoid this security concern and empower more people to feel confident leveraging the full scope of Ethereum functionality. Our vision is an Ethereum where users setup a new hardware wallet for assets they wish to hold long-term, then make one single contract interaction with that wallet: to nominate a hot wallet proxy. That user can always prove they own assets on that address, and they can specify it as a delivery address for new asset delivery.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="definitions">Definitions</h3> <ul> <li>Delivery address: The address that assets will be delivered to for the current Proxy Record, i.e. a new NFT minted by the Proxy address, representing the Nominator address, should be delivered to the Delivery address.</li> <li>Nomination: Where a Nominator has nominated a Proxy address. Will only be active when the Proxy has accepted the nomination.</li> <li>Nominator address: The address that proposes a proxy relationship. This address nominates another address to act as its proxy, representing it and its holdings in all interactions.</li> <li>Proxy address: The address that will represent a Nominator on-chain.</li> <li>Proxy Record: An active proxy relationship encompassing a Nominator, Proxy and Delivery.</li> <li>Register: The main EPS contract, which holds details of both Nominations and Proxy Records.</li> </ul> <h3 id="eps-specification">EPS Specification</h3> <p>There are two main parts to the register - a nomination and a proxy record:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Contract / Dapp Register</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Nominator: 0x1234.. Nominator: 0x1234..</span></span> <span class="giallo-l"><span>Proxy: 0x5678.. ---------&gt; Proxy: 0x4567..</span></span> <span class="giallo-l"><span> Delivery: 0x9876..</span></span></code></pre> <p>The first step to creating a proxy record is for an address to nominate another address as its proxy. This creates a nomination that maps the nominator (the address making the nomination) to the proposed proxy address.</p> <p>This is not a proxy record on the register at this stage, as the proxy address needs to first accept the nomination. Until the nomination is accepted it can be considered to be pending. Once the proxy address has accepted the nomination a proxy record is added to the register.</p> <p>When accepting a nomination the proxy address sets the delivery address for that proxy record. The proxy address remains in control of updating that delivery address as required. Both the nominator and proxy can delete the proxy record and nomination at any time. The proxy will continue forever if not deleted - it is eternal.</p> <p>The register is a single smart contract that stores all nomination and register records. The information held for each is as follows:</p> <ul> <li> <p>Nomination:</p> <ul> <li>The address of the Nominator</li> <li>The address of the Proposed Proxy</li> </ul> </li> <li> <p>Proxy Record:</p> <ul> <li>The address of the Nominator</li> <li>The address of the Proxy</li> <li>The delivery address for proxied deliveries</li> </ul> </li> </ul> <p>Any address can act as a Nominator or a Proxy. A Nomination must have been made first in order for an address to accept acting as a Proxy.</p> <p>A Nomination cannot be made to an address that is already active as either a Proxy or a Nominator, i.e. that address is already in an active proxy relationship.</p> <p>The information for both Nominations and Proxy records is held as a mapping. For the Nomination this is address =&gt; address for the Nominator to the Proxy address. For the Proxy Record the mapping is from address =&gt; struct for the Proxy Address to a struct containing the Nominator and Delivery address.</p> <p>Mapping between an address and its Nominator and Delivery address is a simple process as shown below:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Contract / Dapp Register</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> |------------- 0x4567..---------------&gt; |</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> | &lt;-------nominator: 0x1234..---------- |</span></span> <span class="giallo-l"><span> | delivery: 0x9876.. |</span></span> <span class="giallo-l"><span> | |</span></span></code></pre> <p>The protocol is fully backwards compatible. If it is passed an address that does not have an active mapping it will pass back the received address as both the Nominator and Delivery address, thereby preserving functionality as the address is acting on its own behalf.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Contract / Dapp Register</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> |------------- 0x0222..---------------&gt; |</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> | &lt;-------nominator: 0x0222..---------- |</span></span> <span class="giallo-l"><span> | delivery: 0x0222.. |</span></span> <span class="giallo-l"><span> | |</span></span></code></pre> <p>If the EPS register is passed the address of a Nominator it will revert. This is of vital importance. The purpose of the proxy is that the Proxy address is operating on behalf of the Nominator. The Proxy address therefore can derive the same benefits as the Nominator (for example discord roles based on the Nominator's holdings, or mint NFTs that require another NFT to be held). It is therefore imperative that the Nominator in an active proxy cannot also interact and derive these benefits, otherwise two addresses represent the same holding. A Nominator can of course delete the Proxy Record at any time and interact on it's own behalf, with the Proxy address instantly losing any benefits associated with the proxy relationship.</p> <h3 id="solidity-interface-definition">Solidity Interface Definition</h3> <p><strong>Nomination Exists</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function nominationExists(address _nominator) external view returns (bool);</span></span></code></pre> <p>Returns true if a Nomination exists for the address specified.</p> <p><strong>Nomination Exists for Caller</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function nominationExistsForCaller() external view returns (bool);</span></span></code></pre> <p>Returns true if a Nomination exists for the msg.sender.</p> <p><strong>Proxy Record Exists</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function proxyRecordExists(address _proxy) external view returns (bool);</span></span></code></pre> <p>Returns true if a Proxy Record exists for the passed Proxy address.</p> <p><strong>Proxy Record Exists for Caller</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function proxyRecordExistsForCaller() external view returns (bool);</span></span></code></pre> <p>Returns true if a Proxy Record exists for the msg.sender.</p> <p><strong>Nominator Record Exists</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function nominatorRecordExists(address _nominator) external view returns (bool);</span></span></code></pre> <p>Returns true if a Proxy Record exists for the passed Nominator address.</p> <p><strong>Nominator Record Exists for Caller</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function nominatorRecordExistsForCaller() external view returns (bool);</span></span></code></pre> <p>Returns true if a Proxy Record exists for the msg.sender.</p> <p><strong>Get Proxy Record</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getProxyRecord(address _proxy) external view returns (address nominator, address proxy, address delivery);</span></span></code></pre> <p>Returns Nominator, Proxy and Delivery address for a passed Proxy address.</p> <p><strong>Get Proxy Record for Caller</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getProxyRecordForCaller() external view returns (address nominator, address proxy, address delivery);</span></span></code></pre> <p>Returns Nominator, Proxy and Delivery address for msg.sender as Proxy address.</p> <p><strong>Get Nominator Record</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getNominatorRecord(address _nominator) external view returns (address nominator, address proxy, address delivery);</span></span></code></pre> <p>Returns Nominator, Proxy and Delivery address for a passed Nominator address.</p> <p><strong>Get Nominator Record for Caller</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getNominatorRecordForCaller() external view returns (address nominator, address proxy, address delivery);</span></span></code></pre> <p>Returns Nominator, Proxy and Delivery address for msg.sender address as Nominator.</p> <p><strong>Address Is Active</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function addressIsActive(address _receivedAddress) external view returns (bool);</span></span></code></pre> <p>Returns true if the passed address is Nominator or Proxy address on an active Proxy Record.</p> <p><strong>Address Is Active for Caller</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function addressIsActiveForCaller() external view returns (bool);</span></span></code></pre> <p>Returns true if msg.sender is Nominator or Proxy address on an active Proxy Record.</p> <p><strong>Get Nomination</strong></p> <p>function getNomination(address _nominator) external view returns (address proxy);</p> <p>Returns the proxy address for a Nomination when passed a Nominator.</p> <p><strong>Get Nomination for Caller</strong></p> <p>function getNominationForCaller() external view returns (address proxy);</p> <p>Returns the proxy address for a Nomination if msg.sender is a Nominator</p> <p><strong>Get Addresses</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getAddresses(address _receivedAddress) external view returns (address nominator, address delivery, bool isProxied);</span></span></code></pre> <p>Returns the Nominator, Proxy, Delivery and a boolean isProxied for the passed address. If you pass an address that is not a Proxy address it will return address(0) for the Nominator, Proxy and Delivery address and isProxied of false. If you pass an address that is a Proxy address it will return the relvant addresses and isProxied of true.</p> <p><strong>Get Addresses for Caller</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getAddressesForCaller() external view returns (address nominator, address delivery, bool isProxied);</span></span></code></pre> <p>Returns the Nominator, Proxy, Delivery and a boolean isProxied for msg.sender. If msg.sender is not a Proxy address it will return address(0) for the Nominator, Proxy and Delivery address and isProxied of false. If msg.sender is a Proxy address it will return the relvant addresses and isProxied of true.</p> <p><strong>Get Role</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getRole(address _roleAddress) external view returns (string memory currentRole);</span></span></code></pre> <p>Returns a string value with a role for the passed address. Possible roles are:</p> <p>None The address does not appear on the Register as either a Record or a Nomination.</p> <p>Nominator - Pending The address is the Nominator on a Nomination which has yet to be accepted by the nominated Proxy address.</p> <p>Nominator - Active The address is a Nominator on an active Proxy Record (i.e. the Nomination has been accepted).</p> <p>Proxy - Active The address is a Proxy on an active Proxy Record.</p> <p><strong>Get Role for Caller</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getRoleForCaller() external view returns (string memory currentRole);</span></span></code></pre> <p>Returns a string value with a role for msg.sender. Possible roles are:</p> <p>None The msg.sender does not appear on the Register as either a Record or a Nomination.</p> <p>Nominator - Pending The msg.sender is the Nominator on a Nomination which has yet to be accepted by the nominated Proxy address.</p> <p>Nominator - Active The msg.sender is a Nominator on an active Proxy Record (i.e. the Nomination has been accepted).</p> <p>Proxy - Active The msg.sender is a Proxy on an active Proxy Record.</p> <p><strong>Make Nomination</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function makeNomination(address _proxy, uint256 _provider) external payable;</span></span></code></pre> <p>Can be passed a Proxy address to create a Nomination for the msg.sender.</p> <p>Provider is a required argument. If you do not have a Provider ID you can pass 0 as the default EPS provider. For details on the EPS Provider Program please see .</p> <p><strong>Accept Nomination</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function acceptNomination(address _nominator, address _delivery, uint256 _provider) external;</span></span></code></pre> <p>Can be passed a Nominator and Delivery address to accept a Nomination for a msg.sender. Note that to accept a Nomination the Nomination needs to exists with the msg.sender as the Proxy. The Nominator passed to the function and that on the Nomination must match.</p> <p>Provider is a required argument. If you do not have a Provider ID you can pass 0 as the default EPS provider. For details on the EPS Provider Program please see .</p> <p><strong>Update Delivery Record</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function updateDeliveryAddress(address _delivery, uint256 _provider) external;</span></span></code></pre> <p>Can be passed a new Delivery address where the msg.sender is the Proxy on a Proxy Record.</p> <p>Provider is a required argument. If you do not have a Provider ID you can pass 0 as the default EPS provider. For details on the EPS Provider Program please see .</p> <p><strong>Delete Record by Nominator</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function deleteRecordByNominator(uint256 _provider) external;</span></span></code></pre> <p>Can be called to delete a Record and Nomination when the msg.sender is a Nominator.</p> <p>Note that when both a Record and Nomination exist both are deleted. If no Record exists (i.e. the Nomination hasn't been accepted by the Proxy address) the Nomination is deleted.</p> <p>Provider is a required argument. If you do not have a Provider ID you can pass 0 as the default EPS provider. For details on the EPS Provider Program please see .</p> <p><strong>Delete Record by Proxy</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function deleteRecordByProxy(uint256 _provider) external;</span></span></code></pre> <p>Can be called to delete a Record and Nomination when the msg.sender is a Proxy.</p> <h2 id="rationale">Rationale</h2> <p>The rationale for this EIP was to provide a way for all existing and future Ethereum assets to be have a 'beneficial owner' (the proxy) that is different to the address custodying the asset. The use of a register to achieve this ensures that changes to existing tokens are not required. The register stores a trustless proof, signed by both the nominator and proxy, that can be relied upon as a true representation of asset ownership.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The EIP is fully backwards compatible.</p> <h2 id="test-cases">Test Cases</h2> <p>The full SDLC for this proposal has been completed and it is operation at 0xfa3D2d059E9c0d348dB185B32581ded8E8243924 on mainnet, ropsten and rinkeby. The contract source code is validated and available on etherscan. The full unit test suite is available in <code>./assets/</code>, as is the source code and example implementations.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Please see <code>./assets/contracts</code></p> <h2 id="security-considerations">Security Considerations</h2> <p>The core intention of the EIP is to improve user security by better safeguarding assets and allowing greater use of cold wallet storage.</p> <p>Potential negative security implications have been considered and none are envisaged. The proxy record can only become operational when a nomination has been confirmed by a proxy address, both addresses therefore having provided signed proof.</p> <p>From a usability perspective the key risk is in users specifying the incorrect asset delivery address, though it is noted that this burden of accuracy is no different to that currently on the network.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-08-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Olivier Fernandezhttps://github.com/fernandezOli Frédéric Le Coidichttps://github.com/FredLC29 Julien Bérangerhttps://github.com/julienbrg https://wg-eips.ritovision.com/5560/

Makes an NFT redeemable for a physical object

<h2 id="abstract">Abstract</h2> <p>The EIP is a Redeemable NFT extension which adds a <code>redeem</code> function to <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>. It can be implemented when an NFT issuer wants his/her NFT to be redeemed for a physical object.</p> <h2 id="motivation">Motivation</h2> <p>An increasing amount of NFT issuers such as artists, fine art galeries, auction houses, brands and others want to offer a physical object to the holder of a given NFT. This standard allows EIP-721 NFTs to signal reedemability.</p> <h2 id="specification">Specification</h2> <p><em>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.</em></p> <p><code>EIP-721</code> compliant contracts MAY implement this EIP to provide a standard method of receiving information on redeemability.</p> <p>The NFT issuer <strong>MUST</strong> decide who is allowed to redeem the NFT, and restrict access to the <code>redeem()</code> function accordingly.</p> <p>Anyone <strong>MAY</strong> access the <code>isRedeemable()</code> function to check the redeemability status: it returns <code>true</code> when the NFT redeemable, and <code>false</code> when already redeemed.</p> <p>Third-party services that support this standard <strong>MAY</strong> use the <code>Redeem</code> event to listen to changes on the redeemable status of the NFT.</p> <p>Implementers of this standard <strong>MUST</strong> have all of the following functions:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;@openzeppelin/contracts/utils/introspection/ERC165.sol&#39;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Implementation of Redeemable for ERC-721s</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IRedeemable</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * ERC165 bytes to add to interface array - set in parent contract implementing this standard</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4 private constant _INTERFACE_ID_ERC721REDEEM = 0x2f8ca953;</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This event emits when a token is redeemed.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Redeem</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the redeem status of a token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier of the token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRedeemable</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Redeeem a token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier of the token to redeeem</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> redeem</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>Redeem</code> event is emitted when the <code>redeem()</code> function is called.</p> <p>The <code>supportsInterface</code> method <strong>MUST</strong> return <code>true</code> when called with <code>0x2f8ca953</code>.</p> <h2 id="rationale">Rationale</h2> <p>When the NFT contract is deployed, the <code>isRedeemable()</code> function returns <code>true</code> by default.</p> <p>By default, the <code>redeem()</code> function visibility is public, so anyone can trigger it. It is <strong>RECOMMENDED</strong> to add a <code>require</code> to restrict the access:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;ERC721Redeemable: You are not the owner of this token&quot;</span><span>)</span><span>;</span></span></code></pre> <p>After the <code>redeem()</code> function is triggered, <code>isRedeemable()</code> function returns <code>false</code>.</p> <h3 id="redeem-event"><code>Redeem</code> event</h3> <p>When the <code>redeem()</code> function is triggered, the following event <strong>MUST</strong> be emitted:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Redeem</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with EIP-721.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Here's an example of an EIP-721 that includes the Redeemable extension:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC721Redeemable</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">Redeemable</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> symbol</span><span>)</span><span class="z-entity z-name"> ERC721</span><span>(</span><span>name, symbol) </span><span>{</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRedeemable</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC721Redeemable: Redeem query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">isRedeemable</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> redeem</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC721Redeemable: Redeem query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;ERC721Redeemable: You are not the owner of this token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">redeem</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> override</span><span>(</span><span class="z-entity z-name">ERC721</span><span>,</span><span class="z-entity z-name"> Redeemable</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-08-26T00:00:00+00:00 2026-02-11T14:48:25+00:00 Philipp Boltehttps://github.com/strumswell Lauritz Leifermannhttps://github.com/lleifermann Dennis von der Beyhttps://github.com/DennisVonDerBey https://wg-eips.ritovision.com/5539/

Registry of revocation lists for revoking arbitrary data.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a set of methods and standards for a role-based registry of indicators aimed for usage in revocations.</p> <h2 id="motivation">Motivation</h2> <p>Revocation is a universally needed construct both in the traditional centralized and decentralized credential attestation. This EIP aims to provide an interface to standardize a decentralized approach to managing and resolving revocation states in a contract registry.</p> <p>The largest problem with traditional revocation lists is the centralized aspect of them. Most of the world's CRLs rely on HTTP servers as well as caching and are therefore vulnerable to known attack vectors in the traditional web space. This aspect severely weakens the underlying strong asymmetric key architecture in current PKI systems.</p> <p>In addition, issuers in existing CRL approaches are required to host an own instance of their public revocation list, as shared or centralized instances run the risk of misusage by the controlling entity. This incentivizes issuers to shift this responsibility to a third party, imposing the risk of even more centralization of the ecosystem (see Cloudflare, AWS). Ideally, issuers should be able to focus on their area of expertise, including ownership of their revocable material, instead of worrying about infrastructure.</p> <p>We see value in a future of the Internet where anyone can be an issuer of verifiable information. This proposal lays the groundwork for anyone to also own the lifecycle of this information to build trust in ecosystems.</p> <h2 id="specification">Specification</h2> <p>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> <p>This EIP specifies a contract called <code>EthereumRevocationRegistry</code> that is deployed once and may then be commonly used by everyone. By default, an Ethereum address <strong>MAY</strong> own and manage a multitude of revocation lists in a namespace that <strong>MUST</strong> contain the revocation states for a set of revocation keys.</p> <p>An owner of a namespace <strong>MAY</strong> allow delegates to manage one or more of its revocation lists. Delegates <strong>MUST</strong> be removable by the respective list's owner. In certain situations, an owner <strong>MAY</strong> also want to transfer a revocation list in a namespace and its management rights to a new owner.</p> <h3 id="definitions">Definitions</h3> <ul> <li><code>namespace</code>: A namespace is a representation of an Ethereum address inside the registry that corresponds to its owners address. All revocation lists within a namespace are initially owned by the namespace's owner address.</li> <li><code>revocation list</code>: A namespace can contain a number of revocation lists. Each revocation list is identified by a unique key of the type bytes32 that can be used to address it in combination with the namespace address.</li> <li><code>revocation key</code>: A revocation list can contain a number of revocation keys of the type bytes32. In combination with the namespace address and the revocation list key, it resolves to a boolean value that indicates whether the revocation key is revoked or not.</li> <li><code>owner</code>: An Ethereum address that has modifying rights to revocation lists within its own and possibly foreign namespaces. An owner can give up modifying rights of revocation lists within its namespace by transferring ownership to another address.</li> <li><code>delegate</code>: An Ethereum address that received temporary access to a revocation list in a namespace. It has to be granted by the current owner of the revocation list in question.</li> </ul> <h3 id="revocation-management">Revocation Management</h3> <h4 id="isrevoked">isRevoked</h4> <p><strong>MUST</strong> implement a function that returns the revocation status of a particular revocation key in a namespace's revocation list. It <strong>MAY</strong> also respect the revocation lists revocation status.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isRevoked</span><span>(</span><span class="z-support">address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> list</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> key</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="changestatus">changeStatus</h4> <p><strong>MUST</strong> implement a function to change the revocation status of a particular revocation key in a namespace's revocation list</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeStatus</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationKey</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="changestatussigned-see-meta-transactions">changeStatusSigned (<a href="https://wg-eips.ritovision.com/5539/#MetaTransactions">see Meta Transactions</a>)</h4> <p><strong>OPTIONAL</strong> implements a function to change the revocation status of a particular revocation key in a namespace's revocation list with a raw signature.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeStatusSigned</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationKey</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="changestatusdelegated">changeStatusDelegated</h4> <p><strong>OPTIONAL</strong> implements a function to change the revocation status of a particular revocation key in a namespace's revocation list by a revocation list's delegate.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeStatusDelegated</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationKey</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="changestatusdelegatedsigned-see-meta-transactions">changeStatusDelegatedSigned (<a href="https://wg-eips.ritovision.com/5539/#MetaTransactions">see Meta Transactions</a>)</h4> <p><strong>OPTIONAL</strong> implements a function to change the revocation status of a particular revocation key in a namespace's revocation list with a raw signature.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeStatusDelegatedSigned</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationKey</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="changestatusesinlist">changeStatusesInList</h4> <p><strong>OPTIONAL</strong> implements a function to change multiple revocation statuses in a namespace's revocation list at once.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeStatusesInList</span><span>(</span><span class="z-support">bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> revocationKeys</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="changestatusesinlistsigned-see-meta-transactions">changeStatusesInListSigned (<a href="https://wg-eips.ritovision.com/5539/#MetaTransactions">see Meta Transactions</a>)</h4> <p><strong>OPTIONAL</strong> implements a function to change multiple revocation statuses in a namespace's revocation list at once with a raw signature.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeStatusesInListSigned</span><span>(</span><span class="z-support">bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> revocationKeys</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="changestatusesinlistdelegated">changeStatusesInListDelegated</h4> <p><strong>OPTIONAL</strong> implements a function to change multiple revocation statuses in a namespace's revocation list at once by a revocation list's delegate.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeStatusesInListDelegated</span><span>(</span><span class="z-support">bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> revocationKeys</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="changestatusesinlistdelegatedsigned-see-meta-transactions">changeStatusesInListDelegatedSigned (<a href="https://wg-eips.ritovision.com/5539/#MetaTransactions">see Meta Transactions</a>)</h4> <p><strong>OPTIONAL</strong> implements a function to change multiple revocation statuses in a namespace's revocation list at once with a raw signature generated by a revocation list's delegate.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeStatusesInListDelegatedSigned</span><span>(</span><span class="z-support">bool</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> revocationKeys</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h3 id="revocation-list-management">Revocation List Management</h3> <h4 id=""></h4> <p><strong>OPTIONAL</strong> implements a function that returns the revocation status of a particular revocation list in a namespace.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> listIsRevoked</span><span>(</span><span class="z-support">address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="changeliststatus">changeListStatus</h4> <p><strong>OPTIONAL</strong> implements a function to change the revocation of a revocation list itself. If a revocation list is revoked, all its keys are considered revoked as well.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeListStatus</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="changeliststatussigned-see-meta-transactions">changeListStatusSigned (<a href="https://wg-eips.ritovision.com/5539/#MetaTransactions">see Meta Transactions</a>)</h4> <p><strong>OPTIONAL</strong> implements a function to change the revocation of a revocation list itself with a raw signature. If a revocation list is revoked, all its keys are considered revoked as well.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeListStatusSigned</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> revoked</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h3 id="owner-management">Owner management</h3> <h4 id="changelistowner">changeListOwner</h4> <p><strong>OPTIONAL</strong> implement a function to change the revocation status of a revocation list. If a revocation list is revoked, all keys in it are considered revoked.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeListOwner</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newOwner</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="changelistownersigned-see-meta-transactions">changeListOwnerSigned (<a href="https://wg-eips.ritovision.com/5539/#MetaTransactions">see Meta Transactions</a>)</h4> <p><strong>OPTIONAL</strong> implement a function to change the revocation status of a revocation list with a raw signature. If a revocation list is revoked, all keys in it are considered revoked.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeListOwnerSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newOwner</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h3 id="delegation-management">Delegation management</h3> <h4 id="addlistdelegate">addListDelegate</h4> <p><strong>OPTIONAL</strong> implements a function to add a delegate to an owner's revocation list in a namespace.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addListDelegate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> delegate</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="addlistdelegatesigned-see-meta-transactions">addListDelegateSigned (<a href="https://wg-eips.ritovision.com/5539/#MetaTransactions">see Meta Transactions</a>)</h4> <p><strong>OPTIONAL</strong> implements a function to add a delegate to an owner's revocation list in a namespace with a raw signature.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addListDelegateSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable"> delegate</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="removelistdelegate">removeListDelegate</h4> <p><strong>OPTIONAL</strong> implements a function to remove a delegate from an owner's revocation list in a namespace.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeListDelegate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> delegate</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h4 id="removelistdelegatesigned-see-meta-transactions">removeListDelegateSigned (<a href="https://wg-eips.ritovision.com/5539/#MetaTransactions">see Meta Transactions</a>)</h4> <p><strong>OPTIONAL</strong> implements a function to remove a delegate from an owner's revocation list in a namespace with a raw signature.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeListDelegateSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable"> delegate</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> namespace</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> revocationList</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h3 id="events">Events</h3> <h4 id="revocationstatuschanged">RevocationStatusChanged</h4> <p><strong>MUST</strong> be emitted when <code>changeStatus</code>, <code>changeStatusSigned</code>, <code>changeStatusDelegated</code>, <code>changeStatusDelegatedSigned</code>, <code>changeStatusesInList</code>, <code>changeStatusesInListSigned</code>, <code>changeStatusesInListDelegated</code>, or <code>changeStatusesInListDelegatedSigned</code> was successfully executed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> RevocationStatusChanged</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> namespace</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> revocationList</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> revocationKey</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> revoked</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="revocationlistownerchanged">RevocationListOwnerChanged</h4> <p><strong>MUST</strong> be emitted when <code>changeListOwner</code> or <code>changeListOwnerSigned</code> was successfully executed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> RevocationListOwnerChanged</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> namespace</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> revocationList</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newOwner</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="revocationlistdelegateadded">RevocationListDelegateAdded</h4> <p><strong>MUST</strong> be emitted when <code>addListDelegate</code> or <code>addListDelegateSigned</code> was successfully executed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> RevocationListDelegateAdded</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> namespace</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> revocationList</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> delegate</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="revocationlistdelegateremoved">RevocationListDelegateRemoved</h4> <p><strong>MUST</strong> be emitted when <code>removeListDelegate</code> or <code>removeListDelegateSigned</code> was successfully executed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> RevocationListDelegateRemoved</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> namespace</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> revocationList</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> delegate</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="revocationliststatuschanged">RevocationListStatusChanged</h4> <p><strong>MUST</strong> be emitted when <code>changeListStatus</code> or <code>changeListStatusSigned</code> was successfully executed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> RevocationListStatusChanged</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> namespace</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> revocationlist</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> revoked</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h3 id="meta-transactions">Meta Transactions <span id="MetaTransactions"></span></h3> <p>This section uses the following terms:</p> <ul> <li><strong><code>transaction signer</code></strong>: An Ethereum address that signs arbitrary data for the contract to execute <strong>BUT</strong> does not commit the transaction.</li> <li><strong><code>transaction sender</code></strong>: An Ethereum address that takes signed data from a <strong>transaction signer</strong> and commits it wrapped with its own signature to the smart contract.</li> </ul> <p>An address (<strong>transaction signer</strong>) <strong>MAY</strong> be able to deliver a signed payload off-band to another address (<strong>transaction sender</strong>) that initiates the Ethereum interaction with the smart contract. The signed payload <strong>MUST</strong> be limited to be used only once (<a href="https://wg-eips.ritovision.com/5539/#SignedHash">Signed Hash</a> + <a href="https://wg-eips.ritovision.com/5539/#Nonce">nonces</a>).</p> <h4 id="signed-hash">Signed Hash <span id="SignedHash"></span></h4> <p>The signature of the <strong>transaction signer</strong> <strong>MUST</strong> conform <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>. This helps users understand what the payload they're signing consists of &amp; it improves the protection against replay attacks.</p> <h4 id="nonce">Nonce <span id="Nonce"></span></h4> <p>This EIP <strong>RECOMMENDS</strong> the use of a <strong>dedicated nonce mapping</strong> for meta transactions. If the signature of the <strong>transaction sender</strong> and its meta contents are verified, the contract increases a nonce for this <strong>transaction signer</strong>. This effectively removes the possibility for any other sender to execute the same transaction again with another wallet.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-the-concept-of-namespaces">Why the concept of namespaces?</h3> <p>This provides every Ethereum address a reserved space, without the need to actively claim it in the contract. Initially addresses only have owner access in their own namespace.</p> <h3 id="why-does-a-namespace-always-represent-the-initial-owner-address">Why does a namespace always represent the initial owner address?</h3> <p>The change of an owner of a list shouldn't break the link to a revocation key in it, as already existing off-chain data may depend on it.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues were found.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="meta-transactions-1">Meta Transactions</h3> <p>The signature of signed transactions could potentially be replayed on different chains or deployed versions of the registry implementing this ERC. This security consideration is addressed by the usage of <a href="https://wg-eips.ritovision.com/712/">EIP-712</a></p> <h3 id="rights-management">Rights Management</h3> <p>The different roles and their inherent permissions are meant to prevent changes from unauthorized entities. The revocation list owner should always be in complete control over its revocation list and who has writing access to it.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-08-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jan Smržahttps://github.com/smrza David Rábelhttps://github.com/rabeles11 Tomáš Jančatomas.janca@jtbstorage.eu Jan Burešhttps://github.com/JohnyX89 DOBBYLABShttps://github.com/DOBBYLABS https://wg-eips.ritovision.com/5501/

Adds a conditional time-limited user role to EIP-721. This role can be delegated or borrowed.

<h2 id="abstract">Abstract</h2> <p>The following standard proposes an additional <code>user</code> role for <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>. This role grants the permission to use the NFT with no ability to transfer or set users. It has an expiry and a flag if the token is borrowed or not. <code>Owner</code> can delegate the NFT for usage to hot wallets or lend the NFT. If the token is borrowed, not even the owner can change the user until the status expires or both parties agree to terminate. This way, it is possible to keep both roles active at the same time.</p> <h2 id="motivation">Motivation</h2> <p>Collectibles, gaming assets, metaverse, event tickets, music, video, domains, real item representation are several among many NFT use cases. With <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> only the owner can reap the benefits. However, with most of the utilities it would be beneficial to distinguish between the token owner and its user. For instance music or movies could be rented. Metaverse lands could be delegated for usage.</p> <p>The two reasons why to set the user are:</p> <ul> <li><strong>delegation</strong> - Assign user to your hot wallet to interact with applications securely. In this case, the owner can change the user at any time.</li> <li><strong>renting</strong> - This use case comes with additional requirements. It is needed to terminate the loan once the established lending period is over. This is provided by <code>expires</code> of the user. It is also necessary to protect the borrower against resetting their status by the owner. Thus, <code>isBorrowed</code> check must be implemented to disable the option to set the user before the contract expires.</li> </ul> <p>The most common use cases for having an additional user role are:</p> <ul> <li><strong>delegation</strong> - For security reasons.</li> <li><strong>gaming</strong> - Would you like to try a game (or particular gaming assets) but are you unsure whether or not you will like it? Rent assets first.</li> <li><strong>guilds</strong> - Keep the owner of the NFTs as the multisig wallet and set the user to a hot wallet with shared private keys among your guild members.</li> <li><strong>events</strong> - Distinguish between <code>ownerOf</code> and <code>userOf</code>. Each role has a different access.</li> <li><strong>social</strong> - Differentiate between roles for different rooms. For example owner has read + write access while userOf has read access only.</li> </ul> <p>This proposal is a follow up on <a href="https://wg-eips.ritovision.com/4400/">EIP-4400</a> and <a href="https://wg-eips.ritovision.com/4907/">EIP-4907</a> and introduces additional upgrades for lending and borrowing which include:</p> <ul> <li><strong>NFT stays in owner's wallet during rental period</strong></li> <li><strong>Listing and sale of NFT without termination of the rent</strong></li> <li><strong>Claiming owner benefits during rental period</strong></li> </ul> <p>Building the standard with additional isBorrowed check now allows to create rental marketplaces which can set the user of NFT without the necessary staking mechanism. With current standards if a token is not staked during the rental period, the owner can simply terminate the loan by setting the user repeatedly. This is taken care of by disabling the function if the token is borrowed which in turn is providing the owner additional benefits. They can keep the token tied to their wallet, meaning they can still receive airdrops, claim free mints based on token ownership or otherwise use the NFT provided by third-party services for owners. They can also keep the NFT listed for sale. Receiving airdrops or free mints was previously possible but the owner was completely reliant on the implementation of rental marketplaces and their discretion.</p> <p>Decentralized applications can now differentiate between ownerOf and userOf while both statuses can coexist.</p> <h2 id="specification">Specification</h2> <p>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> <p><strong>Every compliant contract MUST implement the <code>IERC5501</code> interface. This extension is OPTIONAL for <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> contracts.</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> IERC5501: Rental &amp; Delegation NFT - EIP-721 Extension</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> the EIP-165 identifier for this interface is 0xf808ec37.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5501</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC721 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when the user of an NFT is modified.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UpdateUser</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _tokenId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _user</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> _expires</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> _isBorrowed</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Set the user info of an NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> User address cannot be zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * Only approved operator or NFT owner can set the user.</span></span> <span class="giallo-l"><span class="z-comment"> * If NFT is borrowed, the user info cannot be </span><span class="z-keyword">changed</span><span class="z-comment"> until user status expires.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> uint256 ID of the token to set user info for</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _user</span><span class="z-comment"> address of the new user</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _expires</span><span class="z-comment"> Unix timestamp when user info expires</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _isBorrowed</span><span class="z-comment"> flag whether or not the NFT is borrowed</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setUser</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _user</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable z-parameter z-function"> _expires</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _isBorrowed</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the user address of an NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Reverts if user is not set.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> uint256 ID of the token to get the user address for</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> address</span><span class="z-comment"> user address for this NFT</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the user expires of an NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> uint256 ID of the token to get the user expires for</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> uint64</span><span class="z-comment"> user expires for this NFT</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userExpires</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint64</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the user isBorrowed of an NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> uint256 ID of the token to get the user isBorrowed for</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> bool</span><span class="z-comment"> user isBorrowed for this NFT</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userIsBorrowed</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Every contract implementing the <code>IERC5501</code> interface is free to define the permissions of a <code>user</code>. However, user MUST NOT be considered an <code>owner</code>. They MUST NOT be able to execute transfers and approvals. Furthermore, <code>setUser</code> MUST be blocked from executing if <code>userIsBorrowed</code> returns <code>true</code> and <code>userExpires</code> is larger than or equal to <code>block.timestamp</code>.</p> <p>The <code>UpdateUser</code> event MUST be emitted when a <code>user</code> is changed.<br /> The <code>setUser(uint256 _tokenId, address _user, uint64 _expires, bool _isBorrowed)</code> function SHOULD <code>revert</code> unless the <code>msg.sender</code> is the <code>owner</code> or an approved operator. It MUST revert if a token is borrowed and status has not expired yet. It MAY be <code>public</code> or <code>external</code>.<br /> The <code>userOf(uint256 _tokenId)</code> function SHOULD revert if <code>user</code> is not set or expired.<br /> The <code>userExpires(uint256 _tokenId)</code> function returns a timestamp when user status expires.<br /> The <code>userIsBorrowed(uint256 _tokenId)</code> function returns whether NFT is borrowed or not.<br /> The <code>supportsInterface</code> function MUST return <code>true</code> when called with <code>0xf808ec37</code>.<br /> On every <code>transfer</code>, the <code>user</code> MUST be reset if the token is not borrowed. If the token is borrowed the <code>user</code> MUST stay the same.</p> <p><strong>The Balance extension is OPTIONAL. This gives the option to query the number of tokens a <code>user</code> has.</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> IERC5501Balance</span></span> <span class="giallo-l"><span class="z-comment"> * Extension for ERC5501 which adds userBalanceOf to query how many tokens address is userOf.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> the EIP-165 identifier for this interface is 0x0cb22289.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5501Balance</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC5501 </span><span class="z-comment">*/</span><span>{</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Count of all NFTs assigned to a user.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Reverts if user is zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _user</span><span class="z-comment"> an address for which to query the balance</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> the number of NFTs the user has</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _user</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>userBalanceOf(address _user)</code> function SHOULD <code>revert</code> for zero address.</p> <p><strong>The Enumerable extension is OPTIONAL. This allows to iterate over user balance.</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> IERC5501Enumerable</span></span> <span class="giallo-l"><span class="z-comment"> * This extension for ERC5501 adds the option to iterate over user tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> the EIP-165 identifier for this interface is 0x1d350ef8.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5501Enumerable</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC5501Balance, IERC5501 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Enumerate NFTs assigned to a user.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Reverts if user is zero address or _index &gt;= userBalanceOf(_owner).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _user</span><span class="z-comment"> an address to iterate over its tokens</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> the token ID for given index assigned to _user</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenOfUserByIndex</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _user</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _index</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>tokenOfUserByIndex(address _user, uint256 _index)</code> function SHOULD <code>revert</code> for zero address and <code>throw</code> if the index is larger than or equal to <code>user</code> balance.</p> <p><strong>The Terminable extension is OPTIONAL. This allows terminating the rent early if both parties agree.</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> IERC5501Terminable</span></span> <span class="giallo-l"><span class="z-comment"> * This extension for ERC5501 adds the option to terminate borrowing if both parties agree.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> the EIP-165 identifier for this interface is 0x6a26417e.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5501Terminable</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC5501 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when one party from borrowing contract approves termination of agreement.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _isLender</span><span class="z-comment"> true for lender, false for borrower</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AgreeToTerminateBorrow</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _tokenId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _party</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> _isLender</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when agreements to terminate borrow are reset.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ResetTerminationAgreements</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when borrow of token ID is terminated.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TerminateBorrow</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _tokenId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _lender</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _borrower</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _caller</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Agree to terminate a borrowing.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Lender must be ownerOf token ID. Borrower must be userOf token ID.</span></span> <span class="giallo-l"><span class="z-comment"> * If lender and borrower are the same, set termination agreement for both at once.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> uint256 ID of the token to set termination info for</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setBorrowTermination</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get if it is possible to terminate a borrow agreement.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> uint256 ID of the token to get termination info for</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> bool</span><span class="z-comment">, bool first indicates lender agrees, second indicates borrower agrees</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getBorrowTermination</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>,</span><span class="z-support"> bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Terminate a borrow if both parties agreed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Both parties must have agreed, otherwise revert.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> uint256 ID of the token to terminate borrow of</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> terminateBorrow</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>AgreeToTerminateBorrow</code> event MUST be emitted when either the lender or borrower agrees to terminate the rent.<br /> The <code>ResetTerminationAgreements</code> event MUST be emitted when a token is borrowed and transferred or <code>setUser</code> and <code>terminateBorrow</code> functions are called.<br /> The <code>TerminateBorrow</code> event MUST be emitted when the rent is terminated.<br /> The <code>setBorrowTermination(uint256 _tokenId)</code>. It MUST set an agreement from either party whichever calls the function. If the lender and borrower are the same address, it MUST assign an agreement for both parties at once.<br /> The <code>getBorrowTermination(uint256 _tokenId)</code> returns if agreements from both parties are <code>true</code> or <code>false</code>.<br /> The <code>terminateBorrow(uint256 _tokenId)</code> function MAY be called by anyone. It MUST <code>revert</code> if both agreements to terminate are not <code>true</code>. This function SHOULD change the <code>isBorrowed</code> flag from <code>true</code> to <code>false</code>.<br /> On every <code>transfer</code>, the termination agreements from either party MUST be reset if the token is borrowed.</p> <h2 id="rationale">Rationale</h2> <p>The main factors influencing this standard are:</p> <ul> <li><strong><a href="https://wg-eips.ritovision.com/4400/">EIP-4400</a> and <a href="https://wg-eips.ritovision.com/4907/">EIP-4907</a></strong></li> <li><strong>Allow lending and borrowing without the necessary stake or overcollateralization while owner retains ownership</strong></li> <li><strong>Leave the delegation option available</strong></li> <li><strong>Keep the number of functions in the interfaces to a minimum while achieving desired functionality</strong></li> <li><strong>Modularize additional extensions to let developers choose what they need for their project</strong></li> </ul> <h3 id="name">Name</h3> <p>The name for the additional role has been chosen to fit the purpose and to keep compatibility with EIP-4907.</p> <h3 id="ownership-retention">Ownership retention</h3> <p>Many collections offer their owners airdrops or free minting of various tokens. This is essentially broken if the owner is lending a token by staking it into a contract (unless the contract is implementing a way to claim at least airdropped tokens). Applications can also provide different access and benefits to owner and user roles in their ecosystem.</p> <h3 id="balance-and-enumerable-extensions">Balance and Enumerable extensions</h3> <p>These have been chosen as OPTIONAL extensions due to the complexity of implementation based on the fact that balance is less once user status expires and there is no immediate on-chain transaction to evaluate that. In both <code>userBalanceOf</code> and <code>tokenOfUserByIndex</code> functions there must be a way to determine whether or not user status has expired.</p> <h3 id="terminable-extension">Terminable extension</h3> <p>If the owner mistakenly sets a user with borrow status and expires to a large value they would essentially be blocked from setting the user ever again. The problem is addressed by this extension if both parties agree to terminate the user status.</p> <h3 id="security">Security</h3> <p>Once applications adopt the user role, it is possible to delegate ownership to hot wallet and interact with them with no fear of connecting to malicious websites.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with current <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> by adding an extension function set. The new functions introduced are similar to existing functions in EIP-721 which guarantees easy adoption by developers and applications. This standard also shares similarities to <a href="https://wg-eips.ritovision.com/4907/">EIP-4907</a> considering user role and its expiry which means applications will be able to determine the user if either of the standards is used.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases can be found in the reference implementation:</p> <ul> <li><a href="https://wg-eips.ritovision.com/5501/./assets/test/ERC5501Test.ts">Main contract</a></li> <li><a href="https://wg-eips.ritovision.com/5501/./assets/test/ERC5501BalanceTest.ts">Balance extension</a></li> <li><a href="https://wg-eips.ritovision.com/5501/./assets/test/ERC5501EnumerableTest.ts">Enumerable extension</a></li> <li><a href="https://wg-eips.ritovision.com/5501/./assets/test/ERC5501TerminableTest.ts">Terminable extension</a></li> <li><a href="https://wg-eips.ritovision.com/5501/./assets/test/ERC5501CombinedTest.ts">Scenario combined of all extensions</a></li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation is available here:</p> <ul> <li><a href="https://wg-eips.ritovision.com/5501/./assets/contracts/ERC5501.sol">Main contract</a></li> <li><a href="https://wg-eips.ritovision.com/5501/./assets/contracts/ERC5501Balance.sol">Balance extension</a></li> <li><a href="https://wg-eips.ritovision.com/5501/./assets/contracts/ERC5501Enumerable.sol">Enumerable extension</a></li> <li><a href="https://wg-eips.ritovision.com/5501/./assets/contracts/ERC5501Terminable.sol">Terminable extension</a></li> <li><a href="https://wg-eips.ritovision.com/5501/./assets/contracts/ERC5501Combined.sol">Solution combined of all extensions</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Developers implementing this standard and applications must consider all the permissions they give to users and owners. Since owner and user are both active roles at the same time, double-spending problem must be avoided. Balance extension must be implemented in such a way which will not cause any gas problems. Marketplaces should let users know if a token listed for sale is borrowed or not.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-08-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 liszechunghttps://github.com/liszechung https://wg-eips.ritovision.com/5505/

Extends EIP-1155 to support crucial operations for asset-backed NFTs

<h2 id="abstract">Abstract</h2> <p>To propose an extension of smart contract interfaces for asset-backed, fractionalized projects using the <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> standard such that total acquisition will become possible. This proposal focuses on physical asset, where total acquisition should be able to happen.</p> <h2 id="motivation">Motivation</h2> <p>Fractionalized, asset backed NFTs face difficulty when someone wants to acquire the whole asset. For example, if someone wants to bring home a fractionalized asset, he needs to buy all NFT pieces so he will become the 100% owner. However he could not do so as it is publicly visible that someone is trying to perform a total acquisition in an open environment like Ethereum. Sellers will take advantage to set unreasonable high prices which hinders the acquisition. Or in other cases, NFTs are owned by wallets with lost keys, such that the ownership will never be a complete one. We need a way to enable potential total acquisition.</p> <h2 id="specification">Specification</h2> <p>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> <p><a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> compliant contracts MAY implement this EIP for adding functionalities to support total acquisition.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment">set the percentage required for any acquirer to trigger a forced sale</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment">set also the payment token to settle for the acquisition</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setForcedSaleRequirement</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint128</span><span class="z-variable"> requiredBP</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> erc20Token</span></span> <span class="giallo-l"><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyOwner</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>//</span><span class="z-entity z-name">set</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> unit</span><span class="z-entity z-name"> price</span><span class="z-entity z-name"> to</span><span class="z-entity z-name"> acquire</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> remaining</span><span class="z-entity z-name"> NFTs</span><span> (</span><span class="z-entity z-name">100</span><span>% - </span><span class="z-entity z-name">requiredBP</span><span>)</span></span> <span class="giallo-l"><span>//</span><span class="z-entity z-name">suggest</span><span class="z-entity z-name"> to</span><span class="z-entity z-name"> use</span><span class="z-entity z-name"> a</span><span class="z-entity z-name"> Time</span><span class="z-entity z-name"> Weighted</span><span class="z-entity z-name"> Average</span><span class="z-entity z-name"> Price</span><span class="z-keyword"> for</span><span class="z-entity z-name"> a</span><span class="z-entity z-name"> certain</span><span class="z-entity z-name"> period</span><span class="z-entity z-name"> before</span><span class="z-entity z-name"> reaching</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> requiredBP</span></span> <span class="giallo-l"><span>//</span><span class="z-entity z-name">emit</span><span class="z-entity z-name"> ForcedSaleSet</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> setForcedSaleTWAP</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> amount</span></span> <span class="giallo-l"><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyOwner</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>//</span><span class="z-entity z-name">acquirer</span><span class="z-entity z-name"> deposit</span><span class="z-entity z-name"> remainingQTY</span><span>*</span><span class="z-entity z-name">TWAP</span></span> <span class="giallo-l"><span>//</span><span class="z-entity z-name">emit</span><span class="z-entity z-name"> ForcedSaleFinished</span></span> <span class="giallo-l"><span>//</span><span class="z-entity z-name">after</span><span class="z-variable z-language"> this</span><span class="z-entity z-name"> point</span><span>,</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> acquirer</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> new</span><span class="z-entity z-name"> owner</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> whole</span><span class="z-entity z-name"> asset</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> execForcedSale</span><span> (</span></span> <span class="giallo-l"><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> amount</span></span> <span class="giallo-l"><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>//</span><span class="z-entity z-name">burn</span><span class="z-entity z-name"> ALL</span><span class="z-entity z-name"> NFTs</span><span class="z-entity z-name"> and</span><span class="z-entity z-name"> collect</span><span class="z-entity z-name"> funds</span></span> <span class="giallo-l"><span>//</span><span class="z-entity z-name">emit</span><span class="z-entity z-name"> ForcedSaleClaimed</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> claimForcedSale</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type">public</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">event</span><span class="z-entity z-name"> ForcedSaleSet</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> bool</span><span class="z-entity z-name"> isSet</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">event</span><span class="z-entity z-name"> ForceSaleClaimed</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> qtyBurned</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> amountClaimed</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> address</span><span class="z-entity z-name"> claimer</span></span> <span class="giallo-l"><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Native ETH is supported by via Wrapped Ether <a href="https://wg-eips.ritovision.com/20/">EIP-20</a>. After forcedSale is set, the remaining NFTs metadata should be updated to reflect the NFTs are at most valued at the previously set TWAP price.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The major security risks considered include</p> <ul> <li>The execution of the forcedSale is only executed by the contract owner, after a governance proposal. If there is any governance attack, the forcedSale TWAP price might be manipulated on a specific timing. The governance structure for using this extension should consider adding a <strong>council</strong> to safeguard the fairness of the forcedSale.</li> <li>Payment tokens are deposited into the contract account when forcedSale is executed. These tokens will then await the minority holders to withdraw on burning the NFT. There might be a potential security risk.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-08-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Qi Zhouhttps://github.com/qizhou https://wg-eips.ritovision.com/5478/

Reducing the gas cost of contract creation with existing code

<h2 id="abstract">Abstract</h2> <p>Adding a new opcode, <code>CREATE2COPY</code>, that is identical to <code>CREATE2</code> but with potentially much lower gas cost by accepting an additional argument <code>existing_contract_address</code> that already stored the code of the new contract.</p> <h2 id="motivation">Motivation</h2> <p>This EIP aims to reduce the smart contract creation cost of account abstraction (AA) contracts that have identical code.</p> <p>The major cost of creating an AA contract is the contract creation cost, especially data gas. For example, creating an AA contract with 10,000 bytes will consume 2,000,000 data gas. Considering the code for each user's AA contract is the same, <code>CREATE2COPY</code> can reduce the data gas cost to 2600 (cold account) or even 100 (warm account) if the contract code already exists in the local storage.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLKNUM</code></td><td>TBD</td></tr> <tr><td><code>CREATE_DATA_GAS_PER_BYTE</code></td><td>200</td></tr> <tr><td><code>COLD_ACCOUNT_ACCESS_COST</code></td><td>2600</td></tr> <tr><td><code>WARM_ACCOUNT_ACCESS_COST</code></td><td>100</td></tr> </tbody></table> <p>If <code>block.number &gt;= FORK_BLKNUM</code>, a new opcode is added (<code>CREATE2COPY</code>) at <code>0xf6</code>, which takes 5 stack arguments: <code>endowment</code>, <code>memory_start</code>, <code>memory_length</code>, <code>salt</code>, <code>existing_contract_address</code>. <code>CREATE2COPY</code> behaves identically to <code>CREATE2</code> (<code>0xf5</code> as defined in <a href="https://wg-eips.ritovision.com/1014/">EIP-1014</a>), except that the code hash of the creating contract MUST be the same as that of <code>existing_contract_address</code>.</p> <p><code>CREATE2COPY</code> has the same <code>gas</code> schema as <code>CREATE2</code>, but replacing the data gas from <code>CREATE_DATA_GAS_PER_BYTE * CONTRACT_BYTES</code> to the gas cost of <code>EXTCODEHASH</code> opcode, which is <code>COLD_ACCOUNT_ACCESS_COST</code> if the <code>existing_contract_address</code> is first-time accessed in the transaction or <code>WARM_ACCOUNT_ACCESS_COST</code> if <code>existing_contract_address</code> is already in the access list according to <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>.</p> <p>If the code of the contract returned from the init code differs from that of <code>existing_contract_address</code>, the creation fails with the error "mismatched contract creation code with existing code", and will burn all gas for the contract creation.</p> <h2 id="rationale">Rationale</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-08-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Roy Osherovehttps://github.com/royosherove https://wg-eips.ritovision.com/5553/

A way of representing intellectual property and its respective royalty structure on chain

<h2 id="abstract">Abstract</h2> <p>This proposal introduces a generic way to represent intellectual property on chain, along with a refined royalty representation mechanism and associated metadata link. This standard is not associated with a specific type of IP and could represent many types of IP, such as musical IP, videos, books, images, and more. The standard is kept very generic to allow the industry to evolve new ecosystems that can all rely on the same basic standard at their core.</p> <p>This standard allows market participants to:</p> <ol> <li>Observe the canonical on-chain representation of an intellectual property</li> <li>Discover its attached metadata</li> <li>Discover its related royalty structure</li> <li>This will enable building registration, licensing, and payout mechanisms for intellectual property assets in the future.</li> </ol> <h2 id="motivation">Motivation</h2> <p>There is no accepted standard mechanism to license intellectual property or to represent it, except using traditional NFTs. However, regular NFTs only represent a collectible item use case and cannot easily represent more complicated use cases of licensing IP for different types of uses. We can enable such licensing mechanisms if we can:</p> <ol> <li>Declare that IP exists, SEPARATELY from its purchase ability</li> <li>Declare possibly multiple interested parties to be paid for such IP</li> </ol> <p>For 1, no standard exists today.</p> <p>For 2, traditional split standards exist based on NFT purchases or through mechanisms like 0xsplits. While these solve the main problem, they do not contain the ability to name multiple types of collaboration participants.</p> <h2 id="specification">Specification</h2> <p>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> <p><strong>contracts that want to represent IP on chain MUST implement <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> AND this Proposal</strong></p> <p>This standard extends <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> with the following <code>IIPRepresentation</code> (IPR for short) interface. Implementers of this standard <strong>MUST</strong> have all of the following functions:</p> <h3 id="royaltyportiontokens-function">royaltyPortionTokens() function</h3> <p>This function MUST return an array of addresses related to <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> tokens that MUST represent royalty portions to different types of interested parties. These royalty portion tokens represent a more granular and streamlined way to declare royalty splits for multiple collaboration participants for the creation of the IP.</p> <p>For example, for a musical IP, we might have two tokens representing the composition/writing/publishing royalty portion side and the recording/master side. These royalty portion tokens are distributed to the collaboration participants and can later be queried by the various holders to distribute royalties. I.e., if one holds 10% of a royalty portion token, that holder will get 10% of the financial distribution related to that type of royalty.</p> <h3 id="metadatauri-function">metadataURI() function</h3> <p>This function MUST return the URI to a metadata file containing any required metadata for the IP or an empty string. Each IP type MAY implement its metadata standard, defined separately. The file MUST be hosted in IPFS, Arweave, or other decentralized content-addressable systems in which the file's contents are not changeable without changing the URI.</p> <h3 id="changemetadatauri-function">changeMetadataURI() function</h3> <p>This function allows changing the metadata URI to point to a new version of the metadata file. Calling this function MUST trigger the event <code>MetadataChanged</code> in case of success.</p> <h3 id="ledger-function">ledger() function</h3> <p>This function MUST return the registry or registrar contract address or an EOA account that initialized the IP and associated royalty tokens. An IP representation MAY be registered in multiple places by different actors for different purposes. This function enables market participants to discover which registry mechanism is the parent of the IP and might have special access rights to manage the IP.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.9</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;@openzeppelin/contracts/interfaces/IERC165.sol&#39;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface for Intellectual Property Representation</span></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IIPRepresentation</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Called with the new URI to an updated metadata file</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _newUri</span><span class="z-comment"> - the URI pointing to a metadata file (file standard is up to the implementer)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _newFileHash</span><span class="z-comment"> - The hash of the new metadata file for future reference and verification</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> changeMetadataURI</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _newUri</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _newFileHash</span><span>)</span><span class="z-storage z-type"> external</span><span> ;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> array</span><span class="z-comment"> of addresses of ERC20 tokens representing royalty portion in the IP</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> i.e implementing ERC5501 (IRoyaltyInterestToken interface)</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> royaltyPortionTokens</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span> ;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> address of the contract or EOA that initialized the IP registration</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> i.e., a registry or registrar, to be implemented in the future</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ledger</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> ;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> URI of the current metadata file for the II P</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> metadataURI</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span> ;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> event to be triggered whenever metadata URI is </span><span class="z-keyword">changed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> byAddress</span><span class="z-comment"> the addresses that triggered this operation</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> oldURI</span><span class="z-comment"> the URI to the old metadata file before the change</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> oldFileHash</span><span class="z-comment"> the hash of the old metadata file before the change</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> newURI</span><span class="z-comment"> the URI to the new metadata file </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> newFileHash</span><span class="z-comment"> the hash of the new metadata file </span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MetadaDataChanged</span><span>(</span><span class="z-support">address</span><span class="z-variable"> byAddress</span><span>, </span><span class="z-support">string</span><span class="z-variable"> oldURI</span><span>, </span><span class="z-support">string</span><span class="z-variable"> oldFileHash</span><span>, </span><span class="z-support">string</span><span class="z-variable"> newURI</span><span>, </span><span class="z-support">string</span><span class="z-variable"> newFileHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="returning-an-array-of-eip-20-tokens-presents-a-more-robust-royalty-portions-structure">Returning an array of EIP-20 tokens presents a more robust royalty portions structure/</h3> <p>Current royalty implementations deal only with a single type of royalty payment: NFT sales. They also only allow a single type of royalty - i.e., Music NFTs cannot pay different people in different scenarios. In other words, currently, a royalty split works the same way no matter what type of purchase or license deal has happened for all parties involved.</p> <p>With this proposal, multiple <strong>types</strong> of royalty scenarios are allowed. A classic case is the music industry, in which we have writing/composition royalties and recording/master royalties. Different licensing types will pay different percentages to different parties based on context.</p> <p>In the case of a song cover, a license payment formula can be created so that that a) Original IP's writers get paid for using the lyrics or composition of the song b) recording artists of the original song do not get paid since their recording is not used c) recording artists of the new IP will get paid d) there are no writing royalties for the creators of the cover.</p> <p>Moreover, this EIP has a single structure that connects to all types of royalty types and allows finding them more easily. Lastly, moving EIP-20 tokens around is much easier than managing an 0xsplits contract.</p> <h3 id="separating-the-ip-contract-from-the-collectible-and-licensing-nfts-enables-scaling-licensing-types">Separating the IP contract from the collectible and licensing NFTs enables scaling licensing types</h3> <p>By separating the canonical version of the IP from its various licensed uses (NFT purchase, streaming, usage of art and more.), this EIP introduces a path for an ecosystem of various license types and payment distributions to evolve. In other words, when people use this scheme, they will not start by creating a music NFT or art NFT; they start by creating the IP Representation and then create types of licenses or collectibles for it, each as its own sellable NFT.</p> <h3 id="a-single-pointer-to-the-ip-s-metadata">A single pointer to the IP's metadata</h3> <p>The IPR points to metadata housed in IPFS or Arweave and allows changing it and keeping track of the changes in a simple and standard way. Today the only metadata standard is NFT metadata extension, but it is impossible to know to which standard the document adheres. With different IP types, different metadata standards for different IP types can be formulated and have a simple, easy place to discover attached metadata.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h4 id="implementing-a-musical-ip-representation-mipr-for-short-based-on-iiprepresentation">Implementing a Musical IP Representation (MIPR for short) based on IIPRepresentation</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.9</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;@openzeppelin/contracts/token/ERC721/ERC721.sol&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./interfaces/IIPRepresentation.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./interfaces/Structs.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> MusicalIP</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">IIPRepresentation</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> songLedger</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> compToken</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> recToken</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span> metadataURI</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span> fileHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> tokenId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-storage z-type"> public</span><span> activated </span><span class="z-keyword">=</span><span class="z-constant">false</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span>(</span><span class="z-entity z-name"> ERC721</span><span>,</span><span class="z-entity z-name"> IERC165</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IIPRepresentation</span><span>)</span><span>.</span><span>interfaceId </span><span class="z-keyword">||</span></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getInterfaceId</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-language"> type</span><span>(</span><span>IIPRepresentation</span><span>)</span><span>.</span><span>interfaceId</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _songLedger</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> SongMintingParams</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _params</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _compAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _recAddress</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC721</span><span>(</span><span>_params.shortName, _params.symbol)</span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> songLedger </span><span class="z-keyword">=</span><span> _songLedger</span><span>;</span></span> <span class="giallo-l"><span> compToken </span><span class="z-keyword">=</span><span> _compAddress</span><span>;</span></span> <span class="giallo-l"><span> recToken </span><span class="z-keyword">=</span><span> _recAddress</span><span>;</span></span> <span class="giallo-l"><span> metadataURI </span><span class="z-keyword">=</span><span> _params</span><span>.</span><span>metadataUri</span><span>;</span></span> <span class="giallo-l"><span> fileHash </span><span class="z-keyword">=</span><span> _params</span><span>.</span><span>fileHash</span><span>;</span></span> <span class="giallo-l"><span> tokenId </span><span class="z-keyword">=</span><span> _tokenId</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-entity z-name"> _safeMint</span><span>(</span><span>_songLedger</span><span>,</span><span> _tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Minted</span><span>(</span><span>_params</span><span>.</span><span>shortName</span><span>,</span><span>_songLedger</span><span>,</span><span>_compAddress</span><span>,</span><span>_recAddress</span><span>,</span><span class="z-entity z-name">_msgSender</span><span>(</span><span>)</span><span>,</span><span>tokenId</span><span>,</span><span>_params</span><span>.</span><span>metadataUri</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> changeMetadataURI</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _newURI</span><span>,</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _newFileHash</span><span>)</span><span class="z-storage z-type"> public</span><span> </span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> oldURI </span><span class="z-keyword">=</span><span> metadataURI</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> oldHash </span><span class="z-keyword">=</span><span> fileHash</span><span>;</span></span> <span class="giallo-l"><span> metadataURI </span><span class="z-keyword">=</span><span> _newURI</span><span>;</span><span> </span></span> <span class="giallo-l"><span> fileHash </span><span class="z-keyword">=</span><span> _newFileHash</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> MetadataChanged</span><span>(</span><span>oldURI</span><span>,</span><span> oldHash</span><span>,</span><span>_newURI</span><span>,</span><span>_newFileHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> royaltyPortionTokens</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> items </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> address</span><span>[](</span><span class="z-constant">2</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span> items</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</span><span> compToken</span><span>;</span></span> <span class="giallo-l"><span> items</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> =</span><span> recToken</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> items</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ledger</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> songLedger</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MetadataChanged</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> oldUri</span><span>, </span><span class="z-support">string</span><span class="z-variable"> oldFileHash</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> newUri</span><span>, </span><span class="z-support">string</span><span class="z-variable"> newFileHash</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Minted</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> abbvName</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> ledger</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> compToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> recToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> creator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> metadataUri</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"></span></code></pre><h4 id="deploying-a-new-musical-ip-using-a-simple-song-registry-contract">Deploying a new Musical IP using a simple song registry contract</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.9</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/Counters.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./MusicalIP.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./CompositionRoyaltyToken.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./RecordingRoyaltyToken.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> SimpleSongLedger</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC721Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> Counters</span><span class="z-keyword"> for</span><span class="z-entity z-name"> Counters</span><span>.</span><span>Counter</span><span>;</span></span> <span class="giallo-l"><span> Counters</span><span>.</span><span>Counter </span><span class="z-storage z-type">private</span><span> mipIds</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onERC721Received</span><span>(</span><span class="z-support">address</span><span>,</span><span class="z-support"> address</span><span>,</span><span class="z-support"> uint256</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> IERC721Receiver</span><span>.</span><span>onERC721Received</span><span>.</span><span>selector</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintSong</span><span>(</span><span class="z-storage z-type">SongMintingParams</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _params</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> CompositionRoyaltyToken comp </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> CompositionRoyaltyToken</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-string">&quot;SONGCOMP&quot;</span><span>,</span><span class="z-string">&quot;COMP&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> RecordingRoyaltyToken rec </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> RecordingRoyaltyToken</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-string">&quot;SONGREC&quot;</span><span>,</span><span class="z-string">&quot;REC&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> mipIds</span><span>.</span><span class="z-entity z-name">increment</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> MusicalIP mip </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-entity z-name"> MusicalIP</span><span>(</span></span> <span class="giallo-l"><span> mipIds</span><span>.</span><span class="z-entity z-name">current</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> _params</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span>comp</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span>rec</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>There might be potential security challenges of attackers persuading holders of royalty portion tokens to send them those tokens and gaining royalty portion in various IPRs. However, these are not specific to royalties and are a common issue with EIP-20 tokens.</p> <p>In the case of the IP registration ownership, it will be recommended that registry contracts own the IP registration, which will be non-transferrable (account bound to the registry that created it).</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-08-12T00:00:00+00:00 2026-02-11T14:49:28+00:00 Andrei Maiborodahttps://github.com/gumb0 Paweł Bylicahttps://github.com/chfast Alex Beregszaszihttps://github.com/axic Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/5450/

Deploy-time validation of stack usage for EOF functions.

<h2 id="abstract">Abstract</h2> <p>Introduce extended validation of EOF code sections to guarantee that neither stack underflow nor overflow can happen during execution of validated contracts.</p> <h2 id="motivation">Motivation</h2> <p>The current EVM performs a number of validity checks for each executed instruction, such as checking for instruction being defined, stack overflow and underflow, and enough amount of gas remaining.</p> <p>This EIP minimizes the number of such checks required at run-time by verifying that no exceptional conditions can happen and preventing the execution and deployment of any invalid code.</p> <p>The operand stack validation provides several benefits:</p> <ul> <li>removes the run-time stack underflow check for all instructions,</li> <li>removes the run-time stack overflow check for all instructions except <code>CALLF</code> and <code>JUMPF</code> (<code>JUMPF</code> introduced in a separate EIP) ,</li> <li>ensures that execution terminates with one of the terminating instructions,</li> <li>prevents deployment of code with unreachable instructions, thereby discouraging the use of code sections for data storage.</li> </ul> <p>It also has some disadvantages:</p> <ul> <li>adds constraints to the code structure (similar to JVM, CPython bytecode, WebAssembly, SPIR-V and others); however, these constraints can be lifted in a backward-compatible manner if they are shown to be user-unfriendly,</li> <li>it is natural to implement stack validation as a second validation pass; however, it is not strictly required and validation's computational and space complexity remains linear in any implementation variant.</li> </ul> <p>The guarantees created by these validation rules also improve the feasibility of Ahead-Of-Time and Just-In-Time compilation of EVM code. Single pass transpilation passes can be safely executed with the code validation and advanced stack/register handling can be applied with the stack height validations. While not as impactful to a Mainnet validator node that is bound mostly by storage state sizes, these can significantly speed up witness validation and other non-Mainnet use cases.</p> <h2 id="specification">Specification</h2> <h3 id="code-validation">Code validation</h3> <p><em>Remark:</em> We rely on the notions of <em>operand stack</em> and <em>type section</em> as defined by <a href="https://wg-eips.ritovision.com/4750/">EIP-4750</a>.</p> <p>Each code section is validated independently.</p> <h4 id="instructions-validation">Instructions validation</h4> <p>In the first validation phase defined in <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a> (and extended by <a href="https://wg-eips.ritovision.com/4200/">EIP-4200</a> and <a href="https://wg-eips.ritovision.com/4750/">EIP-4750</a>) instructions are inspected independently to check if their opcodes and immediate values are valid.</p> <h4 id="operand-stack-validation">Operand stack validation</h4> <p>In the second validation phase control-flow analysis is performed on the code.</p> <p><em>Operand stack height</em> here refers to the number of stack values accessible by this function, i.e. it does not take into account values of caller functions' frames (but does include this function's inputs). Note that validation procedure does not require actual operand stack implementation, but only to keep track of its height.</p> <p><em>Terminating instructions</em> refers to the instructions either:</p> <ul> <li>ending function execution: <code>RETF</code>, <code>JUMPF</code>, or</li> <li>ending call frame execution: <code>STOP</code>, <code>RETURN</code>, <code>RETURNCODE</code>, <code>REVERT</code>, <code>INVALID</code>.</li> </ul> <p><em>note: <code>JUMPF</code> and <code>RETURNCODE</code> are introduced in separate EIPs.</em></p> <p><em>Forward jump</em> refers to any of <code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> instruction with relative offset greater than or equal to 0. <em>Backwards jump</em> refers to any of <code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> instruction with relative offset less than 0, including jumps to the same jump instruction.</p> <p>Instructions in the code are scanned in a single linear pass over the code. For each instruction the operand stack height bounds are recorded as <code>stack_height_min</code> and <code>stack_height_max</code>.</p> <p>The first instruction's recorded stack height bounds are initialized to be equal to the number of inputs to the function type matching the code (<code>stack_height_min = stack_height_max = type[code_section_index].inputs</code>).</p> <p>For each instruction:</p> <ol> <li><strong>Check</strong> if this instruction has recorded stack height bounds. If it does not, it means it was neither referenced by previous forward jump, nor is part of sequential instruction flow, and this code fails validation. <ul> <li>It is a prerequisite to validation algorithm, and code generators are required to order code basic blocks in a way that no block is referenced only by backwards jump. Any program can satisfy this requirement by ordering code basic blocks by the reverse postorder.</li> </ul> </li> <li>Determine the effect the instruction has on the operand stack: <ol> <li><strong>Check</strong> if the recorded stack height bounds satisfy the instruction requirements. Specifically: <ul> <li>for <code>CALLF</code> instruction the recorded stack height lower bound must be at least the number of inputs of the called function according to its type defined in the type section,</li> <li>for <code>RETF</code> instruction both the recorded lower and upper bound must be equal and must be exactly the number of outputs of the function matching the code,</li> <li>for <code>JUMPF</code> into returning function both the recorded lower and upper bound must equal exactly <code>type[current_section_index].outputs + type[target_section_index].inputs - type[target_section_index].outputs</code>,</li> <li>for <code>JUMPF</code> into non-returning function the recorded stack height lower bound must be at least the number of inputs of the target function according to its type defined in the type section,</li> <li>for any other instruction the recorded stack height lower bound must be at least the number of inputs required by instruction,</li> <li>there is no additional check for terminating instructions other than <code>RETF</code> and <code>JUMPF</code>, this implies that extra items left on stack at instruction ending EVM execution are allowed.</li> </ul> </li> <li>For <code>CALLF</code> and <code>JUMPF</code> <strong>check</strong> for possible stack overflow: if recorded stack height upper bound is greater than <code>1024 - types[target_section_index].max_stack_increase</code>, validation fails.</li> <li>Compute new stack height bounds after the instruction execution. Upper and lower bound are updated by the same value: <ul> <li>after <code>CALLF</code> stack height bounds are adjusted by adding <code>types[target_section_index].outputs - types[target_section_index].inputs</code>,</li> <li>after any other non-terminating instruction stack height bounds are adjusted by subtracting the number of instruction inputs and adding the number of instruction outputs,</li> <li>terminating instructions do not need to update stack height bounds.</li> </ul> </li> </ol> </li> <li>Determine the list of successor instructions that can follow the current instructions: <ol> <li>The next instruction if the current instruction is not a terminating instruction nor unconditional jump (<code>RJUMP</code>).</li> <li>All the current instruction targets if the current instruction is a conditional (<code>RJUMPI</code> or <code>RJUMPV</code>) or unconditional jump (<code>RJUMP</code>).</li> </ol> </li> <li>For each successor instruction: <ol> <li><strong>Check</strong> if the instruction is present in the code (i.e. execution must not "fall off" the code).</li> <li>If the successor is reached via forwards jump or sequential flow from previous instruction: <ol> <li>If the instruction does not have stack height bounds recorded (being visited for the first time), record the instruction stack height bound as the value computed in 2.3.</li> <li>Otherwise, instruction has been already visited (by previously seen forward jump). Update this instruction's recorded stack height bounds so that they contain the bounds computed in 2.3, i.e. <code>target_stack_min = min(target_stack_min, current_stack_min)</code> and <code>target_stack_max = max(target_stack_max, current_stack_max)</code>, where <code>(target_stack_min, target_stack_max)</code> are successor bounds and <code>(current_stack_min, current_stack_max)</code> are bounds computed in 2.3.</li> </ol> </li> <li>If the successor is reached via backwards jump, <strong>check</strong> if the recorded stack height bounds equal the value computed in 2.3. Validation fails if they are not equal, i.e. we see backwards jump to a different stack height.</li> </ol> </li> </ol> <p>After all instructions are visited, determine the function maximum operand stack height increase:</p> <ol> <li>Compute the maximum stack height <code>max_stack_height</code> as the maximum of all recorded stack height upper bounds.</li> <li>Compute the maximum stack height increase <code>max_stack_increase</code> as <code>max_stack_height - type[current_section_index].inputs</code>.</li> <li><strong>Check</strong> if the maximum stack height increase <code>max_stack_increase</code> matches the value corresponding code section's within the type section: <code>types[current_section_index].max_stack_increase</code>.</li> </ol> <p><em>Note: Although we check only that <code>max_stack_increase</code> matches the type section definition, which guarantees that it does not exceed 1023 by EOF header definition, it is also guaranteed that <code>max_stack_height</code> does not exceed 1024, because otherwise validation of <code>CALLF</code> and <code>JUMPF</code> into this section would fail at operand stack overflow check. Every section is required to have <code>CALLF</code> or <code>JUMPF</code> targeting it, except 0th section (non-reachable sections are not allowed). 0th section is required to have 0 inputs, which implies <code>max_stack_increase</code> equals <code>max_stack_height</code>.</em></p> <p>The computational and space complexity of this pass is <em>O(len(code))</em>. Each instruction is visited at most once.</p> <h3 id="execution">Execution</h3> <p>Given the deploy-time validation guarantees, an EVM implementation is not required anymore to have run-time stack underflow nor overflow checks for each executed instruction. The exception is the <code>CALLF</code> and <code>JUMPF</code> performing operand stack overflow check for the entire called function.</p> <h2 id="rationale">Rationale</h2> <h3 id="properties-of-validated-code">Properties of validated code</h3> <p>Any code section validated according to operand stack validation has the following properties:</p> <ol> <li>There are no unreachable instructions</li> <li>There are no instructions reachable only via backwards jump</li> <li>Operand stack underflow cannot happen.</li> <li>Operand stack overflow can only happen at <code>CALLF</code> or <code>JUMPF</code> instruction.</li> <li>Multiple forward jump instructions executing at different stack heights may target the same instruction; the stack of target basic block is validated for all possible heights.</li> <li>Any backwards jump instruction can only target an instruction that is executed with equal stack height; this prevents deployment of the loops with unbounded stack pushing or popping.</li> <li>Final instruction in the code section is either terminating instruction or <code>RJUMP</code>.</li> </ol> <h3 id="stack-overflow-check-only-in-callf-jumpf">Stack overflow check only in CALLF/JUMPF</h3> <p>In this EIP, we provide a more efficient variant of the EVM where stack overflow check is performed only in <code>CALLF</code> and <code>JUMPF</code> instructions using the called function's <code>max_stack_height</code> information. This decreases flexibility of an EVM program because <code>max_stack_height</code> corresponds to the worst-case control-flow path in the function.</p> <h3 id="unreachable-code">Unreachable code</h3> <p>The operand stack validation algorithm rejects any code having any unreachable instructions. This check can be performed very cheaply. It prevents deploying degenerated code. Moreover, it enables combining instruction validation and operand stack validation into single pass.</p> <h3 id="clean-stack-upon-termination">Clean stack upon termination</h3> <p>It is currently required that the operand stack is empty (in the current function context) after the <code>RETF</code> instruction. Otherwise, the <code>RETF</code> semantic would be more complicated. For <code>n</code> function outputs and <code>s</code> the stack height at <code>RETF</code> the EVM would have to erase <code>s-n</code> non-top stack items and move the <code>n</code> stack items to the place of erased ones. Cost of such operation may be relatively cheap but is not constant. However, lifting the requirement and modifying the <code>RETF</code> semantic as described above is backward compatible and can be easily introduced in the future.</p> <h3 id="more-restrictive-stack-validation">More restrictive stack validation</h3> <p>Originally another variant of stack validation was proposed, where instead of linear scan of the code section, all code paths were examined by following the target(s) of every jump instruction in a breadth-first-search manner, tracking stack height for each visited instruction and checking that for every possible code path to a particular instruction its stack height remains constant.</p> <p>The advantage of this variant would be somewhat simpler algorithm (we would not need to track stack height bounds, but only a single stack height value for each instruction) and no extra requirement for ordering of code basic blocks (see below).</p> <p>However, compiler teams opposed to such restrictive stack height requirements. One prominent pattern used by compilers which wouldn't be possible is jumping to terminating helpers (code blocks ending with <code>RETURN</code> or <code>REVERT</code>) from different stack heights. This is common for example for a series of <code>assert</code> statements, each one compiled to a <code>RJUMPI</code> into a shared terminating helper. Enforcing constant stack requirement would mean that before jumping to such helper, extra items on the stack have to be popped, and this noticeably increases code size and consumed gas, and would defeat the purpose of extracting these common terminating sequences into a helper.</p> <h3 id="ordering-of-basic-blocks">Ordering of basic blocks</h3> <p>The prerequisite to stack validation algorithm is ordering of code basic blocks in a way that no block is referenced only by backwards jump.</p> <p>This is required to make it possible to examine each instruction in one linear pass over the code section. Forward pass over the code section allows for the algorithm to "expand" each forward jump target's stack height bounds and still keep the complexity linear. Trying to do jump target stack bounds expansion while scanning the code in the breadth-first-search manner would require to re-examine entire code path after its stack height bounds are expanded, which would result in quadratic complexity.</p> <p>This requirement is not unique to EOF but also present is some low-level IRs like SPIR-V and LLVM MIR.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change requires a "network upgrade," since it modifies consensus rules.</p> <p>It poses no risk to backwards compatibility, as it is introduced only for EOF1 contracts, for which deploying undefined instructions is not allowed, therefore there are no existing contracts using these instructions. The new instructions are not introduced for legacy bytecode (code which is not EOF formatted).</p> <h2 id="security-considerations">Security Considerations</h2> <p>As mentioned above, the proposed validation algorithm has linear computational and space complexity and its cost is covered by the transaction data costs <a href="https://wg-eips.ritovision.com/2028/">EIP-2028</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-08-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Timihttps://github.com/0xTimi 0xTriple7https://github.com/ysqi https://wg-eips.ritovision.com/5635/

An oracle for retrieving NFT licensing agreements

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes an NFT licensing oracle to store (register) and retrieve (discover) granted licensing agreements for non-fungible token (NFT) derivative works, which are also NFTs but are created using properties of some other underlying NFTs.</p> <p>In this standard, an NFT derivative work is referred to as a <strong>dNFT</strong>, while the original underlying NFT is referred to as an <strong>oNFT</strong>.</p> <p>The NFT owner, known as the <code>licensor</code>, may authorize another creator, known as the <code>licensee</code>, to create a derivative works (dNFTs), in exchange for an agreed payment, known as a <code>Royalty</code>. A licensing agreement outlines terms and conditions related to the deal between the licensor and licensee.</p> <h2 id="specification">Specification</h2> <p>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> <p>In general, there are three important roles in this standard:</p> <ul> <li>oNFT: An original underlying NFT. The holder of an oNFT is a licensor. An oNFT can be any NFT.</li> <li>dNFT: A derivative work based on one or more oNFTs. The holder of a dNFT is a licensee.</li> <li>Registry: A trusted smart contract able to verify whether a credential is signed or released by the holder of oNFT.</li> </ul> <p>Every <strong>dNFT</strong> contract must implement the <code>IERC5635NFT</code> and <code>IERC165</code> inferfaces.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.6.0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Interface of NFT derivatives (dNFT) for the NFT Licensing Standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The ERC-165 identifier for this interface is 0xd584841c.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5635DNFT</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC165 bytes to add to interface array - set in parent contract</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> implementing this standard</span></span> <span class="giallo-l"><span class="z-comment"> ///</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> bytes4(keccak256(&quot;IERC5635DNFT{}&quot;)) == 0xd584841c</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> bytes4 private constant _INTERFACE_ID_IERC5635DNFT = 0xd584841c;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> _registerInterface(_INTERFACE_ID_IERC5635XDNFT);</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the number of credentials.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> - ID of the dNFT asset queried</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> _number</span><span class="z-comment"> - the number of credentials </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> numberOfCredentials</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _number</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Called with the sale price to determine how much royalty is owed and to whom.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> - ID of the dNFT asset queried</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _credentialId</span><span class="z-comment"> - ID of the licensing agreement credential, the max id is numberOfCredentials(_tokenId)-1</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> _oNFT</span><span class="z-comment"> - the oNFT address where the licensing from</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> _tokenID</span><span class="z-comment"> - the oNFT ID where the licensing from</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> _registry</span><span class="z-comment"> - the address of registry which can verify this credential</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizedBy</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _credentialId</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _oNFT</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _registry</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Query if a contract implements an interface</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> interfaceID</span><span class="z-comment"> The interface identifier, as specified in ERC-165</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface identification is specified in ERC-165. This function</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> uses less than 30,000 gas.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-comment"> `true` if the contract implements `interfaceID` and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `interfaceID` is not 0xffffffff, `false` otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Every <strong>Registry</strong> contract must implement the <code>IERC5635Registry</code> and <code>IERC165</code> inferfaces.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.6.0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface of NFT derivatives (dNFT) for the NFT Licensing Standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0xb5065e9f</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5635Registry</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC165 bytes to add to interface array - set in parent contract</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> implementing this standard</span></span> <span class="giallo-l"><span class="z-comment"> ///</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> bytes4(keccak256(&quot;IERC5635Registry{}&quot;)) == 0xb5065e9f</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> bytes4 private constant _INTERFACE_ID_IERC5635Registry = 0xb5065e9f;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> _registerInterface(_INTERFACE_ID_IERC5635Registry);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> TODO</span><span class="z-comment">: Is the syntax correct?</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> LicensingAgreementType</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> NonExclusive</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Exclusive</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Sole</span></span> <span class="giallo-l"><span> }</span><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _dNFT</span><span class="z-comment"> - </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _dNFT_Id</span><span class="z-comment"> - </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _oNFT</span><span class="z-comment"> - </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _oNFT_Id</span><span class="z-comment"> - </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> _licensed</span><span class="z-comment"> - </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> _tokenID</span><span class="z-comment"> - the oNFT ID where the licensing from</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> _registry</span><span class="z-comment"> - the address of registry which can verify this credential</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isLicensed</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _dNFT</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _dNFT_Id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _oNFT</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _oNFT_Id</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _licensed</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> _licenseIdentifier</span><span class="z-comment"> - the identifier, e.g. `MIT` or `Apache`, similar to `SPDX-License-Identifier: MIT` in SPDX.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> licensingInfo</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _dNFT</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _dNFT_Id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _oNFT</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _oNFT_Id</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _licensed</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _licensor</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable z-parameter z-function"> _timeOfSignature</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span class="z-variable z-parameter z-function"> _expiryTime</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> LicensingAgreementType</span><span class="z-variable z-parameter z-function"> _type</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _licenseName</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _licenseUri</span><span class="z-comment"> //</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> royaltyRate</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _dNFT</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _dNFT_Id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _oNFT</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _oNFT_Id</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> beneficiary</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> rate</span><span class="z-comment"> //</span><span class="z-comment"> The decimals is 9, means to divide the rate by 1,000,000,000</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <strong>Registry</strong> contract MAY implement the <code>IERC5635Licensing</code> and <code>IERC165</code> inferfaces.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.6.0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5635Licensing</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span>, </span><span class="z-entity z-name">IERC5635Registry</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Licence</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _oNFT</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _oNFT_Id</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _dNFT</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _dNFT_Id</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> _expiryTime</span><span>, </span><span class="z-variable">LicensingAgreementType</span><span class="z-variable"> _type</span><span>, </span><span class="z-support">string</span><span class="z-variable"> _licenseName</span><span>, </span><span class="z-support">string</span><span class="z-variable"> _licenseUri</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _oNFT</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _approved</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ApprovalForAll</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _oNFT</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _operator</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> _approved</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> licence</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable z-parameter z-function"> _oNFT</span><span>,</span><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable z-parameter z-function"> _oNFT_Id</span><span>,</span><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable z-parameter z-function"> _dNFT</span><span>,</span><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable z-parameter z-function"> _dNFT_Id</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable z-parameter z-function"> _expiryTime</span><span>,</span><span class="z-storage z-type"> LicensingAgreementType</span><span class="z-variable z-parameter z-function"> _type</span><span>,</span><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _licenseName</span><span>,</span><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _licenseUri</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span><span class="z-comment"> //</span><span class="z-keyword">TODO</span><span class="z-comment">: mortgages or not?</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable z-parameter z-function"> _oNFT</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _approved</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span><span class="z-comment"> //</span><span class="z-keyword">TODO</span><span class="z-comment">: why payable?</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setApprovalForAll</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable z-parameter z-function"> _oNFT</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _operator</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _approved</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getApproved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable z-parameter z-function"> _oNFT</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isApprovedForAll</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable z-parameter z-function"> _oNFT</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Licensing credentials from a dNFT's contract can be retrieved with <code>authorizedBy</code>, which specifies the details of a licensing agreement, which may include the oNFT. Those credentials may be verified with a <code>registry</code> service.</p> <p>Anyone can retrieve licensing royalty information with <code>licensingRoyalty</code> via the registry. While it is not possible to enforce the rules set out in this EIP on-chain, just like <a href="https://wg-eips.ritovision.com/2981/">EIP-2981</a>, we encourages NFT marketplaces to follow this EIP.</p> <h3 id="two-stages-licensing-and-discovery">Two stages: Licensing and Discovery</h3> <p>Taking the moment when the dNFT is minted as the cut-off point, the stage before is called the <strong>Licensing</strong> stage, and the subsequent stage is called the <strong>Discovery</strong> stage. The interface <code>IERC5635Licensing</code> is for the <strong>Licensing</strong> stage, and the interfaces <code>IERC5635DNFT</code> and <code>IERC5635Registry</code> are for the <strong>Discovery</strong> stage.</p> <h3 id="design-decision-beneficiary-of-licensing-agreement">Design decision: beneficiary of licensing agreement</h3> <p>As soon as someone sells their NFT, the full licensed rights are passed along to the new owner without any encumbrances, so that the beneficiary should be the new owner.</p> <h3 id="difference-between-cantbeevil-licenses-and-licensing-agreements">Difference between CantBeEvil Licenses and Licensing Agreements.</h3> <p>CantBeEvil licenses are creator-holder licenses which indicate what rights the NFTs' holder are granted from the creator. Meanwhile, licensing agreements is a contract between a licensor and licensee. So, CantBeEvil licenses cannot be used as a licensing agreement.</p> <h3 id="design-decision-relationship-between-different-approval-levels">Design decision: Relationship between different approval levels</h3> <p>The approved address can <code>license()</code> the licensing agreement to <strong>dNFT</strong> on behalf of the holder of an <strong>oNFT</strong>. We define two levels of approval like that:</p> <ol> <li><code>approve</code> will lead to approval for one NFT related to an id.</li> <li><code>setApprovalForAll</code> will lead to approval of all NFTs owned by <code>msg.sender</code>.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>, <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>, and <a href="https://wg-eips.ritovision.com/2981/">EIP-2981</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="examples">Examples</h3> <h4 id="deploying-an-eip-721-nft-and-signaling-support-for-dnft">Deploying an <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> NFT and signaling support for dNFT</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">constructor</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> symbol</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> baseURI</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _name </span><span class="z-keyword">=</span><span> name</span><span>;</span></span> <span class="giallo-l"><span> _symbol </span><span class="z-keyword">=</span><span> symbol</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setBaseURI</span><span>(</span><span>baseURI</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> register the supported interfaces to conform to ERC721 via ERC165</span></span> <span class="giallo-l"><span class="z-entity z-name"> _registerInterface</span><span>(</span><span>_INTERFACE_ID_ERC721</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _registerInterface</span><span>(</span><span>_INTERFACE_ID_ERC721_METADATA</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _registerInterface</span><span>(</span><span>_INTERFACE_ID_ERC721_ENUMERABLE</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> dNFT interface</span></span> <span class="giallo-l"><span class="z-entity z-name"> _registerInterface</span><span>(</span><span>_INTERFACE_ID_IERC5635DNFT</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="checking-if-the-nft-being-sold-on-your-marketplace-is-a-dnft">Checking if the NFT being sold on your marketplace is a dNFT</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes4</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _INTERFACE_ID_IERC5635DNFT </span><span class="z-keyword">=</span><span class="z-constant"> 0xd584841c</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> checkDNFT</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> IERC165</span><span>(</span><span>_contract</span><span>)</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>_INTERFACE_ID_IERC5635DNFT</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> success</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="checking-if-an-address-is-a-registry">Checking if an address is a Registry</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes4</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _INTERFACE_ID_IERC5635Registry </span><span class="z-keyword">=</span><span class="z-constant"> 0xb5065e9f</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> checkLARegistry</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _contract</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> IERC165</span><span>(</span><span>_contract</span><span>)</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>_INTERFACE_ID_IERC5635Registry</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> success</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-08-09T00:00:00+00:00 2026-02-11T14:48:26+00:00 Zainan Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/5437/

An interface for security notice using asymmetric encryption

<h2 id="abstract">Abstract</h2> <p>An interface for security notice using asymmetric encryption. The interface exposes a asymmetric encryption key and a destination of delivery.</p> <h2 id="motivation">Motivation</h2> <p>Currently there is no consistent way to specify an official channel for security researchers to report security issues to smart contract maintainers.</p> <h2 id="specification">Specification</h2> <p>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> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IEIP5437</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> REQUIRED</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getSecurityContact</span><span>(</span><span class="z-support">uint8</span><span class="z-variable"> type</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> type</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> publicKey</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> extraData</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> TODO</span><span class="z-comment"> consider remove if not needed before finalized</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setSecurityContact</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> type</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> publicKey</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> extraData</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SecurityContactChanged</span><span>(</span><span class="z-support">uint8</span><span class="z-variable"> type</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> memory</span><span class="z-variable"> publicKeyForEncryption</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> memory</span><span class="z-variable"> extraData</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> securityNotify</span><span>(</span><span class="z-support">uint8</span><span class="z-variable"> type</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OnSecurityNotification</span><span>(</span><span class="z-support">uint8</span><span class="z-variable"> type</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> memory</span><span class="z-variable"> sourceData</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> TODO</span><span class="z-comment"> consider to make it a separate EIP</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> bountyPolicy</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">string</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> extraData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol> <li>Compliant interfaces MUST implement the <code>getSecurityContact</code> method.</li> </ol> <p><code>type</code> is a one byte data with valid range of <code>[0x10, 0x7f]</code>. The ranges of <code>[0x00, 0x0f]</code> and <code>[0x80, 0xff]</code> are reserved for future extension.</p> <p>The <code>type</code> indicates the format of the <code>publicKey</code> and <code>extraData</code> in the following way</p> <hr /> <table><thead><tr><th>Type</th><th>Encryption scheme</th><th>extraData</th></tr></thead><tbody> <tr><td>0x10</td><td>GnuPG - RSA/3072</td><td>Email address(es) encoded in format of RFC 2822</td></tr> </tbody></table> <hr /> <p>A new version of this table can be proposed by future EIPs by specifying a new <code>type</code> number.</p> <ol start="2"> <li>The <code>publicKey</code> returned from <code>getSecurityContact</code> MUST follow the encryption scheme specified in the table above.</li> </ol> <p>The following is an example of a <code>publicKey</code> using <code>RSA/3072</code> generated via GnuPG in an RFC 20 ASCII-encoding of the public key string:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>-----BEGIN PGP PUBLIC KEY BLOCK-----</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>mQGNBGLzM2YBDADnCxAW/A0idvKNeQ6s/iYUeIIE+2mWmHcBGqLi0zrfz7pKWI+D</span></span> <span class="giallo-l"><span>m6Hek51sg2c7ZlswPEp8KqANrj/CV1stXHF+KAZtYeFiAqpIZl1wtB6QgKYWGsJf</span></span> <span class="giallo-l"><span>sXjBU3duLzLut2yvTfbEZsWAvrEaDjlXywdpboorHvfTE2vOvI6iGcjdh7PW7W7g</span></span> <span class="giallo-l"><span>IGzlL6ukLGG7y9FUO2dSMjCR/tWMLCupnDDLN2cUHnfEnHZ34FMd61NxcHLC7cIk</span></span> <span class="giallo-l"><span>P8xkFt8GCxURniTjqI5HAB8bGfR34kflVpr2+iKD5e+vQxcWK7vB443nruVf8osn</span></span> <span class="giallo-l"><span>udDF8Z6mgl7bKBbGyYH58QsVlmZ8g3E4YaMKjpwOzEK3V2R8Yh4ETdr670ZCRrIz</span></span> <span class="giallo-l"><span>QWVkibGgmQ3J/9RYps5Hfqpj4wV60Bsh1xUIJEIAs3ubMt7Z5JYFeze7VlXGlwot</span></span> <span class="giallo-l"><span>P+SnAfKzlZT4CDEl2LEEDrbpnpOEdp0x9hYsEaXTxBGSpTDaxP2MyhW3u6pYeehG</span></span> <span class="giallo-l"><span>oD0UVTLjWgU+6akAEQEAAbQjc29tZXJlYWxuYW1lIDxncGcubG9jYWwuZ2VuQHp6</span></span> <span class="giallo-l"><span>bi5pbT6JAdQEEwEIAD4WIQTDk/9jzRZ+lU2cY8rSVJNbud1lrQUCYvMzZgIbAwUJ</span></span> <span class="giallo-l"><span>EswDAAULCQgHAgYVCgkICwIEFgIDAQIeAQIXgAAKCRDSVJNbud1lraulDACqFbQg</span></span> <span class="giallo-l"><span>e9hfoK17UcPVz/u4ZnwmFd9zFAWSYkGqrK9XMvz0R8pr7Y3Dp5hfvaptqID/lHhA</span></span> <span class="giallo-l"><span>2oPEZ1ViIYDBcqG9WoWjCOYNoIosEAczrvf8YtUC2MHI+5DdYHtST74jDLuWMw3U</span></span> <span class="giallo-l"><span>AbBXHds3KcRY5/j01kqqi4uwsMBCYyH3Jl3IwjKgy0KDBbuQakvaHPmNnt81ayvZ</span></span> <span class="giallo-l"><span>ucdsNB9n/JMDxUWNCcySR+cllW4mk68pdiuK5qw0JMaoUjHFoWsgMTbFSlAV/lre</span></span> <span class="giallo-l"><span>qu8MnrLSs5iPvvaJ3uDOuYROB2FsbvWxayfAAVS1iZf2vQFBJPnDwDdYoPNYMjLp</span></span> <span class="giallo-l"><span>s2SfU02MVRGp3wanbtvM52uP42SLLNjBqUvJV03/QwfxCRejgAJOBn+iaOxP9NOe</span></span> <span class="giallo-l"><span>qfQdKzYPbA9FohdkL9991n21XBZcZzAgF9RyU9IZAPAnwZyex1zfzJsUp/HrjhP8</span></span> <span class="giallo-l"><span>Ljs8MIcjIlmpLk66TmJte4dN5eML1bpohmfMX8k0ILESLSUhxEg1JBNYIDK5AY0E</span></span> <span class="giallo-l"><span>YvMzZgEMALnIkONpqCkV+yaP8Tb8TBjmM+3TioJQROViINUQZh6lZM3/M+DPxAWZ</span></span> <span class="giallo-l"><span>r0MIh1a3+o+ThlZ70tlS67w3Sjd62sWAFzALzW4F+gTqjBTh6LURDqDV8OXUrggA</span></span> <span class="giallo-l"><span>SKK222aDP+Fr21h/TtPLeyDvcgm8Xvi4Cy7Jmf5CfT5jDio7a+FyFBNlTFSVqzLM</span></span> <span class="giallo-l"><span>TgFOkUFBg8kJKvDjWIrS2fcTkELwZ8+IlQ52YbrXwbDar843x1fRmsY+x9nnuGuP</span></span> <span class="giallo-l"><span>RYn1U4Jbptu2pEkG5q94jzUzTkGZHCzBJY7a8mtvS0mLqIE0Se1p+HFLY76Rma/F</span></span> <span class="giallo-l"><span>HB6J4JNOTzBZ0/1FVvUOcMkjuZ2dX81qoCZ8NP6eafzKvNYZrGa5NJnjWO1ag5jQ</span></span> <span class="giallo-l"><span>D8qHuOwxs8Fy9evmkwAVl51evLFNT532I4LK0zHSbF8MccZjpEFMSKwalKJn02Ml</span></span> <span class="giallo-l"><span>yTd+ljYLf8SKMOLVps8kc4VyMR1lz0PwSpKDFOmkC1LRURpM7UTtCK+/RFg1OLyQ</span></span> <span class="giallo-l"><span>SKBmdI37KQARAQABiQG8BBgBCAAmFiEEw5P/Y80WfpVNnGPK0lSTW7ndZa0FAmLz</span></span> <span class="giallo-l"><span>M2YCGwwFCRLMAwAACgkQ0lSTW7ndZa2oFgv8DAxHtRZchTvjxtdLhQEUSHt80JCQ</span></span> <span class="giallo-l"><span>zgHd7OUI9EU3K+oDj9AKtKZF1fqMlQoOskgBsLy/xpWwyhatv2ONLtHSjYDkZ7qs</span></span> <span class="giallo-l"><span>jsXshqpuvJ3X00Yn9PXG1Z1jKl7rzy2/0DnQ8aFP+gktfu2Oat4uIu4YSqRsVW/Z</span></span> <span class="giallo-l"><span>sbdTsW3T4E6Uf0qUKDf49mK3Y2nhTwY0YZqJnuQkSuUvpuM5a/4zSoaIRz+vSNjX</span></span> <span class="giallo-l"><span>MoXUIK/f8UnWABPm90OCptTMTzXCC1UXEHTNm6iBJThFiq3GeLZH+GnIola5KLO1</span></span> <span class="giallo-l"><span>+YbsFEchLfLZ27pWGfIbyppvsuQmrHef+J3g6sXybOWDHVYr3Za1fzxQVIbwoIEe</span></span> <span class="giallo-l"><span>ndKG0bu7ZAi2b/c8uH/wHT5IvtfzHLeSTjDqG8UyLTnaDxHQZIE9JIzWSQ1DSoNC</span></span> <span class="giallo-l"><span>YrU7CQtL+/HRpiGFHfClaXln8VWkjnUvp+Fg1ZPtE1t/SKddZ7m29Hd9nzUc0OQW</span></span> <span class="giallo-l"><span>MOA+HDqgA3a9kWbQKSloORq4unft1eu/FCra</span></span> <span class="giallo-l"><span>=O6Bf</span></span> <span class="giallo-l"><span>-----END PGP PUBLIC KEY BLOCK-----</span></span></code></pre> <ol start="3"> <li> <p>IF <code>setSecurityContact</code> is implemented and a call to it has succeeded in setting a new security contact, an event <code>SecurityContactChanged</code> MUST be emitted with the identical passed-in-parameters of <code>setSecurityContact</code></p> </li> <li> <p>It's also RECOMMENDED that an on-chain security notify method <code>securityNotify</code> to implemented to receive security notice onchain. If it's implemented and a call has succeeded, it MUST emit an <code>OnSecurityNotification</code> with identical pass-in-parameter data.</p> </li> <li> <p>Compliant interfaces MUST implement <a href="https://wg-eips.ritovision.com/165/">EIP-165</a>.</p> </li> </ol> <!-- TODO: add EIP-165 interfaces. --> <!-- TODO also consider requiring/recommending implementing EIP-5629 ERC-interface detection. --> <ol start="6"> <li>It's recommended to set a bounty policy via <code>bountyPolicy</code> method. The <code>id = 0</code> is preserved for a full overview, while other digits are used for different individual bounty policies. The returned string will be URI to content of bounty policies. No particular format of bounty policy is specified.</li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li>For simplicity, this EIP specifies a simple GPG scheme with a given encryption scheme and uses email addresses as a contact method. It's possible that future EIPs will specify new encryption schemes or delivery methods.</li> <li>This EIP adds an optional method, <code>setSecurityContact</code>, to set the security contact, because it might change due to circumstances such as the expiration of the cryptographic keys.</li> <li>This EIP explicitly marks <code>securityNotify</code> as <code>payable</code>, in order to allow implementers to set a staking amount to report a security vulnerability.</li> <li>This EIP allows for future expansion by adding the <code>bountyPolicy</code> the <code>extraData</code> fields. Additional values of these fields may be added in future EIPs.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Currently, existing solutions such as OpenZeppelin use plaintext in source code</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @custom:security</span><span class="z-comment">-contact some-user@some-domain.com</span></span></code></pre> <p>It's recommend that new versions of smart contracts adopt this EIP in addition to the legacy <code>@custom:security-contact</code> approach.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Implementors should properly follow security practices required by the encryption scheme to ensure the security of the chosen communication channel. Some best practices are as follows:</p> <ol> <li>Keep security contact information up-to-date;</li> <li>Rotate encryption keys in the period recommended by best practice;</li> <li>Regularly monitor the channel to receive notices in a timely manner.</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-07-26T00:00:00+00:00 2026-02-11T14:49:28+00:00 Stanley Wuhttps://github.com/fruit37 Mücahit Büyükyılmazhttps://github.com/anndro Muhammed Emin Aydınhttps://github.com/muhammedea https://wg-eips.ritovision.com/5345/

Temporary transaction signing without user interaction

<h2 id="abstract">Abstract</h2> <p>Mobile applications supporting lots of transactions might become a source of bad user experience due to uncontrolled switching between the wallet's and application's UI. By this proposal, we would like to introduce the means to sign and send wallet transactions without the need for user participation. This feature can be implemented by providing user consent for a specific time duration. We call the feature Silent Signing.</p> <h2 id="motivation">Motivation</h2> <p>Some blockchain applications interact with a blockchain much more frequently than others. It is especially true for gaming applications having their own sidechains. Interrupting the gaming process and switching to the wallet to perform a transaction drastically affect the user experience.</p> <h2 id="specification">Specification</h2> <p>To remedy the situation, we'd like to introduce new RPC methods for the ethereum JSON-RPC. Those methods help enable wallets to implement the Silent Signing feature.</p> <h3 id="silent-signing-user-flow">Silent Signing User Flow</h3> <p>The Silent Signing process has the following structure:</p> <ol> <li>First, the application requests the wallet to use Silent Signing via the RPC's <code>wallet_requestSilentSign</code> method.</li> <li>Second, the wallet prompts the user to confirm enabling the Silent Singing functionality for a specific time duration.</li> <li>If the user does not confirm Silent Signing or the RPC method is not allowed, the application will continue using the regular methods.</li> <li>If the user confirms Silent Signing, then each subsequent transaction will be sent using the <code>wallet_silentSendTransaction</code> method for the time duration specified.</li> </ol> <h3 id="implementation">Implementation</h3> <p>The implementation introduces new RPC methods and flow for application and wallet side.</p> <h3 id="new-rpc-methods">New RPC Methods</h3> <h4 id="wallet-requestsilentsign"><code>wallet_requestSilentSign</code></h4> <p>This RPC method opens the wallet and prompts the user to enable automatic signing for a specific time duration. This function grants the application to call the following methods until the timestamp expires. Standard methods like <code>eth_signTrancaction</code> remain untouched.</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">Parameters</span></span> <span class="giallo-l"><span class="z-entity z-name"> Object:</span><span class="z-string"> request</span><span class="z-string"> object</span></span> <span class="giallo-l"><span> until: NUMBER - unix timesptamp, the </span><span class="z-keyword">end</span><span class="z-keyword"> time</span><span> the permission will be valid</span></span> <span class="giallo-l"><span class="z-entity z-name"> chainId:</span><span class="z-string"> NUMBER</span><span class="z-string"> -</span><span class="z-string"> the</span><span class="z-string"> chain</span><span class="z-string"> id</span><span class="z-string"> that</span><span class="z-string"> the</span><span class="z-string"> contract</span><span class="z-string"> located</span><span class="z-string"> in</span></span> <span class="giallo-l"><span class="z-entity z-name"> contractAddress:</span><span class="z-string"> ADDRESS</span><span class="z-string"> -</span><span class="z-string"> address</span><span class="z-string"> of</span><span class="z-string"> the</span><span class="z-string"> contract</span><span class="z-string"> to</span><span class="z-string"> be</span><span class="z-string"> allowed</span></span> <span class="giallo-l"><span class="z-entity z-name"> allowedFunctions:</span><span class="z-string"> STRING</span><span class="z-string"> ARRAY</span><span class="z-string"> -</span><span class="z-string"> allowed</span><span class="z-string"> function</span><span class="z-string"> signatures</span></span> <span class="giallo-l"><span class="z-entity z-name"> Ex:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">equip(address,uint256)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">unequip(address,uint256)</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">]</span></span> <span class="giallo-l"><span class="z-entity z-name"> description:</span><span class="z-string"> STRING</span><span class="z-string"> -</span><span class="z-string"> extra</span><span class="z-string"> description</span><span class="z-string"> that</span><span class="z-string"> can</span><span class="z-string"> be</span><span class="z-string"> shown</span><span class="z-string"> to</span><span class="z-string"> user</span><span class="z-string"> by</span><span class="z-string"> the</span><span class="z-string"> wallet</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">Returns</span></span> <span class="giallo-l"><span class="z-entity z-name"> DATA,</span><span class="z-constant"> 20</span><span class="z-string"> Bytes:</span><span class="z-string"> permissionSecret</span><span class="z-string"> -</span><span class="z-string"> a</span><span class="z-string"> secret</span><span class="z-string"> key</span><span class="z-string"> for</span><span class="z-string"> silent-signing</span><span class="z-string"> requests</span><span> (randomly</span><span class="z-string"> generated</span><span>)</span></span></code></pre><h4 id="wallet-silentsigntransaction"><code>wallet_silentSignTransaction</code></h4> <p>This RPC method creates a transaction and sends its data to the wallet for signing. The wallet signs the data in the background, interfering with no processes the user is involved in. Afterward, the application sends the signed transaction to the blockchain using Nethereum's or other libraries' <code>sendRawTransaction</code> method.</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">Parameters</span></span> <span class="giallo-l"><span class="z-entity z-name"> DATA,</span><span class="z-constant"> 20</span><span class="z-string"> Bytes:</span><span class="z-string"> permissionSecret</span><span class="z-string"> -</span><span class="z-string"> secret</span><span class="z-string"> key</span><span class="z-string"> obtained</span><span class="z-string"> from</span><span class="z-string"> `</span><span class="z-entity z-name">wallet_requestSilentSign</span><span class="z-string">`</span><span class="z-entity z-name"> method</span></span> <span class="giallo-l"><span class="z-entity z-name"> Object</span><span class="z-string"> -</span><span class="z-string"> The</span><span class="z-string"> transaction</span><span class="z-string"> object</span></span> <span class="giallo-l"><span class="z-entity z-name"> from:</span><span class="z-string"> DATA,</span><span class="z-constant"> 20</span><span class="z-string"> Bytes</span><span class="z-string"> -</span><span class="z-string"> The</span><span class="z-string"> address</span><span class="z-string"> the</span><span class="z-string"> transaction</span><span class="z-string"> is</span><span class="z-string"> sent</span><span class="z-string"> from.</span></span> <span class="giallo-l"><span class="z-entity z-name"> to:</span><span class="z-string"> DATA,</span><span class="z-constant"> 20</span><span class="z-string"> Bytes</span><span class="z-string"> -</span><span> (optional</span><span class="z-string"> when</span><span class="z-string"> creating</span><span class="z-string"> new</span><span class="z-string"> contract</span><span>) The address the transaction is directed to.</span></span> <span class="giallo-l"><span class="z-entity z-name"> gas:</span><span class="z-string"> QUANTITY</span><span class="z-string"> -</span><span> (optional,</span><span class="z-string"> default:</span><span class="z-constant"> 90000</span><span>) Integer of the gas provided </span><span class="z-keyword">for</span><span> the transaction execution. It will return unused gas.</span></span> <span class="giallo-l"><span class="z-entity z-name"> gasPrice:</span><span class="z-string"> QUANTITY</span><span class="z-string"> -</span><span> (optional,</span><span class="z-string"> default:</span><span class="z-string"> To-Be-Determined</span><span>) Integer of the gasPrice used </span><span class="z-keyword">for</span><span> each paid gas, in Wei.</span></span> <span class="giallo-l"><span class="z-entity z-name"> value:</span><span class="z-string"> QUANTITY</span><span class="z-string"> -</span><span> (optional</span><span>) Integer of the value sent with this transaction, in Wei.</span></span> <span class="giallo-l"><span class="z-entity z-name"> data:</span><span class="z-string"> DATA</span><span class="z-string"> -</span><span class="z-string"> The</span><span class="z-string"> compiled</span><span class="z-string"> code</span><span class="z-string"> of</span><span class="z-string"> a</span><span class="z-string"> contract</span><span class="z-string"> OR</span><span class="z-string"> the</span><span class="z-string"> hash</span><span class="z-string"> of</span><span class="z-string"> the</span><span class="z-string"> invoked</span><span class="z-string"> method</span><span class="z-string"> signature</span><span class="z-string"> and</span><span class="z-string"> encoded</span><span class="z-string"> parameters.</span></span> <span class="giallo-l"><span class="z-entity z-name"> nonce:</span><span class="z-string"> QUANTITY</span><span class="z-string"> -</span><span> (optional</span><span>) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-entity z-name">Returns</span></span> <span class="giallo-l"><span class="z-entity z-name"> DATA,</span><span class="z-string"> The</span><span class="z-string"> signed</span><span class="z-string"> transaction</span><span class="z-string"> object.</span></span></code></pre><h4 id="wallet-silentsendtransaction"><code>wallet_silentSendTransaction</code></h4> <p>This RPC method creates a transaction and sends it to the blockchain without interfering with the process the user is involved in.</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">Parameters</span></span> <span class="giallo-l"><span class="z-entity z-name"> DATA,</span><span class="z-constant"> 20</span><span class="z-string"> Bytes:</span><span class="z-string"> permissionSecret</span><span class="z-string"> -</span><span class="z-string"> secret</span><span class="z-string"> key</span><span class="z-string"> obtained</span><span class="z-string"> from</span><span class="z-string"> `</span><span class="z-entity z-name">wallet_requestSilentSign</span><span class="z-string">`</span><span class="z-entity z-name"> method</span></span> <span class="giallo-l"><span class="z-entity z-name"> Object</span><span class="z-string"> -</span><span class="z-string"> The</span><span class="z-string"> transaction</span><span class="z-string"> object</span></span> <span class="giallo-l"><span class="z-entity z-name"> from:</span><span class="z-string"> DATA,</span><span class="z-constant"> 20</span><span class="z-string"> Bytes</span><span class="z-string"> -</span><span class="z-string"> The</span><span class="z-string"> address</span><span class="z-string"> the</span><span class="z-string"> transaction</span><span class="z-string"> is</span><span class="z-string"> sent</span><span class="z-string"> from.</span></span> <span class="giallo-l"><span class="z-entity z-name"> to:</span><span class="z-string"> DATA,</span><span class="z-constant"> 20</span><span class="z-string"> Bytes</span><span class="z-string"> -</span><span> (optional</span><span class="z-string"> when</span><span class="z-string"> creating</span><span class="z-string"> new</span><span class="z-string"> contract</span><span>) The address the transaction is directed to.</span></span> <span class="giallo-l"><span class="z-entity z-name"> gas:</span><span class="z-string"> QUANTITY</span><span class="z-string"> -</span><span> (optional,</span><span class="z-string"> default:</span><span class="z-constant"> 90000</span><span>) Integer of the gas provided </span><span class="z-keyword">for</span><span> the transaction execution. It will return unused gas.</span></span> <span class="giallo-l"><span class="z-entity z-name"> gasPrice:</span><span class="z-string"> QUANTITY</span><span class="z-string"> -</span><span> (optional,</span><span class="z-string"> default:</span><span class="z-string"> To-Be-Determined</span><span>) Integer of the gasPrice used </span><span class="z-keyword">for</span><span> each paid gas.</span></span> <span class="giallo-l"><span class="z-entity z-name"> value:</span><span class="z-string"> QUANTITY</span><span class="z-string"> -</span><span> (optional</span><span>) Integer of the value sent with this transaction.</span></span> <span class="giallo-l"><span class="z-entity z-name"> data:</span><span class="z-string"> DATA</span><span class="z-string"> -</span><span class="z-string"> The</span><span class="z-string"> compiled</span><span class="z-string"> code</span><span class="z-string"> of</span><span class="z-string"> a</span><span class="z-string"> contract</span><span class="z-string"> OR</span><span class="z-string"> the</span><span class="z-string"> hash</span><span class="z-string"> of</span><span class="z-string"> the</span><span class="z-string"> invoked</span><span class="z-string"> method</span><span class="z-string"> signature</span><span class="z-string"> and</span><span class="z-string"> encoded</span><span class="z-string"> parameters.</span></span> <span class="giallo-l"><span class="z-entity z-name"> nonce:</span><span class="z-string"> QUANTITY</span><span class="z-string"> -</span><span> (optional</span><span>) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">Returns</span></span> <span class="giallo-l"><span class="z-entity z-name"> DATA,</span><span class="z-constant"> 32</span><span class="z-string"> Bytes</span><span class="z-string"> -</span><span class="z-string"> the</span><span class="z-string"> transaction</span><span class="z-string"> hash,</span><span class="z-string"> or</span><span class="z-string"> the</span><span class="z-string"> zero</span><span class="z-string"> hash</span><span class="z-string"> if</span><span class="z-string"> the</span><span class="z-string"> transaction</span><span class="z-string"> is</span><span class="z-string"> not</span><span class="z-string"> yet</span><span class="z-string"> available.</span></span></code></pre><h3 id="application-and-wallet-communication">Application and Wallet Communication</h3> <p>Sending RPC requests between application and wallet can be as usual. For example browser extension wallets can use these new methods easily. Even hardware wallets can implement this too. But for mobile wallets extra communication techniques should be considered. Because mobile wallets can be inactive when it is not in use.</p> <p>Mobile wallets mostly use Walletconnect protocol. The application closed or active in the background can't connect to the Bridge server via WebSocket. Therefore, we have to trigger the wallet to connect to the Bridge and to start waiting for requests. For this purpose, push notifications are to be used. That means that only the wallets supporting push notifications can implement the feature.</p> <p><img src="https://wg-eips.ritovision.com/5345/./assets/walletconnect-flow.png" alt="" /></p> <p>Whenever the wallet receives a push notification, it connects to the Bridge server and gets access to the pending requests. If there are <code>wallet_silenSignTransaction</code> or <code>wallet_silentSendTransaction</code> silent signing requests pending and the interaction with the requesting client has been confirmed for this particular time duration, then the wallet executes the request without interfering with the ongoing user activity.</p> <h2 id="rationale">Rationale</h2> <p>Games and Metaverse applications imply lots of cases when the user interacts with the wallet, switching to it and approving transactions. This switching aspect might interfere with gaming per se and create a bad user experience. That is why such applications can benefit if the wallets can support the Silent Signing functionality allowing transactions to be signed with no user interaction.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>These new RPC methods don't interfere with the current ones, and for mobile wallets the push notifications API is currently a part of the <code>WalletConnect</code> specification. Implementing the proposal's functionality changes nothing for other applications and wallets.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The proposed feature aims to improve the user experience and can only be enabled with user consent. Users might freely choose to use the application as usual.</p> <p>Silent Signing permission has restrictions that makes it more secure.</p> <ul> <li>Permission granted only for a specified time duration</li> <li>Permission granted only for specific contract in a specific chain and restricted to specified functions.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-07-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yanhttps://github.com/yan253319066 https://wg-eips.ritovision.com/5334/

Add a time-limited role with restricted permissions to EIP-721 tokens.

<h2 id="abstract">Abstract</h2> <p>An <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> extension that adds an additional role (<code>user</code>) which can be granted to addresses, and a time where the role is automatically revoked (<code>expires</code>) and (<code>level</code>) . The <code>user</code> role represents permission to "use" the NFT, but not the ability to transfer it or set users.</p> <h2 id="motivation">Motivation</h2> <p>Some NFTs have certain utilities. For example, virtual land can be "used" to build scenes, and NFTs representing game assets can be "used" in-game. In some cases, the owner and user may not always be the same. There may be an owner of the NFT that rents it out to a “user”. The actions that a “user” should be able to take with an NFT would be different from the “owner” (for instance, “users” usually shouldn’t be able to sell ownership of the NFT).  In these situations, it makes sense to have separate roles that identify whether an address represents an “owner” or a “user” and manage permissions to perform actions accordingly.</p> <p>Some projects already use this design scheme under different names such as “operator” or “controller” but as it becomes more and more prevalent, we need a unified standard to facilitate collaboration amongst all applications.</p> <p>Furthermore, applications of this model (such as renting) often demand that user addresses have only temporary access to using the NFT. Normally, this means the owner needs to submit two on-chain transactions, one to list a new address as the new user role at the start of the duration and one to reclaim the user role at the end. This is inefficient in both labor and gas and so an “expires” and “level” function is introduced that would facilitate the automatic end of a usage term without the need of a second transaction.</p> <p>Here are some of the problems that are solved by this standard:</p> <h3 id="clear-rights-assignment">Clear Rights Assignment</h3> <p>With Dual “owner” and “user” roles, it becomes significantly easier to manage what lenders and borrowers can and cannot do with the NFT (in other words, their rights). Additionally, owners can control who the user is and it’s easy for other projects to assign their own rights to either the owners or the users.</p> <h3 id="simple-on-chain-time-management">Simple On-chain Time Management</h3> <p>Once a rental period is over, the user role needs to be reset and the “user” has to lose access to the right to use the NFT. This is usually accomplished with a second on-chain transaction but that is gas inefficient and can lead to complications because it’s imprecise. With the <code>expires</code> function, there is no need for another transaction because the “user” is invalidated automatically after the duration is over.</p> <h3 id="easy-third-party-integration">Easy Third-Party Integration</h3> <p>In the spirit of permission less interoperability, this standard makes it easier for third-party protocols to manage NFT usage rights without permission from the NFT issuer or the NFT application. Once a project has adopted the additional <code>user</code> role and <code>expires</code> and <code>level</code>, any other project can directly interact with these features and implement their own type of transaction. For example, a PFP NFT using this standard can be integrated into both a rental platform where users can rent the NFT for 30 days AND, at the same time, a mortgage platform where users can use the NFT while eventually buying ownership of the NFT with installment payments. This would all be done without needing the permission of the original PFP project.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="contract-interface">Contract Interface</h3> <p>Solidity Interface with NatSpec &amp; OpenZeppelin v4 Interfaces (also available at <a href="https://wg-eips.ritovision.com/5334/./assets/IERC5334.sol"><code>IERC5334.sol</code></a>):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5334</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Logged when the user of a NFT, expires, or level is </span><span class="z-keyword">changed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Emitted when the `user` of an NFT or the `expires` of the `user` is </span><span class="z-keyword">changed</span><span class="z-comment"> or the user `level` is </span><span class="z-keyword">changed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The zero address for user indicates that there is no user address</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UpdateUser</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>, </span><span class="z-support">uint64</span><span class="z-variable"> expires</span><span>, </span><span class="z-support">uint8</span><span class="z-variable"> level</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> set the user and expires and level of a NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The zero address indicates there is no user</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if `tokenId` is not valid NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> user</span><span class="z-comment"> The new user of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> expires</span><span class="z-comment"> UNIX timestamp, The new user could use the NFT before expires</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> level</span><span class="z-comment"> user level</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setUser</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> uint64</span><span class="z-variable"> expires</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> level</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the user address of an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The zero address indicates that there is no user or the user is expired</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT to get the user address for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> user address for this NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the user expires of an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The zero value indicates that there is no user</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT to get the user expires for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> user expires for this NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userExpires</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the user level of an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The zero value indicates that there is no user</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The NFT to get the user level for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> user level for this NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> userLevel</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>userOf(uint256 tokenId)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>userExpires(uint256 tokenId)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>userLevel(uint256 tokenId)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>setUser(uint256 tokenId, address user, uint64 expires)</code> function MAY be implemented as <code>public</code> or <code>external</code>.</p> <p>The <code>UpdateUser</code> event MUST be emitted when a user address is changed or the user expires is changed or the user level is changed.</p> <!-- The `supportsInterface` method MUST return `true` when called with `0xTODO`. --> <h2 id="rationale">Rationale</h2> <p>TBD</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As mentioned in the specifications section, this standard can be fully EIP-721 compatible by adding an extension function set.</p> <p>In addition, new functions introduced in this standard have many similarities with the existing functions in EIP-721. This allows developers to easily adopt the standard quickly.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation of this standard can be found in the assets folder.</p> <!-- [./assets/ERC5334.sol](./assets/ERC5334.sol). --> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP standard can completely protect the rights of the owner, the owner can change the NFT user and expires and level at any time.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-07-23T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ronan Sandfordhttps://github.com/wighawag https://wg-eips.ritovision.com/5409/

Allow EIP-1155 to represent Non-Fungible Tokens (tokens who have a unique owner)

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>. It proposes an additional function, <code>ownerOf</code>, which allows EIP-1155 tokens to support Non-Fungibility (unique owners). By implementing this extra function, EIP-1155 tokens can benefit from <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>'s core functionality without implementing the (less efficient) EIP-721 specification in the same contract.</p> <h2 id="motivation">Motivation</h2> <p>Currently, EIP-1155 does not allow an external caller to detect whether a token is truly unique (can have only one owner) or fungible. This is because EIP-1155 do not expose a mechanism to detect whether a token will have its supply remain to be "1". Furthermore, it does not let an external caller retrieve the owner directly on-chain.</p> <p>The EIP-1155 specification does mention the use of split id to represent non-fungible tokens, but this requires a pre-established convention that is not part of the standard, and is not as simple as EIP-721's <code>ownerOf</code>.</p> <p>The ability to get the owner of a token enables novel use-cases, including the ability for the owner to associate data with it.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="contract-interface">Contract Interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC1155OwnerOf</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Find the owner of an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The zero address indicates that there is no owner: either the token does not exist or it is not an NFT (supply potentially bigger than 1)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The identifier for an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> address of the owner of the NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>ownerOf(uint256 tokenId)</code> function MAY be implemented as <code>pure</code> or <code>view</code>.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0x6352211e</code>.</p> <h2 id="rationale">Rationale</h2> <p><code>ownerOf</code> does not throw when a token does not exist (or does not have an owner). This simplifies the handling of such a case. Since it would be a security risk to assume all EIP-721 implementation would throw, it should not break compatibility with contract handling EIP-721 when dealing with this EIP-1155 extension.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backward compatible with EIP-1155.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-07-19T00:00:00+00:00 2026-02-11T14:48:26+00:00 Erhard Dinhoblhttps://github.com/mrqc Kevin Riedlhttps://github.com/wsdt https://wg-eips.ritovision.com/5883/

On-Chain Social Recovery taking users' reputation into account & using a nearest-neighbour approach.

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes a mechanism of a social recovery where a token may be transferred from an inaccessible account to a new account, given enough approvals from other identities. This approval is not purely technical, but rather needs human intervention. These humans are - based on the Soul Bound Token proposal - called Souls. When enough Souls give their approval (which is a Yes/No decision) and a threshold is reached, a token is transferred from an old to a new identity.</p> <h2 id="motivation">Motivation</h2> <p>It is a known problem that the private key of an account can be lost. If that key is lost it's not possible to recover the tokens owned by that account. The holder loses those tokens forever. In addition to directly harming the token holder, the entire ecosystem of the token itself is affected: the more tokens that are lost the less tokens are available for the natural growth and planned evolution of that ecosystem.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.7</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ISocialRecovery</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Related but independent identity approves the transfer</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approveTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from_</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to_</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> User wants to move their onchain identity to another wallet which needs to be approved by n-nearest neighbour identities</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> requestTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from_</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to_</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addNeighbour</span><span>(</span><span class="z-support">address</span><span class="z-variable"> neighbour_</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeNeighbour</span><span>(</span><span class="z-support">address</span><span class="z-variable"> neighbour_</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>The math behind it</strong>:</p> <p>A compliant contract SHOULD calculate the score of a node n with the following formula:</p> <p>$$ score(n) = tanh({ { {\displaystyle\sum_{i = 1}^{|N|} } {log{(n_i^{r} {1 \over t - n_i^{t} + 1})}} \over{|N| + 1}} + n^{r}}) $$</p> <p>where:</p> <p>$t$ is the current time (can be any time-identifying value such as <code>block.timestamp</code>, <code>block.number</code>, etc.)</p> <p>$n^{r}$ is the reward count of the node n</p> <p>$N$ is the list of neighbours of n</p> <p>$n_i^{r}$ is the reward count of neighbour node i from n</p> <p>$n_i^{t}$ is the last timestamp (where a reward was booked on that account) of neighbour node i from n</p> <p><strong>Flows</strong>:</p> <p><img src="https://wg-eips.ritovision.com/5883/./assets/sequence-diagram.svg" alt="Approval of asset movement" /></p> <h2 id="rationale">Rationale</h2> <p>The formula proposed was deemed very resilient and provides a coherent incentivation structure to actually see value in the on-chain score. The formula adds weights based on scores based on time which further contributes to the fairness of the metric.</p> <h2 id="security-considerations">Security Considerations</h2> <ol> <li> <p>We currently do not see any mechanism of preventing a user of getting a lot of rewards. Sure, a high reward is bound to a lot of investment but the person who wants to get that reward amount and has a enough money will reach it. The only thing which could be improved is that we somehow find a mechanism really identify users bound to an address. We thought about having a kind of a hashing mechanism which hashes a real world object which could be fuzzy (for sure!) and generates a hash out of it which is the same based on the fuzzy set.</p> </li> <li> <p>We implemented a threshold which must be reached to make a social token transfer possible. Currently there is no experience which defines a "good" or "bad" threshold hence we tried to find a first value. This can or must be adjusted based on future experience.</p> </li> <li> <p>Another problem we see is that the network of the neighbours is not active anymore to reach the necessary minimum threshold. Which means that due to not being able to reach the minimum amount of approvals a user gets stuck with the e.g. social token transfer he/she wants to perform. Hence the contract lives from its usage and if it tends to be not used anymore it will get useless.</p> </li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-07-17T00:00:00+00:00 2026-02-11T14:49:28+00:00 Sergio D. Lernerhttps://github.com/SergioDemianLerner https://wg-eips.ritovision.com/5283/

A Precompile-based parallelizable reentrancy protection using the call stack

<h2 id="abstract">Abstract</h2> <p>This EIP proposes adding a precompiled contract that provides a semaphore function for creating a new type of reentrancy protection guard (RPG). This function aims to replace the typical RPG based on modifying a contract storage cell. The benefit is that the precompile-based RPG does not write to storage, and therefore it enables contracts to be forward-compatible with all designs that provide fine-grained (i.e. cell level) parallelization for the multi-threaded execution of EVM transactions.</p> <h2 id="motivation">Motivation</h2> <p>The typical smart contract RPG uses a contract storage cell. The algorithm is simple: the code checks that a storage cell is 0 (or any other predefined constant) on entry, aborting if not, and then sets it to 1. After executing the required code, it resets the cell back to 0 before exiting. This is the algorithm implemented in OpenZeppelin's ReentrancyGuard. The algorithm results in a read-write pattern on the RPG's storage cell. This pattern prevents the parallelization of the execution of the smart contract for all known designs that try to provide fine-grained parallelization (detecting conflicts at the storage cell level).</p> <p>Several EVM-based blockchains have successfully tested designs for the parallelization of the EVM. The best results have been obtained with fine-grained parallelization where conflicts are detected by tracking writes and reads of individual storage cells. The designs based on tracking the use of accounts or contracts provide only minor benefits because most transactions use the same <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> contracts.</p> <p>To summarize, the only available RPG construction today is based on using a contract storage cell. This construction is clean but it is not forward-compatible with transaction execution parallelization.</p> <h2 id="specification">Specification</h2> <p>Starting from an activation block (TBD) a new precompiled contract <code>Semaphore</code> is created at address <code>0x0A</code>. When <code>Semaphore</code> is called, if the caller address is present more than once in the call stack, the contract behaves as if the first instruction had been a <code>REVERT</code>, therefore the CALL returns 0. Otherwise, it executes no code and returns 1. The gas cost of the contract execution is set to 100, which is consumed independently of the call result.</p> <h2 id="rationale">Rationale</h2> <p>The address <code>0x0A</code> is the next one available within the range defined by <a href="https://wg-eips.ritovision.com/1352/">EIP-1352</a>.</p> <h3 id="sample-usage">Sample usage</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">abstract</span><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> ReentrancyGuard2</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> constant</span><span> SemaphoreAddress </span><span class="z-keyword">=</span><span class="z-constant"> 0x0A</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Prevents a contract from calling itself, directly or indirectly.</span></span> <span class="giallo-l"><span class="z-comment"> * Calling a `nonReentrant` function from another `nonReentrant`</span></span> <span class="giallo-l"><span class="z-comment"> * function is supported. </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> nonReentrant</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _nonReentrantBefore</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _nonReentrantBefore</span><span>(</span><span>)</span><span class="z-storage z-type"> private</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-entity z-name"> iszero</span><span>(</span><span class="z-entity z-name">staticcall</span><span>(</span><span class="z-constant">1000</span><span>,</span><span>SemaphoreAddress</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="parallelizable-storage-based-rpgs">Parallelizable storage-based RPGs</h3> <p>The only way to parallelize preexistent contracts that are using the storage RPG construction is that the VM automatically detects that a storage variable is used for the RPG, and proves that it works as required. This requires static code analysis. This is difficult to implement in consensus for two reasons. First, the CPU cost of detection and/or proving may be high. Second, some contract functions may not be protected by the RPG, meaning that some execution paths do not alter the RPG, which may complicate proving. Therefore this proposal aims to protect future contracts and let them be parallelizable, rather than to parallelize already deployed ones.</p> <h3 id="alternatives">Alternatives</h3> <p>There are alternative designs to implement RPGs on the EVM:</p> <ol> <li>Transient storage opcodes (<code>TLOAD</code>/<code>TSTORE</code>) provide contract state that is kept between calls in the same transaction but it is not committed to the world state afterward. These opcodes also enable fine-grained parallelization.</li> <li>An opcode <code>SSTORE_COUNT</code> that retrieves the number of <code>SSTORE</code> instructions executed. It enables also fine-grained execution parallelization, but <code>SSTORE_COUNT</code> is much more complex to use correctly as it returns the number <code>SSTORE</code> opcodes executed, not the number of reentrant calls. Reentrancy must be deducted from this value.</li> <li>A new <code>LOCKCALL</code> opcode that works similar to <code>STATICALL</code> but only blocks storage writes in the caller contract. This results in cheaper RPG, but it doesn't allow some contract functions to be free of the RPG.</li> </ol> <p>All these alternative proposals have the downside that they create new opcodes, and this is discouraged if the same functionality can be implemented with the same gas cost using precompiles. A new opcode requires modifying compilers, debuggers and static analysis tools.</p> <h3 id="gas-cost">Gas cost</h3> <p>A gas cost of 100 represents a worst-case resource consumption, which occurs when the stack is almost full (approximately 400 addresses) and it is fully scanned. As the stack is always present in RAM, the scanning is fast.</p> <p>Note: Once code is implemented in geth, it can be benchmarked and the cost can be re-evaluated, as it may result to be lower in practice. As a precompile call currently costs 700 gas, the cost of stack scanning has a low impact on the total cost of the precompile call (800 gas in total).</p> <p>The storage-based RPG currently costs 200 gas (because of the savings introduced in <a href="https://wg-eips.ritovision.com/1283/">EIP-1283</a>. Using the <code>Semaphore</code> precompile as a reentrancy check would currently cost 800 gas (a single call from one of the function modifiers). While this cost is higher than the traditional RPG cost and therefore discourages its use, it is still much lower than the pre-EIP-1283 cost. If a reduction in precompile call cost is implemented, then the cost of using the <code>Semaphore</code> precompile will be reduced to approximately 140 gas, below the current 200 gas consumed by a storage-based RPG. To encourage to use of the precompile-based RPG, it is suggested that this EIP is implemented together with a reduction in precompile calls cost.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change requires a hard fork and therefore all full nodes must be updated.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Test</span><span class="z-storage"> is</span><span class="z-entity z-name"> ReentrancyGuard2</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> second</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> nonReentrant</span><span> {</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> first</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> nonReentrant</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-language"> this</span><span>.</span><span class="z-entity z-name">second</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A call to <code>second()</code> directly from a transaction does not revert, but a call to <code>first()</code> does revert.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-07-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv https://wg-eips.ritovision.com/5298/

An interface for a smart contract acting as a "trust" that holds tokens by ENS name.

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes an interface for smart contracts to hold of <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> tokens on behalf of ENS domains.</p> <h2 id="motivation">Motivation</h2> <p>Currently, if someone wants to receive a token, they have to set up a wallet address. This EIP decouples NFT ownership from wallet addresses.</p> <h2 id="specification">Specification</h2> <ol> <li>Compliant contracts MUST implement <code>ERC721TokenReceiver</code>, as defined in <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>.</li> <li>Compliant contracts implement the following interface:</li> </ol> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC_ENS_TRUST</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721Receiver</span><span>, </span><span class="z-entity z-name">ERC1155Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> claimTo</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> ensNode</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> payable</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ol start="3"> <li> <p><code>claimTo</code> MUST check if <code>msg.sender</code> is the owner of the ENS node identified by <code>bytes32 ensNode</code> (and/or approved by the domain in implementation-specific ways). The compliant contract then MUST make a call to the <code>safeTransferFrom</code> function of <a href="https://wg-eips.ritovision.com/712/">EIP-721</a> or <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>.</p> </li> <li> <p>Any <code>ensNode</code> is allowed.</p> </li> </ol> <h2 id="rationale">Rationale</h2> <ol> <li> <p>ENS was chosen because it is a well-established scoped ownership namespace. This is nonetheless compatible with other scoped ownership namespaces.</p> </li> <li> <p>We didn't expose getters or setters for ensRoot because it is outside of the scope of this EIP.</p> </li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues were found.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-variable z-other"> loadFixture</span><span> }</span><span class="z-keyword"> from</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">@nomicfoundation/hardhat-network-helpers</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-variable z-other"> expect</span><span> }</span><span class="z-keyword"> from</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chai</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span> {</span><span class="z-variable z-other"> ethers</span><span> }</span><span class="z-keyword"> from</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">hardhat</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">describe</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">FirstENSBankAndTrust</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> describe</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Receive and Claim Token</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> it</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Should ACCEPT/REJECT claimTo based on if ENS owner is msg.sender</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage"> async</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> ...</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Steps of testing:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> mint to charlie</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> charlie send to ENSTrust and recorded under bob.xinbenlvethsf.eth</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bob try to claimTo alice, first time it should be rejected</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bob then set the ENS record</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bob claim to alice, second time it should be accepted</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> mint to charlie</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> erc721ForTesting</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span class="z-variable z-other">charlie</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> fakeTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> charlie send to ENSTrust and recorded under bob.xinbenlvethsf.eth</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> erc721ForTesting</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">charlie</span><span>)</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">safeTransferFrom(address,address,uint256,bytes)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> charlie</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> firstENSBankAndTrust</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> fakeTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> fakeReceiverENSNamehash</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bob try to claimTo alice, first time it should be rejected</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">firstENSBankAndTrust</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">bob</span><span>)</span><span>.</span><span class="z-entity z-name">claimTo</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> alice</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> fakeReceiverENSNamehash</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> firstENSBankAndTrust</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> fakeTokenId</span></span> <span class="giallo-l"><span> )</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-variable z-other">to</span><span>.</span><span class="z-variable z-other">be</span><span>.</span><span class="z-entity z-name">rejectedWith</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ENSTokenHolder: node not owned by sender</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bob then set the ENS record</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> ensForTesting</span><span>.</span><span class="z-entity z-name">setOwner</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> fakeReceiverENSNamehash</span><span>,</span><span class="z-variable z-other"> bob</span><span>.</span><span class="z-variable z-other">address</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> bob claim to alice, second time it should be accepted</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">firstENSBankAndTrust</span><span>.</span><span class="z-entity z-name">connect</span><span>(</span><span class="z-variable z-other">bob</span><span>)</span><span>.</span><span class="z-entity z-name">claimTo</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> alice</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> fakeReceiverENSNamehash</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> erc721ForTesting</span><span>.</span><span class="z-variable z-other">address</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> fakeTokenId</span></span> <span class="giallo-l"><span> )</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.9</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> FirstENSBankAndTrust</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC721Receiver</span><span>, </span><span class="z-entity z-name">Ownable</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getENS</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">ENS</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> ENS</span><span>(</span><span>ensAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setENS</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newENSAddress</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span> ensAddress </span><span class="z-keyword">=</span><span> newENSAddress</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev This function is called by the owner of the token to approve the transfer of the token</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @param data MUST BE the ENS node of the intended token receiver this ENSHoldingServiceForNFT is holding on behalf of.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onERC721Received</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> operator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-comment"> /*</span><span class="z-comment">from</span><span class="z-comment">*/</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>data</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 32</span><span>,</span><span class="z-string"> &quot;ENSTokenHolder: last data field must be ENS node.&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> --- START WARNING ---</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> DO NOT USE THIS IN PROD</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> this is just a demo purpose of using extraData for node information</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> In prod, you should use a struct to store the data. struct should clearly identify the data is for ENS</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> rather than anything else.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> ensNode </span><span class="z-keyword">=</span><span class="z-support"> bytes32</span><span>(</span><span>data</span><span>[</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">32</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> --- END OF WARNING ---</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> addToHolding</span><span>(</span><span>ensNode</span><span>,</span><span> operator</span><span>,</span><span> tokenId</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> conduct the book keeping</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ERC721_RECEIVER_MAGICWORD</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> claimTo</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> ensNode</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenContract</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">getENS</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">owner</span><span>(</span><span>ensNode</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span class="z-string"> &quot;ENSTokenHolder: node not owned by sender&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> removeFromHolding</span><span>(</span><span>ensNode</span><span>,</span><span> tokenContract</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC721</span><span>(</span><span>tokenContract</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-07-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 James Grimmelmannhttps://github.com/grimmelm Yan Jihttps://github.com/iseriohn Tyler Kellhttps://github.com/relyt29 https://wg-eips.ritovision.com/5218/

An interface for creating copyright licenses that transfer with an NFT.

<h2 id="abstract">Abstract</h2> <p>The following standard defines an API for managing NFT licenses. This standard provides basic functionality to create, transfer, and revoke licenses, and to determine the current licensing state of an NFT. The standard does not define the legal details of the license. Instead, it provides a structured framework for recording licensing details.</p> <p>We consider use cases of NFT creators who wish to give the NFT holder a copyright license to use a work associated with the NFT. The holder of an active license can issue sublicenses to others to carry out the rights granted under the license. The license can be transferred with the NFT, so do all the sublicenses. The license can optionally be revoked under conditions specified by the creator.</p> <h2 id="motivation">Motivation</h2> <p>The <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard defines an API to track and transfer ownership of an NFT. When an NFT is to represent some off-chain asset, however, we would need some legally effective mechanism to <em>tether</em> the on-chain asset (NFT) to the off-chain property. One important case of off-chain property is creative work such as an image or music file. Recently, most NFT projects involving creative works have used licenses to clarify what legal rights are granted to the NFT owner. But these licenses are almost always off-chain and the NFTs themselves do not indicate what licenses apply to them, leading to uncertainty about rights to use the work associated with the NFT. It is not a trivial task to avoid all the copyright vulnerabilities in NFTs, nor have existing EIPs addressed rights management of NFTs beyond the simple cases of direct ownership (see <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>) or rental (see <a href="https://wg-eips.ritovision.com/4907/">ERC-4907</a>).</p> <p>This EIP attempts to provide a standard to facilitate rights management of NFTs in the world of Web3. In particular, <a href="https://wg-eips.ritovision.com/5218/">ERC-5218</a> smart contracts allow all licenses to an NFT, including the <em>root license</em> issued to the NFT owner and <em>sublicenses</em> granted by a license holder, to be recorded and easily tracked with on-chain data. These licenses can consist of human-readable legal code, machine-readable summaries such as those written in CC REL, or both. An ERC-5218 smart contract points to a license by recording a URI, providing a reliable reference for users to learn what legal rights they are granted and for NFT creators and auditors to detect unauthorized infringing uses.</p> <h2 id="specification">Specification</h2> <p>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> <p><strong>Every ERC-5218 compliant contract <em>must</em> implement the <code>IERC5218</code> interface</strong>:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-5218: NFT Rights Management</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5218</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC721</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a new license is created by any mechanism.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CreateLicense</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _licenseId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _tokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _parentLicenseId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _licenseHolder</span><span>, </span><span class="z-support">string</span><span class="z-variable"> _uri</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _revoker</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a license is revoked. </span><span class="z-keyword">Note</span><span class="z-comment"> that under some</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> license terms, the sublicenses may be `implicitly` revoked following the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> revocation of some ancestral license. In that case, your smart contract</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> may only emit this event once for the ancestral license, and the revocation</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> of all its sublicenses can be implied without consuming additional gas.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RevokeLicense</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _licenseId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when the a license is transferred to a new holder. The</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> root license of an NFT should be transferred with the NFT in an ERC721</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `transfer` function call. </span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TransferLicense</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _licenseId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _licenseHolder</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Check if a license is active.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A non-existing or revoked license is inactive and this function must</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> return `false` upon it. Under some license terms, a license may become</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> inactive because some ancestral license has been revoked. In that case,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> this function should return `false`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseId</span><span class="z-comment"> The identifier for the queried license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Whether</span><span class="z-comment"> the queried license is active</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isLicenseActive</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _licenseId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the token identifier a license was issued upon.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the license is active.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseId</span><span class="z-comment"> The identifier for the queried license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> token identifier the queried license was issued upon</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLicenseTokenId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _licenseId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the parent license identifier of a license.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the license is active. If a license doesn&#39;t have a</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> parent license, return a special identifier not referring to any license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (such as 0).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseId</span><span class="z-comment"> The identifier for the queried license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> parent license identifier of the queried license</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getParentLicenseId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _licenseId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the holder of a license.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the license is active. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseId</span><span class="z-comment"> The identifier for the queried license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> holder address of the queried license</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLicenseHolder</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _licenseId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the URI of a license.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the license is active. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseId</span><span class="z-comment"> The identifier for the queried license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> URI of the queried license</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLicenseURI</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _licenseId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the revoker address of a license.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the license is active. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseId</span><span class="z-comment"> The identifier for the queried license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> revoker address of the queried license</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLicenseRevoker</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _licenseId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the root license identifier of an NFT.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the queried NFT exists. If the NFT doesn&#39;t have a root</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> license tethered to it, return a special identifier not referring to any</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> license (such as 0). </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> The identifier for the queried NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> root license identifier of the queried NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLicenseIdByTokenId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Create a new license.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the NFT `_tokenId` exists. Throws unless the parent</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> license `_parentLicenseId` is active, or `_parentLicenseId` is a special</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> identifier not referring to any license (such as 0) and the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `_tokenId` doesn&#39;t have a root license tethered to it. Throws unless the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> message sender is eligible to create the license, i.e., either the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> license to be created is a root license and `msg.sender` is the NFT owner,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> or the license to be created is a sublicense and `msg.sender` is the holder</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> of the parent license. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> The identifier for the NFT the license is issued upon</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _parentLicenseId</span><span class="z-comment"> The identifier for the parent license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseHolder</span><span class="z-comment"> The address of the license holder</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _uri</span><span class="z-comment"> The URI of the license terms</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _revoker</span><span class="z-comment"> The revoker address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> identifier of the created license</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createLicense</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _parentLicenseId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _licenseHolder</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _uri</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _revoker</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Revoke a license.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the license is active and the message sender is the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> eligible revoker. This function should be used for revoking both root</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> licenses and sublicenses. </span><span class="z-keyword">Note</span><span class="z-comment"> that if a root license is revoked, the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> NFT should be transferred back to its creator.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseId</span><span class="z-comment"> The identifier for the queried license</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeLicense</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _licenseId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfer a sublicense.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the sublicense is active and `msg.sender` is the license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> holder. </span><span class="z-keyword">Note</span><span class="z-comment"> that the root license of an NFT should be tethered to and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> transferred with the NFT. Whenever an NFT is transferred by calling the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC721 `transfer` function, the holder of the root license should be</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-keyword"> changed</span><span class="z-comment"> to the new NFT owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseId</span><span class="z-comment"> The identifier for the queried license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _licenseHolder</span><span class="z-comment"> The new license holder</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferSublicense</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _licenseId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _licenseHolder</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Licenses to an NFT in general have a tree structure as below:</p> <p><img src="https://wg-eips.ritovision.com/5218/./assets/license-tree.png" alt="The license tree" /></p> <p>There is one root license to the NFT itself, granting the NFT owner some rights to the linked work. The NFT owner (i.e., the root license holder) may create sublicenses, holders of which may also create sublicenses recursively.</p> <p>The full log of license creation, transfer, and revocation <em>must</em> be traceable via event logs. Therefore, all license creations and transfers <em>must</em> emit a corresponding log event. Revocation may differ a bit. An implementation of this EIP may emit a <code>Revoke</code> event only when a license is revoked in a function call, or for every revoked license, both are sufficient to trace the status of all licenses. The former costs less gas if revoking a license automatically revokes all sublicenses under it, while the latter is efficient in terms of interrogation of a license status. Implementers should make the tradeoffs depending on their license terms.</p> <p>The <code>revoker</code> of a license may be the licensor, the license holder, or a smart contract address which calls the <code>revokeLicense</code> function when some conditions are met. Implementers should be careful with the authorization, and may make the <code>revoker</code> smart contract forward compatible with transfers by not hardcoding the addresses of <code>licensor</code> or <code>licenseHolder</code>.</p> <p>The license <code>URI</code> may point to a JSON file that conforms to the "ERC-5218 Metadata JSON Schema" as below, which adopts the "three-layer" design of the Creative Commons Licenses:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">License Metadata</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">legal-code</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The legal code of the license.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">human-readable</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The human readable license deed.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">machine-readable</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The machine readable code of the license that can be recognized by software, such as CC REL.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note that this EIP doesn't include a function to update license URI so the license terms should be persistent by default. It is recommended to store the license metadata on a decentralized storage service such as IPFS or adopt the IPFS-style URI which encodes the hash of the metadata for integrity verification. On the other hand, license updatability, if necessary in certain scenarios, can be realized by revoking the original license and creating a new license, or adding a updating function, the eligibile caller of which must be carefully specified in the license and securely implemented in the smart contract.</p> <p>The <code>supportsInterface</code> method MUST return <code>true</code> when called with <code>0xac7b5ca9</code>.</p> <h2 id="rationale">Rationale</h2> <p>This EIP aims to allow tracing all licenses to an NFT to facilitate right management. The ERC-721 standard only logs the property but not the legal rights tethered to NFTs. Even when logging the license via the optional ERC-721 Metadata extension, sublicenses are not traceable, which doesn't comply with the transparency goals of Web3. Some implementations attempt to get around this limitation by minting NFTs to represent a particular license, such as the BAYC #6068 Royalty-Free Usage License. This is not an ideal solution because the linking between different licenses to an NFT is ambiguous. An auditor has to investigate all NFTs in the blockchain and inspect the metadata which hasn't been standardized in terms of sublicense relationship. To avoid these problems, this EIP logs all licenses to an NFT in a tree data structure, which is compatible with ERC-721 and allows efficient traceability.</p> <p>This EIP attempts to tether NFTs with copyright licenses to the creative work by default and is not subject to the high legal threshold for copyright ownership transfers which require an explicit signature from the copyright owner. To transfer and track copyright ownership, one may possibly integrate ERC-5218 and <a href="https://wg-eips.ritovision.com/5289/">ERC-5289</a> after careful scrutinizing and implement a smart contract that atomically (1) signs the legal contract via ERC-5289, and (2) transfers the NFT together with the copyright ownership via ERC-5218. Either both take place or both revert.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with the current ERC-721 standards: a contract can inherit from both ERC-721 and ERC-5218 at the same time.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are available <a href="https://wg-eips.ritovision.com/5218/./assets/contracts/test/Contract.t.sol">here</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation maintains the following data structures:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> License</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> active</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> whether the license is active</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> tokenId</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> the identifier of the NFT the license is tethered to</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> parentLicenseId</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> the identifier of the parent license</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> licenseHolder</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> the license holder</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> uri</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> the license URI</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> revoker</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> the license revoker</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span> License</span><span>)</span><span class="z-storage z-type"> private</span><span> _licenses</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> maps from a license identifier to a license object</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _licenseIds</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> maps from an NFT to its root license identifier</span></span></code></pre> <p>Each NFT has a license tree and starting from each license, one can trace back to the root license via <code>parentLicenseId</code> along the path.</p> <p>In the reference implementation, once a license is revoked, all sublicenses under it are revoked. This is realized in a <em>lazy</em> manner for lower gas cost, i.e., assign <code>active=false</code> only for licenses that are explicitly revoked in a <code>revokeLicense</code> function call. Therefore, <code>isLicenseActive</code> returns <code>true</code> only if all its ancestral licenses haven't been revoked.</p> <p>For non-root licenses, the creation, transfer and revocation are straightforward:</p> <ol> <li>Only the holder of an active license can create sublicenses.</li> <li>Only the holder of an active license can transfer it to a different license holder.</li> <li>Only the revoker of an active license can revoke it.</li> </ol> <p>The root license must be compatible with <code>ERC-721</code>:</p> <ol> <li>When an NFT is minted, a license is granted to the NFT owner.</li> <li>When an NFT is transferred, the license holder is changed to the new owner of the NFT.</li> <li>When a root license is revoked, the NFT is returned to the NFT creator, and the NFT creator may later transfer it to a new owner with a new license.</li> </ol> <p>The complete implementation can be found <a href="https://wg-eips.ritovision.com/5218/./assets/contracts/src/RightsManagement.sol">here</a>.</p> <p>In addition, the <a href="https://wg-eips.ritovision.com/5218/./assets/ic3license/ic3license.pdf">Token-Bound NFT License</a> is specifically designed to work with this interface and provides a reference to the language of NFT licenses.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Implementors of the <code>IERC5218</code> standard must consider thoroughly the permissions they give to <code>licenseHolder</code> and <code>revoker</code>. If the license is ever to be transferred to a different license holder, the <code>revoker</code> smart contract should not hardcode the <code>licenseHolder</code> address to avoid undesirable scenarios.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-07-07T00:00:00+00:00 2026-02-11T14:48:26+00:00 Isaac Patkahttps://github.com/ipatka COALA Licensing Taskforceinfo@coala.org https://wg-eips.ritovision.com/5554/

An interface for describing and enforcing the legal use and remix of an NFT. On-chain registry of rights, attribution and derivative links.

<h2 id="abstract">Abstract</h2> <p>This EIP extends any other token standard to provide:</p> <ul> <li>Explicit rights for the token holder related to commercial exploitation, derivative works, and reproduction;</li> <li><a href="https://wg-eips.ritovision.com/5218/">EIP-5218</a> interface for creating, viewing, and checking the status of licenses</li> <li>Standard format for extended license information in the token metadata;</li> <li>Standard events to track off chain creation of derivative works, commercial exploitation, and reproduction;</li> <li>On chain tracking of derivative works and reproductions</li> <li>Additional required fields in the smart contract to reference the copyright owner</li> <li>Function calls for commercial exploitation, derivative works and reproduction.</li> </ul> <h2 id="motivation">Motivation</h2> <p>NFTs still face legal uncertainty, and many now realize that the rights associated with an NFT are just as important as the NFT itself. Our goal is to help the ecosystem reach clear consensus and broad understanding of what purchasers of NFTs are acquiring in terms of copyright or other rights.</p> <p>Today, purchasing the NFT of a digital work is not the same as purchasing the copyright in that work. In most cases, the NFT does not even incorporate the digital work; it only references it via a hash. Hence, the NFT holder owns a unique digital copy of the work, but does not necessarily enjoy the right to reproduce, redistribute, or otherwise exploit that work—unless explicitly provided for by the copyright owner. It typically only includes the right to privately enjoy the work and display it publicly on social media or in virtual galleries.</p> <p>We aim to create a new set of licenses with modular terms and conditions—à la Creative Commons—in order to enable artists to increase the value of their NFT by associating additional rights to them (e.g. the right to create derivative works, or to allow for the commercial usage of the underlying works). Our solution will allow for any licensed rights to be granted, only and exclusively, to the current holders of an NFT, and to be transferred automatically to the new token holders every time the NFT is being transferred.</p> <p>An on chain registry of copyrighted material will help in discovery of the rights associated with the NFTs that have been created with this protocol.</p> <p>Our current work is drafting the legalese and technical specifications.</p> <h2 id="specification">Specification</h2> <p>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> <p>Every contract compliant with this EIP must implement the <code>IERC5554</code> interface:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5554</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC5218</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CommercialExploitation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _tokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _licenseId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> _externalUri</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ReproductionCreated</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _tokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _licenseId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _reproductionId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _reproduction</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _reproductionTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DerivativeCreated</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _tokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _licenseId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _derivativeId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _derivative</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _derivativeTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the copyright owner address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the token exists</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The identifier for the queried token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> address</span><span class="z-comment"> of the copyright owner</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getCopyrightOwner</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Requests to log an execution of a license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the token issuance conditions are met</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The identifier for the queried token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> tracking reproduction ID</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> logReproduction</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> reproduction</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> reproductionTokenId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Requests to log an executions of a license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the token issuance conditions are met</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The identifier for the queried token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> tracking derivative ID</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> logDerivative</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> derivative</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> derivativeTokenId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Requests to log an execution of a license</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the commercial exploitation conditions are met</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The identifier for the queried token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> logCommercialExploitation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> uri</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the token associated with a reproduction</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the reproduction exists</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _reproductionId</span><span class="z-comment"> The identifier for the reproduction</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> The identifier for the token used to generate the reproduction</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getReproductionTokenId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _reproductionId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the token associated with a reproduction</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the reproduction exists</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _reproductionId</span><span class="z-comment"> The identifier for the reproduction</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> The identifier for the license used to generate the reproduction</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getReproductionLicenseId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _reproductionId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the token associated with a reproduction</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the reproduction exists</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _reproductionId</span><span class="z-comment"> The identifier for the derivative work</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> address</span><span class="z-comment"> The address of the reproduction collection</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getReproductionCollection</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _reproductionId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the token associated with a derivative</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the derivative exists</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _derivativeId</span><span class="z-comment"> The identifier for the derivative work</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> The identifier for the token used to generate the derivative work</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDerivativeTokenId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _derivativeId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the token associated with a derivative</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the derivative exists</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _derivativeId</span><span class="z-comment"> The identifier for the derivative work</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> The identifier for the license used to generate the derivative work</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDerivativeLicenseId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _derivativeId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve the token associated with a derivative</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws unless the derivative exists</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _derivativeId</span><span class="z-comment"> The identifier for the derivative work</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> address</span><span class="z-comment"> The address of the derivative collection</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDerivativeCollection</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _derivativeId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="token-based-attribution-remix">Token based Attribution/ Remix</h3> <p>On chain derivative works and reproductions</p> <ul> <li>Reproductions and derivative works are tracked in the contract.</li> </ul> <h3 id="event-based-attribution">Event based attribution</h3> <p>For commercial exploitation or other off-chain uses of a creative work, this EIP defines events to be emitted to track the use of the work.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> CommercialExploitation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenID</span><span>, </span><span class="z-support">string</span><span class="z-variable"> uri</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> logCommercialExploitation</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> uri</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> bool;</span></span></code></pre><h4 id="example">Example:</h4> <p>When a token holder uses an NFT for off-chain merchandise, log a reference to the off-chain work in the event uri</p> <h3 id="required-fields">Required fields</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> copyrightOwner</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> address;</span></span></code></pre> <p>Copyright owner per tokenID. Could just be the tokenID owner in a simple use case, or something else if desired by the creator.</p> <h2 id="rationale">Rationale</h2> <p>We expand here upon the Motivation section to justify every decision made with regard to the specs of the standard:</p> <p>The <code>getLicenseId()</code> function takes a tokenID as a parameter, making it possible for different tokenID to be associated with different licensing terms.</p> <p>LicenseURI links to a content-addressed file that stipulates the terms and conditions of the license in actual legal language, so that the license can be read and understood by those who want to understand which rights are associated with the work of authorship, and which additional rights are granted through the acquisition of the NFT.</p> <p>When the license allows for the reproduction and/or for the creation of a derivative work only to the token holders, there needs to be a way to verify that the new NFT or the derivative NFT was created legitimately. The standard ensures this by enabling the current token holder to call a function, e.g. logDerivative which checks that the caller has a valid license to execute</p> <p>For commercial exploitation or other off-chain uses of a creative work, the standard implements the <code>logCommercialExploitation()</code> that makes it possible to keep track of which commercial exploitations have been made, and when. This makes it possible to verify that all commercial exploitation were legitimately done.</p> <p>The standard introduces a new field, <code>copyrightOwner</code>, which indicates the address of the current holder of the copyright in the work. If multiple copyright owners exist, a multisig address (or DAO) can be used.</p> <p>The artist address is not registered as an on-chain variable, but rather as part of the metadata, because it is an immutable field.</p> <p>If any, the parents of the work (i.e. the works that it is derived upon) must be part of the metadata information, so that people can verify that the NFT has obtained a DerivativeWork for each one of its parents.</p> <p>This licensing framework is intended to create a system to facilitate the licensing of rights that “follow the token” through a public licensing framework. This is not meant to be used for cases in which an exclusive right is licensed through a personal license to a specific actor (e.g. the copyright owner providing a third-party with the right to commercially exploit the work, regardless of whether they hold the token). This also is not designed to account for the sub-licensing case (e.g. licensing the right to one party to license third parties to engage in commercial exploitation), since this should rather be done via a personal copyright licensing scheme.</p> <h3 id="examples">Examples</h3> <h4 id="bored-koalas-merchandising">Bored Koalas merchandising</h4> <p>Vigdís creates a PFP collection of Bored Koalas, which is subject to standard copyright restrictions: no one has the right to reproduce, distribute, communicate, commercialize or remix these works. However, she wants to give specific permissions to those who hold a NFT from the collection. She mints the collection with this EIP, introducing a conditional license that allows for the current token holder to display the Bored Koala associated with each NFT and commercialize it for the purpose of merchandising only.</p> <p>Neža has purchased one of these Bored Koalas. She wants to produce merchandising to be distributed at his blockchain conference. She goes to a print shop and asks them to make t-shirts with the Bored Koala image of the NFT she has purchased. The print shop can verify that she has the right to commercially exploit the work by verifying that they are the holder of the Bored Koala NFT, and verifying the terms of the license associated with it. (NB: this does not require a sub-license to be granted to the print shop, because the commercial exploitation implies the right to commission third parties to engage in such commercial exploitation). Neža brings the t-shirts to her conference and puts them for sale. When doing so, she calls the <code>logCommercialExploitation()</code> function from the NFT smart contract in order to track that the commercial exploitation was done at a time while she was the token holder.</p> <h4 id="musical-remix">Musical Remix</h4> <p>Matti is an up and coming songwriter in the emerging web3 music ecosystem. For the upcoming crypto conference, he creates a hit song called “Degens in the Night”. Instead of listing the song on a web2 platform, Matti mints the song as an NFT using this EIP, with a dual licensing scheme: a general public licenses that allows for the free reproduction and redistribution of the work, given proper attribution (e.g. Creative Commons BY-NC-ND) and a conditional license which allows for the token holder to remix the song, in exchange of a particular lump sum (e.g. 1ETH) and under the condition that the derivative work is released under the same licensing terms as the original work Lyyli wants to create a cover of that song, which she calls “Degens in the Parisian Night”. She purchases the NFT and mints a new derivative NFT under a new smart contract using this EIP standard. She then calls the <code>requestDerivativeToken()</code> function and send 1ETH to the original NFT smart contract, in order to request that a DerivativeToken be assigned to the new smart contract she has created. The smart contract automatically approves the request to assign a Derivative Token to the new smart contract of Lyyli. This can be used as a proof that the derivative work is indeed a legitimate work, which has been approved by the copyright owner of the original work. During the conference hundreds of other web3 music creators host a side event with Degens in the Night remixes playing until 4am.</p> <h4 id="royalties-remix">Royalties Remix</h4> <p>Alice created a 3D model of a motorcycle, which she wants everyone to remix, under the condition that she gets royalty from the commercial exploitation of all derivative works. She release her work as an NFT with this EIP, with a dual licensing scheme: a general public licenses that allows for the free reproduction and redistribution of the work, given proper attribution (e.g. Creative Commons BY-NC-ND) and a conditional license which allows for the token holder to remix the song, under the condition that the derivative work is released under the same licensing terms as the original work, and that there is a split of the royalties between himself and the remixer.</p> <p>Jane wants to create a derivative work of the motorcycle. She purchases the NFT and mints a new derivative NFT under a new smart contract that uses this EIP, which includes a royalty split for Alice. She then calls the <code>requestDerivativeToken()</code> function from the original NFT smart contract in order to request that a DerivativeToken be assigned to the new smart contract she has created. Alice decided that the smart contract shall not automate the approval or rejection of the request, but rather wait for her to validate or invalidate the request, after she has verified that the design and provisions of the new smart contract, namely that it does indeed replicate the same terms and conditions as the original work and that it incorporates the proper amount of royalties. She approves the request to assign a Derivative Token to the new smart contract of Jane. When people purchase Jane’s NFT, the royalties are split to ensure the proper redistribution of the generated profit to Alice.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The interface defined in this standard is backward compatible with most NFT standards used in the Ethereum ecosystem as of this writing.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-07-04T00:00:00+00:00 2026-02-11T14:48:26+00:00 Hadrien Crouboishttps://github.com/Amxx Francisco Giordanohttps://github.com/frangio https://wg-eips.ritovision.com/5805/

An interface for voting weight tracking, with delegation support

<h2 id="abstract">Abstract</h2> <p>Many DAOs (decentralized autonomous organizations) rely on tokens to represent one's voting power. In order to perform this task effectively, the token contracts need to include specific mechanisms such as checkpoints and delegation. The existing implementations are not standardized. This ERC proposes to standardize the way votes are delegated from one account to another, and the way current and past votes are tracked and queried. The corresponding behavior is compatible with many token types, including but not limited to <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>. This ERC also considers the diversity of time tracking functions, allowing the voting tokens (and any contract associated with it) to track the votes based on <code>block.number</code>, <code>block.timestamp</code>, or any other non-decreasing function.</p> <h2 id="motivation">Motivation</h2> <p>Beyond simple monetary transactions, decentralized autonomous organizations are arguably one of the most important use cases of blockchain and smart contract technologies. Today, many communities are organized around a governance contract that allows users to vote. Among these communities, some represent voting power using transferable tokens (<a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, other). In this context, the more tokens one owns, the more voting power one has. Governor contracts, such as Compound's <code>GovernorBravo</code>, read from these "voting token" contracts to get the voting power of the users.</p> <p>Unfortunately, simply using the <code>balanceOf(address)</code> function present in most token standards is not good enough:</p> <ul> <li>The values are not checkpointed, so a user can vote, transfer its tokens to a new account, and vote again with the same tokens.</li> <li>A user cannot delegate their voting power to someone else without transferring full ownership of the tokens.</li> </ul> <p>These constraints have led to the emergence of voting tokens with delegation that contain the following logic:</p> <ul> <li>Users can delegate the voting power of their tokens to themselves or a third party. This creates a distinction between balance and voting weight.</li> <li>The voting weights of accounts are checkpointed, allowing lookups for past values at different points in time.</li> <li>The balances are not checkpointed.</li> </ul> <p>This ERC is proposing to standardize the interface and behavior of these voting tokens.</p> <p>Additionally, the existing (non-standardized) implementations are limited to <code>block.number</code> based checkpoints. This choice causes many issues in a multichain environment, where some chains (particularly L2s) have an inconsistent or unpredictable time between blocks. This ERC also addresses this issue by allowing the voting token to use any time tracking function it wants, and exposing it so that other contracts (such as a Governor) can stay consistent with the token checkpoints.</p> <h2 id="specification">Specification</h2> <p>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> <p>Following pre-existing (but not-standardized) implementation, the EIP proposes the following mechanism.</p> <p>Each user account (address) can delegate to an account of its choice. This can be itself, someone else, or no one (represented by <code>address(0)</code>). Assets held by the user cannot express their voting power unless they are delegated.</p> <p>When a "delegator" delegates its tokens voting power to a "delegatee", its balance is added to the voting power of the delegatee. If the delegator changes its delegation, the voting power is subtracted from the old delegatee's voting power and added to the new delegate's voting power. The voting power of each account is tracked through time so that it is possible to query its value in the past. With tokens being delegated to at most one delegate at a given point in time, double voting is prevented.</p> <p>Whenever tokens are transferred from one account to another, the associated voting power should be deducted from the sender's delegate and added to the receiver's delegate.</p> <p>Tokens that are delegated to <code>address(0)</code> should not be tracked. This allows users to optimize the gas cost of their token transfers by skipping the checkpoint update for their delegate.</p> <p>To accommodate different types of chains, we want the voting checkpoint system to support different forms of time tracking. On the Ethereum mainnet, using block numbers provides backward compatibility with applications that historically use it. On the other hand, using timestamps provides better semantics for end users, and accommodates use cases where the duration is expressed in seconds. Other monotonic functions could also be deemed relevant by developers based on the characteristics of future applications and blockchains.</p> <p>Both timestamps, block numbers, and other possible modes use the same external interfaces. This allows transparent binding of third-party contracts, such as governor systems, to the vote tracking built into the voting contracts. For this to be effective, the voting contracts must, in addition to all the vote-tracking functions, expose the current value used for time-tracking.</p> <h3 id="methods">Methods</h3> <h4 id="erc-6372-clock-and-clock-mode"><a href="https://wg-eips.ritovision.com/6372/">ERC-6372</a>: clock and CLOCK_MODE</h4> <p>Compliant contracts SHOULD implement ERC-6372 (Contract clock) to announce the clock that is used for vote tracking.</p> <p>If the contract does not implement ERC-6372, it MUST operate according to a block number clock, exactly as if ERC-6372's <code>CLOCK_MODE</code> returned <code>mode=blocknumber&amp;from=default</code>.</p> <p>In the following specification, "the current clock" refers to either the result of ERC-6372's <code>clock()</code>, or the default of <code>block.number</code> in its absence.</p> <h4 id="getvotes">getVotes</h4> <p>This function returns the current voting weight of an account. This corresponds to all the voting power delegated to it at the moment this function is called.</p> <p>As tokens delegated to <code>address(0)</code> should not be counted/snapshotted, <code>getVotes(0)</code> SHOULD always return <code>0</code>.</p> <p>This function MUST be implemented</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> g</span><span class="z-string">etVotes</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">ccount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> v</span><span class="z-string">otingWeight</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="getpastvotes">getPastVotes</h4> <p>This function returns the historical voting weight of an account. This corresponds to all the voting power delegated to it at a specific timepoint. The timepoint parameter MUST match the operating mode of the contract. This function SHOULD only serve past checkpoints, which SHOULD be immutable.</p> <ul> <li>Calling this function with a timepoint that is greater or equal to the current clock SHOULD revert.</li> <li>Calling this function with a timepoint strictly smaller than the current clock SHOULD NOT revert.</li> <li>For any integer that is strictly smaller than the current clock, the value returned by <code>getPastVotes</code> SHOULD be constant. This means that for any call to this function that returns a value, re-executing the same call (at any time in the future) SHOULD return the same value.</li> </ul> <p>As tokens delegated to <code>address(0)</code> should not be counted/snapshotted, <code>getPastVotes(0,x)</code> SHOULD always return <code>0</code> (for all values of <code>x</code>).</p> <p>This function MUST be implemented</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> g</span><span class="z-string">etPastVotes</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">ccount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> t</span><span class="z-string">imepoint</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> v</span><span class="z-string">otingWeight</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="delegates">delegates</h4> <p>This function returns the address to which the voting power of an account is currently delegated.</p> <p>Note that if the delegate is <code>address(0)</code> then the voting power SHOULD NOT be checkpointed, and it should not be possible to vote with it.</p> <p>This function MUST be implemented</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">elegates</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">ccount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">elegatee</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span></code></pre><h4 id="delegate">delegate</h4> <p>This function changes the caller's delegate, updating the vote delegation in the meantime.</p> <p>This function MUST be implemented</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">elegate</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">elegatee</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span><span> [</span><span>]</span></span></code></pre><h4 id="delegatebysig">delegateBySig</h4> <p>This function changes an account's delegate using a signature, updating the vote delegation in the meantime.</p> <p>This function MUST be implemented</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">elegateBySig</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">elegatee</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> n</span><span class="z-string">once</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> e</span><span class="z-string">xpiry</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> v</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int8</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> s</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ytes32</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span><span> [</span><span>]</span></span></code></pre> <p>This signature should follow the <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> format:</p> <p>A call to <code>delegateBySig(delegatee, nonce, expiry, v, r, s)</code> changes the signer's delegate to <code>delegatee</code>, increment the signer's nonce by 1, and emits a corresponding <code>DelegateChanged</code> event, and possibly <code>DelegateVotesChanged</code> events for the old and the new delegate accounts, if and only if the following conditions are met:</p> <ul> <li>The current timestamp is less than or equal to <code>expiry</code>.</li> <li><code>nonces(signer)</code> (before the state update) is equal to <code>nonce</code>.</li> </ul> <p>If any of these conditions are not met, the <code>delegateBySig</code> call must revert. This translates to the following solidity code:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span>expiry </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>)</span></span> <span class="giallo-l"><span class="z-support">bytes</span><span> signer </span><span class="z-keyword">=</span><span class="z-support"> ecrecover</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span></span> <span class="giallo-l"><span> hex</span><span class="z-string">&quot;1901&quot;</span><span>,</span></span> <span class="giallo-l"><span> DOMAIN_SEPARATOR</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;Delegation(address delegatee,uint256 nonce,uint256 expiry)&quot;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> delegatee</span><span>,</span></span> <span class="giallo-l"><span> nonce</span><span>,</span></span> <span class="giallo-l"><span> expiry</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> v</span><span>,</span><span> r</span><span>,</span><span> s</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span>signer </span><span class="z-keyword">!=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span>nounces</span><span>[</span><span>signer</span><span>]</span><span class="z-keyword"> ==</span><span> nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> increment nonce</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> set delegation of `signer` to `delegatee`</span></span></code></pre> <p>where <code>DOMAIN_SEPARATOR</code> is defined according to <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>. The <code>DOMAIN_SEPARATOR</code> should be unique to the contract and chain to prevent replay attacks from other domains, and satisfy the requirements of EIP-712, but is otherwise unconstrained.</p> <p>A common choice for <code>DOMAIN_SEPARATOR</code> is:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>DOMAIN_SEPARATOR </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&#39;EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)&#39;</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span>name</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span>version</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> chainid</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span></span> <span class="giallo-l"><span>)</span><span>)</span><span>;</span></span></code></pre> <p>In other words, the message is the EIP-712 typed structure:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">types</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">EIP712Domain</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chainId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">verifyingContract</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Delegation</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">delegatee</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nonce</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">expiry</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">primaryType</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Permit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">domain</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-variable z-other"> contractName</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-variable z-other"> version</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chainId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-variable z-other"> chainid</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">verifyingContract</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-variable z-other"> contractAddress</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">message</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">delegatee</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-variable z-other"> delegatee</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nonce</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-variable z-other"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">expiry</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span class="z-variable z-other"> expiry</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span><span>}</span></span></code></pre> <p>Note that nowhere in this definition do we refer to <code>msg.sender</code>. The caller of the <code>delegateBySig</code> function can be any address.</p> <p>When this function is successfully executed, the delegator's nonce MUST be incremented to prevent replay attacks.</p> <h4 id="nonces">nonces</h4> <p>This function returns the current nonce for a given account.</p> <p>Signed delegations (see <code>delegateBySig</code>) are only accepted if the nonce used in the EIP-712 signature matches the return of this function. This value of <code>nonce(delegator)</code> should be incremented whenever a call to <code>delegateBySig</code> is performed on behalf of <code>delegator</code>.</p> <p>This function MUST be implemented</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> n</span><span class="z-string">onces</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">ccount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> d</span><span class="z-string">elegator</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> n</span><span class="z-string">once</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h3 id="events">Events</h3> <h4 id="delegatechanged">DelegateChanged</h4> <p><code>delegator</code> changes the delegation of its assets from <code>fromDelegate</code> to <code>toDelegate</code>.</p> <p>MUST be emitted when the delegate for an account is modified by <code>delegate(address)</code> or <code>delegateBySig(address,uint256,uint256,uint8,bytes32,bytes32)</code>.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> D</span><span class="z-string">elegateChanged</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> e</span><span class="z-string">vent</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">elegator</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> f</span><span class="z-string">romDelegate</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> t</span><span class="z-string">oDelegate</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span></code></pre><h4 id="delegatevoteschanged">DelegateVotesChanged</h4> <p><code>delegate</code> available voting power changes from <code>previousBalance</code> to <code>newBalance</code>.</p> <p>This MUST be emitted when:</p> <ul> <li>an account (that holds more than 0 assets) updates its delegation from or to <code>delegate</code>,</li> <li>an asset transfer from or to an account that is delegated to <code>delegate</code>.</li> </ul> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> D</span><span class="z-string">elegateVotesChanged</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> e</span><span class="z-string">vent</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">elegate</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">reviousBalance</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> n</span><span class="z-string">ewBalance</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h3 id="solidity-interface">Solidity interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5805</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC6372</span><span> /* (</span><span class="z-entity z-name">optional</span><span>) */ </span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DelegateChanged</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> delegator</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> fromDelegate</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> toDelegate</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DelegateVotesChanged</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> delegate</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> previousBalance</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> newBalance</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getVotes</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getPastVotes</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> timepoint</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegates</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> nonces</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> delegate</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> delegatee</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegateBySig</span><span>(</span><span class="z-support">address</span><span class="z-variable"> delegatee</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> nonce</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> expiry</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="expected-properties">Expected properties</h3> <p>Let <code>clock</code> be the current clock.</p> <ul> <li>For all timepoints <code>t &lt; clock</code>, <code>getVotes(address(0))</code> and <code>getPastVotes(address(0), t)</code> SHOULD return 0.</li> <li>For all accounts <code>a != 0</code>, <code>getVotes(a)</code> SHOULD be the sum of the "balances" of all the accounts that delegate to <code>a</code>.</li> <li>For all accounts <code>a != 0</code> and all timestamp <code>t &lt; clock</code>, <code>getPastVotes(a, t)</code> SHOULD be the sum of the "balances" of all the accounts that delegated to <code>a</code> when <code>clock</code> overtook <code>t</code>.</li> <li>For all accounts <code>a</code>, <code>getPastVotes(a, t)</code> MUST be constant after <code>t &lt; clock</code> is reached.</li> <li>For all accounts <code>a</code>, the action of changing the delegate from <code>b</code> to <code>c</code> MUST not increase the current voting power of <code>b</code> (<code>getVotes(b)</code>) and MUST not decrease the current voting power of <code>c</code> (<code>getVotes(c)</code>).</li> </ul> <h2 id="rationale">Rationale</h2> <p>Delegation allows token holders to trust a delegate with their vote while keeping full custody of their token. This means that only a small-ish number of delegates need to pay gas for voting. This leads to better representation of small token holders by allowing their votes to be cast without requiring them to pay expensive gas fees. Users can take over their voting power at any point, and delegate it to someone else, or to themselves.</p> <p>The use of checkpoints prevents double voting. Votes, for example in the context of a governance proposal, should rely on a snapshot defined by a timepoint. Only tokens delegated at that timepoint can be used for voting. This means any token transfer performed after the snapshot will not affect the voting power of the sender/receiver's delegate. This also means that in order to vote, someone must acquire tokens and delegate them before the snapshot is taken. Governors can, and do, include a delay between the proposal is submitted and the snapshot is taken so that users can take the necessary actions (change their delegation, buy more tokens, ...).</p> <p>While timestamps produced by ERC-6372's <code>clock</code> are represented as <code>uint48</code>, <code>getPastVotes</code>'s timepoint argument is <code>uint256</code> for backward compatibility. Any timepoint <code>&gt;=2**48</code> passed to <code>getPastVotes</code> SHOULD cause the function to revert, as it would be a lookup in the future.</p> <p><code>delegateBySig</code> is necessary to offer a gasless workflow to token holders that do not want to pay gas for voting.</p> <p>The <code>nonces</code> mapping is given for replay protection.</p> <p>EIP-712 typed messages are included because of their widespread adoption in many wallet providers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Compound and OpenZeppelin already provide implementations of voting tokens. The delegation-related methods are shared between the two implementations and this ERC. For the vote lookup, this ERC uses OpenZeppelin's implementation (with return type uint256) as Compound's implementation causes significant restrictions of the acceptable values (return type is uint96).</p> <p>Both implementations use <code>block.number</code> for their checkpoints and do not implement ERC-6372, which is compatible with this ERC.</p> <p>Existing governors, that are currently compatible with OpenZeppelin's implementation will be compatible with the "block number mode" of this ERC.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Before doing a lookup, one should check the return value of <code>clock()</code> and make sure that the parameters of the lookup are consistent. Performing a lookup using a timestamp argument on a contract that uses block numbers will very likely cause a revert. On the other end, performing a lookup using a block number argument on a contract that uses timestamps will likely return 0.</p> <p>Though the signer of a <code>Delegation</code> may have a certain party in mind to submit their transaction, another party can always front-run this transaction and call <code>delegateBySig</code> before the intended party. The result is the same for the <code>Delegation</code> signer, however.</p> <p>Since the ecrecover precompile fails silently and just returns the zero address as <code>signer</code> when given malformed messages, it is important to ensure <code>signer != address(0)</code> to avoid <code>delegateBySig</code> from delegating "zombie funds" belonging to the zero address.</p> <p>Signed <code>Delegation</code> messages are censorable. The relaying party can always choose to not submit the <code>Delegation</code> after having received it, withholding the option to submit it. The <code>expiry</code> parameter is one mitigation to this. If the signing party holds ETH they can also just submit the <code>Delegation</code> themselves, which can render previously signed <code>Delegation</code>s invalid.</p> <p>If the <code>DOMAIN_SEPARATOR</code> contains the <code>chainId</code> and is defined at contract deployment instead of reconstructed for every signature, there is a risk of possible replay attacks between chains in the event of a future chain split.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-06-29T00:00:00+00:00 2026-02-11T14:48:26+00:00 Hyungsuk Kanghttps://github.com/hskang9 Viktor Pernjekhttps://github.com/smuxx https://wg-eips.ritovision.com/5252/

An ERC-5114 extension that aids in preventing arbitrary loss of funds

<h2 id="abstract">Abstract</h2> <p>This EIP proposes a form of smart contract design pattern and a new type of account abstraction on how one's finance should be managed, ensuring transparency of managing investments and protection with self-sovereignty even from its financial operators. This EIP enables greater self-sovereignty of one's assets using a personal finance contract for each individual. The separation between an investor's funds and the operation fee is clearly specified in the personal smart contract, so investors can ensure safety from arbitrary loss of funds by the operating team's control.</p> <p>This EIP extends <a href="https://wg-eips.ritovision.com/5114/">ERC-5114</a> to further enable transferring fund to other accounts for mobility between managing multiple wallets.</p> <h2 id="motivation">Motivation</h2> <p>Decentralized finance (DeFi) faces a trust issue. Smart contracts are often proxies, with the actual logic of the contract hidden away in a separate logic contract. Many projects include a multi-signature "wallet" with unnecessarily-powerful permissions. And it is not possible to independently verify that stablecoins have enough real-world assets to continue maintaining their peg, creating a large loss of funds (such as happened in the official bankruptcy announcement of Celsius and UST de-pegging and anchor protocol failure). One should not trust exchanges or other third parties with one's own investments with the operators' clout in Web3.0.</p> <p>Smart contracts are best implemented as a promise between two parties written in code, but current DeFi contracts are often formed using less than 7 smart contracts to manage their whole investors' funds, and often have a trusted key that has full control. This is evidently an issue, as investors have to trust contract operators with their funds, meaning that users do not actually own their funds.</p> <p>The pattern with personal finance contract also offers more transparency than storing mixed fund financial data in the operating team's contract. With a personal finance contract, an account's activity is easier to track than one global smart contract's activity. The pattern introduces a Non-Fungiible Account-Bound Token (ABT) to store credentials from the personal finance contract.</p> <h3 id="offchain-identity-vs-soul-bound-token-on-credentials">Offchain-identity vs Soul-bound token on credentials</h3> <p>This EIP provides a better alternative to off-chain identity solutions which take over the whole system because their backends eventually rely on the trust of the operator, not cryptographic proof (e.g. Proof-of-work, Proof-of-stake, etc). Off-chain identity as credentials are in direct opposition to the whole premise of crypto. Soulbound tokens are a better, verifiable credential, and data stored off-chain is only to store token metadata.</p> <h2 id="specification">Specification</h2> <p>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> <p>The specification consists of two patterns for <strong>Interaction</strong> and <strong>Governance</strong>.</p> <h3 id="interaction">Interaction</h3> <h4 id="interfaces">Interfaces</h4> <p>The interaction pattern consists of 4 components for interaction; manager, factory, finance, account-bound token, and extension.</p> <p>Interaction contract pattern is defined with these contracts:</p> <ul> <li>A soul-bound or account bound token contract to give access to interact with a financial contract with credentials</li> <li>A manager contract that interacts first contact with an investor</li> <li>A factory contract that creates a financial contract for each user</li> <li>A finance contract that can interact with the investor</li> </ul> <h4 id="requirements">Requirements</h4> <p>A soul-bound or account bound token contract is defined with these properties:</p> <ol> <li>It SHALL be non-fungible and MUST satisfy <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>.</li> <li>Credentials SHOULD be represented with its metadata with <code>tokenURI()</code> function.</li> <li>It MUST only reference factory to verify its minting.</li> <li>If it is transferrable, it is account-bound. If not, it is soul-bound.</li> </ol> <p>A manager contract is defined with these properties:</p> <ol> <li>It MUST be the only kind of contract which calls factory to create.</li> <li>It SHOULD store all related configurations for financial parameters.</li> </ol> <p>A factory contract is defined with these properties:</p> <ol> <li>It SHALL clone the finance contract with uniform implementation.</li> <li>It MUST be the only contract that can mint account-bound token.</li> <li>It MUST keep an recent id of account bound token.</li> </ol> <p>A finance contract is defined with these properties:</p> <ol> <li>A finance contract MUST only be initialized once from factory contract in constructor.</li> <li>Funds in the contract SHALL NOT be transferred to other contracts nor accounts unless sender who owns soul-bound or account bound token signs to do so.</li> <li>Every state-changing function of the smart contract MUST only accept sender who owns soul-bound or account bound-token except global function(e.g. liquidation).</li> <li>Global function SHOULD be commented as <code>/* global */</code> to clarify the function is can be accessed with anyone.</li> <li>Each finance contract SHOULD be able to represent transaction that has happened only with those who had account-bound token.</li> <li>If soul-bound token is used for access, the finance contract MUST be able to represent transaction that has happened only between whom had the private key and the finance contract.</li> </ol> <h4 id="contracts">Contracts</h4> <p><img src="https://wg-eips.ritovision.com/5252/./assets/media/media.svg" alt="Diagram" /></p> <center> Contract Diagram of [ERC-5252](../05252.md) </center> <p><strong><code>Manager</code></strong>: <strong><code>Manager</code></strong> contract acts as an entry point to interact with the investor. The contract also stores parameters for <strong><code>Finance</code></strong> contract.</p> <p><strong><code>Factory</code></strong>: <strong><code>Factory</code></strong> contract manages contract bytecode to create for managing investor's fund and clones <strong><code>Finance</code></strong> contract on <strong><code>Manager</code></strong> contract's approval. It also mints account-bound tokens to interact with the <code>Finance</code> contract.</p> <p><strong><code>Finance</code></strong>: <strong><code>Finance</code></strong> contract specifies all rules on managing an investor's fund. The contract is only accessible with an account that has an Account-bound token. When an investor deposits a fund to <strong><code>Manager</code></strong> contract, the contract sends the fund to <strong><code>Finance</code></strong> contract account after separating fees for operation.</p> <p><strong><code>Account-bound token</code></strong>: <strong><code>Account-bound token</code></strong> contract in this EIP can bring the <strong><code>Finance</code></strong> contract's data and add metadata. For example, if there is a money market lending <strong><code>Finance</code></strong> contract, its <strong><code>Account-bound token</code></strong> can show how much balance is in agreement using SVG.</p> <p><strong><code>Extension</code></strong>: <strong><code>Extension</code></strong> contract is another contract that can utilize locked funds in <strong><code>Finance</code></strong> contract. The contract can access with <strong><code>Finance</code></strong> contract on operator's approval managed in <strong><code>Manager</code></strong> contract. Example use case of <code>Extension</code> can be a membership.</p> <p><strong><code>Metadata</code></strong>: <strong><code>Metadata</code></strong> contract is the contract where it stores metadata related to account credentials. Credential related data are stored with specific key. Images are usually displayed as SVG, but offchain image is possible.</p> <hr /> <h3 id="governance">Governance</h3> <p>The governance pattern consists of 2 components; influencer and governor.</p> <h4 id="interfaces-1">Interfaces</h4> <h4 id="requirements-1">Requirements</h4> <p>An influencer contract is defined with these properties:</p> <ol> <li>The contract SHALL manage multiplier for votes.</li> <li>The contract SHALL set a decimal to calculated normalized scores.</li> <li>The contract SHALL set a function where governance can decide factor parameters.</li> </ol> <p>A governor contract is defined with these properties:</p> <ol> <li>The contract MUST satisfy Governor contract from OpenZeppelin.</li> <li>The contract SHALL refer influencer contract for multiplier</li> <li>The contract MUST limit transfer of account bound token once claimed for double vote prevention.</li> </ol> <h4 id="from-token-governance-to-contribution-based-governance">From Token Governance To Contribution Based Governance</h4> <table><thead><tr><th></th><th>Token Governance</th><th>Credential-based Governance</th></tr></thead><tbody> <tr><td>Enforcement</td><td>More tokens, more power</td><td>More contribution, More power</td></tr> <tr><td>Incentives</td><td>More tokens, more incentives</td><td>More contribution, more incentives</td></tr> <tr><td>Penalty</td><td>No penalty</td><td>Loss of power</td></tr> <tr><td>Assignment</td><td>One who holds the token</td><td>One who has the most influence</td></tr> </tbody></table> <center> Token Governance vs Credential Based Governance </center> <p>Token governance is not sustainable in that it gives <strong>more</strong> power to "those who most want to rule". Any individual who gets more than 51% of the token supply can forcefully take control.</p> <p>New governance that considers contributions to the protocol is needed because:</p> <ul> <li><strong>Rulers can be penalized on breaking the protocol</strong></li> <li><strong>Rulers can be more effectively incentivized on maintaining the protocol</strong></li> </ul> <p>The power should be given to "those who are most responsible". Instead of locked or owned tokens, voting power is determined with contributions marked in Account Bound Tokens (ABT). This EIP defines this form of voting power as <strong><code>Influence</code></strong>.</p> <h4 id="calculating-influence">Calculating Influence</h4> <p><strong><code>Influence</code></strong> is a multiplier on staked tokens that brings more voting power of a DAO to its contributors. To get <strong><code>Influence</code></strong>, a score is calculated on weighted contribution matrix. Then, the score is normalized to give a member's position in whole distribution. Finally, the multiplier is determined on the position in every community members.</p> <h4 id="calculating-score">Calculating score</h4> <p>The weights represent relative importance on each factor. The total importance is the total sum of the factors. More factors that can be normalized at the time of submitting proposal can be added by community.</p> <table><thead><tr><th></th><th>Description</th></tr></thead><tbody> <tr><td>α</td><td>Contribution value per each <strong><code>Finance</code></strong> contract from current proposal</td></tr> <tr><td>β</td><td>Time they maintained <strong><code>Finance</code></strong> per each contract from current timestamp of a proposal</td></tr> </tbody></table> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(score per each ABT) = α * (contribution value) + β * (time that abt was maintained from now)</span></span></code></pre><h4 id="normalization">Normalization</h4> <p>Normalization is applied for data integrity on user's contribution in a DAO. Normalized score can be calculated from the state of submitting a proposal</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(Normalized score per each ABT) = α * (contribution value)/(total contribution value at submitting tx) + β * (time that abt was maintained)/(time passed from genesis to proposal creation)</span></span></code></pre> <p>and have a value between 0 and 1 (since α + β = 1).</p> <h4 id="multiplier">Multiplier</h4> <p>The multiplier is determined linearly from base factor (b) and multiplier(m).</p> <p>The equation for influence is :</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(influence) = m * (sum(normalized_score))</span></span></code></pre><h4 id="example">Example</h4> <p>For example, if a user has 3 <strong><code>Account-bound tokens</code></strong> with normalized score of each 1.0, 0.5, 0.3 and the locked token is 100, and multiplier is 0.5 and base factor is 1.5. Then the total influence is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0.5 * {(1.0 + 0.5 + 0.3) / 3} + 1.5 = 1.8</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> The total voting power would be</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>```</span></span> <span class="giallo-l"><span>(voting power) = 1.8 * sqrt(100) = 18</span></span></code></pre><h4 id="stakers-vs-enforcers">Stakers vs Enforcers</h4> <table><thead><tr><th></th><th>Stakers</th><th>Enforcers</th></tr></thead><tbody> <tr><td>Role</td><td>stake governance token for voting</td><td>Contributed on the system, can make proposal to change rule, more voting power like 1.5</td></tr> <tr><td>Populations</td><td>many</td><td>small</td></tr> <tr><td>Contribution</td><td>Less effect</td><td>More effect</td></tr> <tr><td>Influence</td><td>sqrt(locked token)</td><td>Influence * sqrt(locked token)</td></tr> </tbody></table> <center> Stakers vs Enforcers </center> <p><strong>Stakers</strong>: Stakers are people who vote to enforcers' proposals and get dividend for staked tokens</p> <p><strong>Enforcers</strong>: Enforcers are people who takes risk on managing protocol and contributes to the protocol by making a proposal and change to it.</p> <h4 id="contracts-1">Contracts</h4> <p><strong><code>Influencer</code></strong>: An <strong><code>Influencer</code></strong> contract stores influence configurations and measures the contribution of a user from his activities done in a registered Account Bound Token contract. The contract puts a lock on that Account Bound Token until the proposal is finalized.</p> <p><strong><code>Governor</code></strong>: <strong><code>Governor</code></strong> contract is compatible with the current governor contract in OpenZeppelin. For its special use case, it configures factors where the influencer manages and has access to changing parameters of <strong><code>Manager</code></strong> configs. Only the <code>Enforcer</code> can propose new parameters.</p> <h2 id="rationale">Rationale</h2> <h3 id="gas-saving-for-end-user">Gas saving for end user</h3> <p>The gas cost of using multiple contracts (as opposed to a single one) actually saves gas long-run if the clone factory pattern is applied. One contract storing users' states globally means each user is actually paying for the storage cost of other users after interacting with the contract. This, for example, means that MakerDAO's contract operating cost is sometimes over 0.1 ETH, limitimg users' minimum deposit for CDP in order to save gas costs. To solve inefficient n-times charging gas cost interaction for future users, one contract per user is used.</p> <h4 id="separation-between-investor-s-and-operation-fund">Separation between investor's and operation fund</h4> <p>The separation between an investor's funds and operation fee is clearly specified in the smart contract, so investors can ensure safety from arbitrary loss of funds by the operating team's control.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP has no known backward compatibility issues.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p><a href="https://wg-eips.ritovision.com/5252/assets/README/">Reference implementation</a> is a simple deposit account contract as <code>Finance</code> contract and its contribution value α is measured with deposit amount with ETH.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li> <p><strong><code>Factory</code></strong> contracts must ensure that each <strong><code>Finance</code></strong> contract is registered in the factory and check that <strong><code>Finance</code></strong> contracts are sending transactions related to their bounded owner.</p> </li> <li> <p>Reentrancy attack guard should be applied or change state before delegatecall in each user function in <strong><code>Manager</code></strong> contract or <strong><code>Finance</code></strong> contract. Otherwise, <strong><code>Finance</code></strong> can be generated as double and ruin whole indices.</p> </li> <li> <p>Once a user locks influence on a proposal's vote, an <strong><code>Account Bound Token</code></strong> cannot be transferred to another wallet. Otherwise, double influence can happen.</p> </li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-06-27T00:00:00+00:00 2026-02-11T14:48:25+00:00 Christophe Le Barshttps://github.com/clbrge https://wg-eips.ritovision.com/5185/

An interface extension for ERC-721/ERC-1155 controlled metadata updates

<h2 id="abstract">Abstract</h2> <p>This specification defines a standard way to allow controlled NFTs' metadata updates along predefined formulas. Updates of the original metadata are restricted and defined by a set of recipes and the sequence and results of these recipes are deterministic and fully verifiable with on-chain metadata updates event. The proposal depends on and extends the <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>.</p> <h2 id="motivation">Motivation</h2> <p>Storing voluminous NFT metadata on-chain is often neither practical nor cost-efficient.</p> <p>Storing NFT metadata off-chain on distributed file systems like IPFS can answer some needs of verifiable correlation and permanence between an NFT tokenId and its metadata but updates come at the cost of being all or nothing (aka changing the <code>tokenURI</code>). Bespoke solutions can be easily developed for a specific NFT smart contract but a common specification is necessary for NFT marketplaces and third parties tools to understand and verify these metadata updates.</p> <p>This ERC allows the original JSON metadata to be modified step by step along a set of predefined JSON transformation formulas. Depending on NFT use-cases, the transformation formulas can be more or less restrictive.</p> <p>As examples, an NFT representing a house could only allow append-only updates to the list of successive owners, and a game using NFT characters could let some attributes change from time to time (e.g. health, experience, level, etc) while some other would be guaranteed to never change (e.g. physicals traits etc).</p> <p>This standard extension is compatible with NFTs bridged between Ethereum and L2 networks and allows efficient caching solutions.</p> <h2 id="specification">Specification</h2> <p>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> <p>The <strong>metadata updates extension</strong> is OPTIONAL for <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> contracts.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-721/ERC-1155 Updatable Metadata Extension</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5185UpdatableMetadata</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> A distinct Uniform Resource Identifier (URI) for a set of updates</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This event emits an URI (defined in RFC 3986) of a set of metadata updates.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The URI should point to a JSON file that conforms to the &quot;NFT Metadata Updates JSON Schema&quot;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Third-party platforms such as NFT marketplace can deterministically calculate the latest</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> metadata for all tokens using these events by applying them in sequence for each token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MetadataUpdates</span><span>(</span><span class="z-support">string</span><span class="z-variable"> URI</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The original metadata SHOULD conform to the "ERC-5185 Updatable Metadata JSON Schema" which is a compatible extension of the "ERC-721 Metadata JSON Schema" defined in ERC-721.</p> <p>"ERC-5185 Updatable Metadata JSON Schema" :</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset Updatable Metadata</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Identifies the asset to which this NFT represents</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Describes the asset to which this NFT represents</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">image</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">updatable</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">engine</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">recipes</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">engine</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Non ambiguous transformation method/language (with version) to process updates along recipes defined below</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">schema</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">if present, a JSON Schema that all sequential post transformation updated metadata need to conform. If a transformed JSON does not conform, the update should be considered voided.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">recipes</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A catalog of all possibles recipes identified by their keys</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">patternProperties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">.*</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The key of this object is used to select which recipe to apply for each update</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eval</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">eval</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The evaluation formula to transform the last JSON metadata using the engine above (can take arguments)</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>"NFT Metadata Updates JSON Schema" :</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Metadata Updates JSON Schema</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">updates</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">array</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A list of updates to apply sequentially to calculate updated metadata</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">items</span><span class="z-support">&quot;</span><span>:</span><span> {</span><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/update</span><span class="z-punctuation z-definition z-string">&quot;</span><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$defs</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">update</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">tokenId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">recipeKey</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">tokenId</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The tokenId for which the update recipe should apply</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">recipeKey</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">recipeKey to use to get the JSON transformation expression in current metadata</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">args</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">arguments to pass to the JSON transformation</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="engines">Engines</h3> <p>Only one engine is currently defined in this extension proposal.</p> <p>If the engine in the original metadata is "jsonata@1.8.*", updated metadata is calculated starting from original metadata and applying each update sequentially (all updates which are present in all the URIs emitted by the event <code>MetadataUpdates</code> for which tokenId matches).</p> <p>For each step, the next metadata is obtained by the javascript calculation (or compatible jsonata implementation in other language) :</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> nextMetadata</span><span class="z-keyword"> =</span><span class="z-entity z-name"> jsonata</span><span>(</span><span class="z-variable z-other">evalString</span><span>)</span><span>.</span><span class="z-entity z-name">evaluate</span><span>(</span><span class="z-variable z-other">previousMetadata</span><span>,</span><span class="z-variable z-other"> args</span><span>)</span></span></code></pre> <p>With <code>evalString</code> is found with <code>recipeKey</code> in the original metadata recipes list.</p> <p>If the key is not present in the original metadata list, <code>previousMetadata</code> is kept as the valid updated metadata.</p> <p>If the evaluation throws any errors, <code>previousMetadata</code> is kept as the valid updated metadata.</p> <p>If a validation Schema JSON has been defined and the result JSON <code>nextMetadata</code> does not conform, that update is not valid and <code>previousMetadata</code> is kept as the valid updated metadata.</p> <h2 id="rationale">Rationale</h2> <p>There have been numerous interesting uses of <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> smart contracts that associate for each token essential and significant metadata. While some projects (e.g. EtherOrcs) have experimented successfully to manage these metadata on-chain, that experimental solution will always be limited by the cost and speed of generating and storing JSON on-chain. Symmetrically, while storing the JSON metadata at URI endpoint controlled by traditional servers permit limitless updates the metadata for each NFT, it is somehow defeating in many uses cases, the whole purpose of using a trustless blockchain to manage NFT: indeed users may want or demand more permanence and immutability from the metadata associated with their NFT.</p> <p>Most use cases have chosen intermediate solutions like IPFS or arweave to provide some permanence or partial/full immutability of metadata. This is a good solution when an NFT represents a static asset whose characteristics are by nature permanent and immutable (like in the art world) but less so with other use cases like gaming or NFT representing a deed or title. Distinguishable assets in a game often should be allowed to evolve and change over time in a controlled way and titles need to record real life changes.</p> <p>The advantages of this standard is precisely to allow these types of controlled transformations over time of each NFT metadata by applying sequential transformations starting with the original metadata and using formulas themselves defined in the original metadata.</p> <p>The original metadata for a given NFT is always defined as the JSON pointed by the result of <code>tokenURI</code> for <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and function <code>uri</code> for <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>.</p> <p>The on-chain log trace of updates guarantee that anyone can recalculate and verify independently the current updated metadata starting from the original metadata. The fact that the calculation is deterministic allows easy caching of intermediate transformations and the efficient processing of new updates using these caches.</p> <p>The number of updates defined by each event is to be determined by the smart contract logic and use case, but it can easily scale to thousands or millions of updates per event. The function(s) that should emit <code>MetadataUpdates</code> and the frequency of these on-chain updates is left at the discretion of this standard implementation.</p> <p>The proposal is extremely gas efficient, since gas costs are only proportional to the frequency of committing changes. Many changes for many tokens can be batched in one transaction for the cost of only one <code>emit</code>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="transformation-engines">Transformation engines</h3> <p>We have been experimenting with this generic Metadata update proposal using the JSONata transformation language.</p> <p>Here is a very simple example of a NFT metadata for an imaginary 'little monster' game :</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Monster 1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Little monsters you can play with.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">attributes</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span><span class="z-support"> &quot;</span><span class="z-support">trait_type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Level</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</span><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-support"> &quot;</span><span class="z-support">trait_type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Stamina</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 100</span><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">updatable</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">engine</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">jsonata@1.8.*</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">recipes</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">levelUp</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">eval</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">$ ~&gt; | attributes[trait_type=&#39;Level&#39;] | {&#39;value&#39;: value + 1} |</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">updateDescription</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">eval</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">$ ~&gt; | $ | {&#39;description&#39;: $newDescription} |</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This updatable metadata can only be updated to increment by one the trait attribute "Level".</p> <p>An example JSON updates metadata would be :</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">updates</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span><span class="z-support">&quot;</span><span class="z-support">tokenId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">action</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">levelUp</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-support">&quot;</span><span class="z-support">tokenId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">action</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">levelUp</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-support">&quot;</span><span class="z-support">tokenId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">action</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">updateDescription</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">args</span><span class="z-support">&quot;</span><span>:</span><span>{</span><span class="z-support">&quot;</span><span class="z-support">newDescription</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Now I&#39;m a big monster</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-support">&quot;</span><span class="z-support">tokenId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">action</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">levelUp</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-support">&quot;</span><span class="z-support">tokenId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">3</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support">&quot;</span><span class="z-support">action</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">levelUp</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>A malicious recipe in the original metadata might be constructed as a DDoS vector for third parties marketplaces and tools that calculate NFT updated JSON metadata. They are encouraged to properly encapsulate software in charge of these calculations and put limits for the engine updates processing.</p> <p>Smart contracts should be careful and conscious of using this extension and still allow the metadata URI to be updated in some contexts (by not having the same URI returned by <code>tokenURI</code> or <code>uri</code> for a given tokenId over time). They need to take into account if previous changes could have been already broadcasted for that NFT by the contract, if these changes are compatible with the new "original metadata" and what semantic they decide to associate by combining these two kinds of "updates".</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The proposal is fully compatible with both <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>. Third-party applications that don't support this EIP will still be able to use the original metadata for each NFT.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-06-23T00:00:00+00:00 2026-02-11T14:48:26+00:00 Paul Gauvreauhttps://github.com/0xpaulio Nick Johnsonhttps://github.com/arachnid https://wg-eips.ritovision.com/5559/

The cross chain write deferral protocol provides a mechanism to defer the storage & resolution of mutations to off-chain handlers

<h2 id="abstract">Abstract</h2> <p>The following standard provides a mechanism in which smart contracts can request various tasks to be resolved by an external handler. This provides a mechanism in which protocols can reduce the gas fees associated with storing data on mainnet by deferring the handling of it to another system/network. These external handlers act as an extension to the core L1 contract.</p> <p>This standard outlines a set of handler types that can be used for managing the execution and storage of mutations (tasks), as well as their corresponding tradeoffs. Each handler type has associated operational costs, finality guarantees, and levels of decentralization. By further specifying the type of handler that the mutation is deferred to, the protocol can better define how to permission and secure their system.</p> <p>This standard can be implemented in conjunction with <a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a> to provide a mechanism in which protocols can reside on and be interfaced through an L1 contract on mainnet, while being able to resolve and mutate data stored in external systems.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a> provides a mechanism by which off-chain lookups can be defined inside smart contracts in a transparent manner. In addition, it provides a scheme in which the resolved data can be verified on-chain. However, there lacks a standard by which mutations can be requested through the native contract, to be performed on the off-chain data. Furthermore, with the increase in L2 solutions, smart contract engineers have additional tools that can be used to reduce the storage and transaction costs of performing mutations on the Ethereum mainnet.</p> <p>A specification that allows smart contracts to defer the storage and resolution of data to external handlers facilitates writing clients agnostic to the storage solution being used, enabling new applications that can operate without knowledge of the underlying handlers associated with the contracts they interact with.</p> <p>Examples of this include:</p> <ul> <li>Allowing the management of ENS domains externally resolved on an L2 solution or off-chain database as if they were native L1 tokens.</li> <li>Allowing the management of digital identities stored on external handlers as if they were in the stored in the native L1 smart contract.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="overview">Overview</h3> <p>There are two main handler classifications: L2 Contract and Off-Chain Database. These are determined based off of where the handler is deployed. The handler classifications are used to better define the different security guarantees and requirements associated with its deployment.</p> <p>From a high level:</p> <ul> <li>Handlers hosted on an L2 solution are EVM compatible and can use attributes native to the Ethereum ecosystem (such as address) to permission access.</li> <li>Handlers hosted on an Off-Chain Database require additional parameters and signatures to correctly enforce the authenticity and check the validity of a request.</li> </ul> <p>A deferred mutation can be handled in as little as two steps. However, in some cases the mutation might be deferred multiple times.</p> <ol> <li>Querying or sending a transaction to the contract</li> <li>Querying or sending a transaction to the handler using the parameters provided in step 1</li> </ol> <p>In step 1, a standard blockchain call operation is made to the contract. The contract either performs the operation as intended or reverts with an error that specifies the type of handler that the mutation is being deferred to and the corresponding parameters required to perform the subsequent mutation. There are two types of errors that the contract can revert with, but more may be defined in other EIPs:</p> <ul> <li><code>StorageHandledByL2(chainId, contractAddress)</code></li> <li><code>StorageHandledByOffChainDatabase(sender, url, data)</code></li> </ul> <p>In step 2, the client builds and performs a new request based off of the type of error received in (1). These handshakes are outlined in the sections below:</p> <ul> <li><a href="https://wg-eips.ritovision.com/5559/#data-stored-in-an-l2">StorageHandledByL2</a></li> <li><a href="https://wg-eips.ritovision.com/5559/#data-stored-in-an-off-chain-database">StorageHandledByOffChainDatabase</a></li> </ul> <p>In some cases, the mutation may be deferred multiple times</p> <ul> <li><a href="https://wg-eips.ritovision.com/5559/#data-stored-in-an-l2-an-off-chain-database">Storage Deferred Twice L1 &gt; L2 &gt; Off-Chain</a></li> </ul> <h3 id="data-stored-in-an-l1">Data Stored in an L1</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌──────┐ ┌───────────┐ </span></span> <span class="giallo-l"><span>│Client│ │L1 Contract│ </span></span> <span class="giallo-l"><span>└──┬───┘ └─────┬─────┘ </span></span> <span class="giallo-l"><span> │ │ </span></span> <span class="giallo-l"><span> │ somefunc(...) │ </span></span> <span class="giallo-l"><span> ├─────────────────────────►│ </span></span> <span class="giallo-l"><span> │ │ </span></span> <span class="giallo-l"><span> │ response │ </span></span> <span class="giallo-l"><span> │◄─────────────────────────┤ </span></span> <span class="giallo-l"><span> │ │ </span></span></code></pre> <p>In the case in which no reversion occurs, data is stored in the L1 contract when the transaction is executed.</p> <h3 id="data-stored-in-an-l2">Data Stored in an L2</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌──────┐ ┌───────────┐ ┌─────────────┐</span></span> <span class="giallo-l"><span>│Client│ │L1 Contract│ │ L2 Contract │</span></span> <span class="giallo-l"><span>└──┬───┘ └─────┬─────┘ └──────┬──────┘</span></span> <span class="giallo-l"><span> │ │ │ </span></span> <span class="giallo-l"><span> │ somefunc(...) │ │ </span></span> <span class="giallo-l"><span> ├────────────────────────────────────────────────────►│ │ </span></span> <span class="giallo-l"><span> │ │ │ </span></span> <span class="giallo-l"><span> │ revert StorageHandledByL2(chainId, contractAddress) │ │ </span></span> <span class="giallo-l"><span> │◄────────────────────────────────────────────────────┤ │ </span></span> <span class="giallo-l"><span> │ │ │ </span></span> <span class="giallo-l"><span> │ Execute Tx [chainId] [contractAddress] [callData] │ │ </span></span> <span class="giallo-l"><span> ├─────────────────────────────────────────────────────┼──────────────►│ </span></span> <span class="giallo-l"><span> │ │ │ </span></span> <span class="giallo-l"><span> │ response │ │ </span></span> <span class="giallo-l"><span> │◄────────────────────────────────────────────────────┼───────────────┤ </span></span> <span class="giallo-l"><span> │ │ │ </span></span></code></pre> <p>The call or transaction to the L1 contract reverts with the <code>StorageHandledByL2(chainId, contractAddress)</code> error.</p> <p>In this case, the client builds a new transaction for <code>contractAddress</code> with the original <code>callData</code> and sends it to a RPC of their choice for the corresponding <code>chainId</code>. The <code>chainId</code> parameter corresponds to an L2 Solution that is EVM compatible.</p> <h4 id="example">Example</h4> <p>Suppose a contract has the following method:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setAddr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> a</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Data for this mutations is stored and tracked on an EVM compatible L2. The contract author wants to reduce the gas fees associated with the contract, while maintaining the interoperability and decentralization of the protocol. Therefore, the mutation is deferred to a off-chain handler by reverting with the <code>StorageHandledByL2(chainId, contractAddress)</code> error.</p> <p>One example of a valid implementation of <code>setAddr</code> would be:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setAddr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> a</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> StorageHandledByL2</span><span>(</span></span> <span class="giallo-l"><span class="z-constant"> 10</span><span>,</span></span> <span class="giallo-l"><span> _l2HandlerContractAddress</span></span> <span class="giallo-l"><span> )</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>For example, if a contract returns the following data in an <code>StorageHandledByL2</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>chainId = 10</span></span> <span class="giallo-l"><span>contractAddress = 0x0000111122223333444455556666777788889999aaaabbbbccccddddeeeeffff</span></span></code></pre> <p>The user, receiving this error, creates a new transaction for the corresponding <code>chainId</code>, and builds a transaction with the original <code>callData</code> to send to <code>contractAddress</code>. The user will have to choose an RPC of their choice to send the transaction to for the corresponding <code>chainId</code>.</p> <h3 id="data-stored-in-an-off-chain-database">Data Stored in an Off-Chain Database</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌──────┐ ┌───────────┐ ┌────────────────────┐</span></span> <span class="giallo-l"><span>│Client│ │L1 Contract│ │ Off-Chain Database │</span></span> <span class="giallo-l"><span>└──┬───┘ └─────┬─────┘ └──────────┬─────────┘</span></span> <span class="giallo-l"><span> │ │ │ </span></span> <span class="giallo-l"><span> │ somefunc(...) │ │ </span></span> <span class="giallo-l"><span> ├────────────────────────────────────────────────────►│ │ </span></span> <span class="giallo-l"><span> │ │ │ </span></span> <span class="giallo-l"><span> │ revert StorageHandledByOffChainDatabase(sender, | │ </span></span> <span class="giallo-l"><span> │ urls, requestParams) │ │ </span></span> <span class="giallo-l"><span> │◄────────────────────────────────────────────────────┤ │ </span></span> <span class="giallo-l"><span> │ │ │ </span></span> <span class="giallo-l"><span> │ HTTP Request [requestParams, signature] │ │ </span></span> <span class="giallo-l"><span> ├─────────────────────────────────────────────────────┼──────────────────►│ </span></span> <span class="giallo-l"><span> │ │ │ </span></span> <span class="giallo-l"><span> │ response │ │ </span></span> <span class="giallo-l"><span> │◄────────────────────────────────────────────────────┼───────────────────┤ </span></span> <span class="giallo-l"><span> │ │ │ </span></span></code></pre> <p>The call or transaction to the L1 contract reverts with the <code>StorageHandledByOffChainDatabase(sender, url, data)</code> error.</p> <p>In this case, the client performs a HTTP POST request to the gateway service. The gateway service is defined by <code>url</code>. The body attached to the request is a JSON object that includes <code>sender</code>, <code>data</code>, and a signed copy of <code>data</code> denoted <code>signature</code>. The signature is generated according to a <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>, in which a typed data signature is generated using domain definition, <code>sender</code>, and the message context, <code>data</code>.</p> <p><code>sender</code> ia an ABI-encoded struct defined as:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Struct used to define the domain of the typed data signature, defined in EIP-712.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> name</span><span class="z-comment"> The user friendly name of the contract that the signature corresponds to.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> version</span><span class="z-comment"> The version of domain object being used.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> chainId</span><span class="z-comment"> The ID of the chain that the signature corresponds to (ie Ethereum mainnet: 1, Goerli testnet: 5, ...). </span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> verifyingContract</span><span class="z-comment"> The address of the contract that the signature pertains to.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> domainData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> version</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> chainId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> verifyingContract</span><span>;</span></span> <span class="giallo-l"><span>}</span><span> </span></span></code></pre> <p><code>data</code> ia an abi encoded struct defined as:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Struct used to define the message context used to construct a typed data signature, defined in EIP-712, </span></span> <span class="giallo-l"><span class="z-comment">* to authorize and define the deferred mutation being performed.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> functionSelector</span><span class="z-comment"> The function selector of the corresponding mutation.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> sender</span><span class="z-comment"> The address of the user performing the mutation (msg.sender).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parameter</span><span class="z-comment">[] A list of &lt;key, value&gt; pairs defining the inputs used to perform the deferred mutation.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> messageData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> functionSelector</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> sender</span><span>;</span></span> <span class="giallo-l"><span> parameter</span><span>[</span><span>]</span><span> parameters</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> expirationTimestamp</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Struct used to define a parameter for Off-Chain Database Handler deferral.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> name</span><span class="z-comment"> The variable name of the parameter.</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> value</span><span class="z-comment"> The string encoded value representation of the parameter.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> parameter</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> value</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>signature</code> is generated by using the <code>sender</code> &amp; <code>data</code> parameters to construct an <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> typed data signature.</p> <p>The body used in the HTTP POST request is defined as:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;abi encoded domainData (sender)&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">data</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;abi encoded messageData (data)&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signature</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;EIP-712 typed data signature of corresponding message data &amp; domain definition&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="example-1">Example</h4> <p>Suppose a contract has the following method:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setAddr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> a</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre> <p>Data for this mutations is stored and tracked in some kind of off-chain database. The contract author wants the user to be able to authorize and make modifications to their <code>Addr</code> without having to pay a gas fee. Therefore, the mutation is deferred to a off-chain handler by reverting with the <code>StorageHandledByOffChainDatabase(sender, url, data)</code> error.</p> <p>One example of a valid implementation of <code>setAddr</code> would be:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setAddr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> a</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> IWriteDeferral</span><span>.</span><span>parameter</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> params </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span> IWriteDeferral</span><span>.</span><span>parameter</span><span>[</span><span>]</span><span>(</span><span class="z-constant">3</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> params</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span>name </span><span class="z-keyword">=</span><span class="z-string"> &quot;node&quot;</span><span>;</span></span> <span class="giallo-l"><span> params</span><span>[</span><span class="z-constant">0</span><span>]</span><span>.</span><span>value </span><span class="z-keyword">=</span><span> BytesToString</span><span>.</span><span class="z-entity z-name">bytes32ToString</span><span>(</span><span>node</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> params</span><span>[</span><span class="z-constant">1</span><span>]</span><span>.</span><span>name </span><span class="z-keyword">=</span><span class="z-string"> &quot;coin_type&quot;</span><span>;</span></span> <span class="giallo-l"><span> params</span><span>[</span><span class="z-constant">1</span><span>]</span><span>.</span><span>value </span><span class="z-keyword">=</span><span> Strings</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>coinType</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> params</span><span>[</span><span class="z-constant">2</span><span>]</span><span>.</span><span>name </span><span class="z-keyword">=</span><span class="z-string"> &quot;address&quot;</span><span>;</span></span> <span class="giallo-l"><span> params</span><span>[</span><span class="z-constant">2</span><span>]</span><span>.</span><span>value </span><span class="z-keyword">=</span><span> BytesToString</span><span>.</span><span class="z-entity z-name">bytesToString</span><span>(</span><span>a</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> StorageHandledByOffChainDatabase</span><span>(</span></span> <span class="giallo-l"><span> IWriteDeferral</span><span>.</span><span class="z-entity z-name">domainData</span><span>(</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> name</span><span class="z-keyword">:</span><span> WRITE_DEFERRAL_DOMAIN_NAME</span><span>,</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword">:</span><span> WRITE_DEFERRAL_DOMAIN_VERSION</span><span>,</span></span> <span class="giallo-l"><span> chainId</span><span class="z-keyword">:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span> verifyingContract</span><span class="z-keyword">:</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span> _offChainDatabaseUrl</span><span>,</span></span> <span class="giallo-l"><span> IWriteDeferral</span><span>.</span><span class="z-entity z-name">messageData</span><span>(</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> functionSelector</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg</span><span>.</span><span>sig</span><span>,</span></span> <span class="giallo-l"><span> sender</span><span class="z-keyword">:</span><span class="z-variable z-language"> msg.sender</span><span>,</span></span> <span class="giallo-l"><span> parameters</span><span class="z-keyword">:</span><span> params</span><span>,</span></span> <span class="giallo-l"><span> expirationTimestamp</span><span class="z-keyword">:</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp </span><span class="z-keyword">+</span><span> _offChainDatabaseTimeoutDuration</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>For example, if a contract reverts with the following:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>StorageHandledByOffChainDatabase(</span></span> <span class="giallo-l"><span> (</span></span> <span class="giallo-l"><span> &quot;CoinbaseResolver&quot;, </span></span> <span class="giallo-l"><span> &quot;1&quot;, </span></span> <span class="giallo-l"><span> 1, </span></span> <span class="giallo-l"><span> 0x32f94e75cde5fa48b6469323742e6004d701409b</span></span> <span class="giallo-l"><span> ), </span></span> <span class="giallo-l"><span> &quot;https://example.com/r/{sender}&quot;, </span></span> <span class="giallo-l"><span> (</span></span> <span class="giallo-l"><span> 0xd5fa2b00, </span></span> <span class="giallo-l"><span> 0x727f366727d3c9cc87f05d549ee2068f254b267c, </span></span> <span class="giallo-l"><span> [</span></span> <span class="giallo-l"><span> (&quot;node&quot;, &quot;0x418ae76a9d04818c7a8001095ad01a78b9cd173ee66fe33af2d289b5dc5f4cba&quot;), </span></span> <span class="giallo-l"><span> (&quot;coin_type&quot;, &quot;60&quot;), </span></span> <span class="giallo-l"><span> (&quot;address&quot;, &quot;0x727f366727d3c9cc87f05d549ee2068f254b267c&quot;)</span></span> <span class="giallo-l"><span> ], </span></span> <span class="giallo-l"><span> 181</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>The user, receiving this error, constructs the typed data signature, signs it, and performs that request via a HTTP POST to <code>url</code>.</p> <p>Example HTTP POST request body including <code>requestParams</code> and <code>signature</code>:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">sender</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;abi encoded domainData (sender)&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">data</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;abi encoded messageData (data)&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">signature</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;EIP-712 typed data signature of corresponding message data &amp; domain definition&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note that the message could be altered could be altered in any way, shape, or form prior to signature and request. It is the backend's responsibility to correctly permission and process these mutations. From a security standpoint, this is no different then a user being able to call a smart contract with any params they want, as it is the smart contract's responsibility to permission and handle those requests.</p> <h3 id="data-stored-in-an-l2-an-off-chain-database">Data Stored in an L2 &amp; an Off-Chain Database</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌──────┐ ┌───────────┐ ┌─────────────┐ ┌────────────────────┐</span></span> <span class="giallo-l"><span>│Client│ │L1 Contract│ │ L2 Contract │ │ Off-Chain Database │</span></span> <span class="giallo-l"><span>└──┬───┘ └─────┬─────┘ └──────┬──────┘ └──────────┬─────────┘</span></span> <span class="giallo-l"><span> │ │ │ │</span></span> <span class="giallo-l"><span> │ somefunc(...) │ │ │</span></span> <span class="giallo-l"><span> ├────────────────────────────────────────────────────►│ │ │</span></span> <span class="giallo-l"><span> │ │ │ │</span></span> <span class="giallo-l"><span> │ revert StorageHandledByL2(chainId, contractAddress) │ │ │</span></span> <span class="giallo-l"><span> │◄────────────────────────────────────────────────────┤ │ │</span></span> <span class="giallo-l"><span> │ │ │ │</span></span> <span class="giallo-l"><span> │ Execute Tx [chainId] [contractAddress] [callData] │ │ │</span></span> <span class="giallo-l"><span> ├─────────────────────────────────────────────────────┼──────────────►│ │</span></span> <span class="giallo-l"><span> │ │ │ │</span></span> <span class="giallo-l"><span> │ revert StorageHandledByOffChainDatabase(sender, url, data) │ │</span></span> <span class="giallo-l"><span> │◄────────────────────────────────────────────────────┼───────────────┤ │</span></span> <span class="giallo-l"><span> │ │ │ │</span></span> <span class="giallo-l"><span> │ HTTP Request {requestParams, signature} │ │ │</span></span> <span class="giallo-l"><span> ├─────────────────────────────────────────────────────┼───────────────┼───────────────────►│</span></span> <span class="giallo-l"><span> │ │ │ │</span></span> <span class="giallo-l"><span> │ response │ │ │</span></span> <span class="giallo-l"><span> │◄────────────────────────────────────────────────────┼───────────────┼────────────────────┤</span></span> <span class="giallo-l"><span> │ │ │ │</span></span></code></pre> <p>The call or transaction to the L1 contract reverts with the <code>StorageHandledByL2(chainId, contractAddress)</code> error.</p> <p>In this case, the client builds a new transaction for <code>contractAddress</code> with the original <code>callData</code> and sends it to a RPC of their choice for the corresponding <code>chainId</code>.</p> <p>That call or transaction to the L2 contract then reverts with the <code>StorageHandledByOffChainDatabase(sender, url, data)</code> error.</p> <p>In this case, the client then performs a HTTP POST request against the gateway service. The gateway service is defined by <code>url</code>. The body attached to the request is a JSON object that includes <code>sender</code>, <code>data</code>, and <code>signature</code> -- a typed data signature corresponding to <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>.</p> <h3 id="events">Events</h3> <p>When making changes to core variables of the handler, the corresponding event MUST be emitted. This increases the transparency associated with different managerial actions. Core variables include <code>chainId</code> and <code>contractAddress</code> for L2 solutions and <code>url</code> for Off-Chain Database solutions. The events are outlined below in the WriteDeferral Interface.</p> <h3 id="write-deferral-interface">Write Deferral Interface</h3> <p>Below is a basic interface that defines and describes all of the reversion types and their corresponding parameters.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.13</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IWriteDeferral</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">//////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> EVENTS</span></span> <span class="giallo-l"><span class="z-comment"> //////////////////////////////////////////////////////////////</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Event raised when the default chainId is </span><span class="z-keyword">changed</span><span class="z-comment"> for the corresponding L2 handler.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> L2HandlerDefaultChainIdChanged</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> previousChainId</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newChainId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Event raised when the contractAddress is </span><span class="z-keyword">changed</span><span class="z-comment"> for the L2 handler corresponding to chainId.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> L2HandlerContractAddressChanged</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> chainId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> previousContractAddress</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newContractAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Event raised when the url is </span><span class="z-keyword">changed</span><span class="z-comment"> for the corresponding Off-Chain Database handler.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OffChainDatabaseHandlerURLChanged</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> previousUrl</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newUrl</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">//////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> STRUCTS</span></span> <span class="giallo-l"><span class="z-comment"> //////////////////////////////////////////////////////////////</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Struct used to define the domain of the typed data signature, defined in EIP-712.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> name</span><span class="z-comment"> The user friendly name of the contract that the signature corresponds to.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> version</span><span class="z-comment"> The version of domain object being used.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> chainId</span><span class="z-comment"> The ID of the chain that the signature corresponds to (ie Ethereum mainnet: 1, Goerli testnet: 5, ...). </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> verifyingContract</span><span class="z-comment"> The address of the contract that the signature pertains to.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> domainData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> version</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> chainId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> verifyingContract</span><span>;</span></span> <span class="giallo-l"><span> }</span><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Struct used to define the message context used to construct a typed data signature, defined in EIP-712, </span></span> <span class="giallo-l"><span class="z-comment"> * to authorize and define the deferred mutation being performed.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> functionSelector</span><span class="z-comment"> The function selector of the corresponding mutation.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> sender</span><span class="z-comment"> The address of the user performing the mutation (msg.sender).</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> parameter</span><span class="z-comment">[] A list of &lt;key, value&gt; pairs defining the inputs used to perform the deferred mutation.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> messageData</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> functionSelector</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> sender</span><span>;</span></span> <span class="giallo-l"><span> parameter</span><span>[</span><span>]</span><span> parameters</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> expirationTimestamp</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Struct used to define a parameter for off-chain Database Handler deferral.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> name</span><span class="z-comment"> The variable name of the parameter.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> value</span><span class="z-comment"> The string encoded value representation of the parameter.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> parameter</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> value</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment">//////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-comment"> ERRORS</span></span> <span class="giallo-l"><span class="z-comment"> //////////////////////////////////////////////////////////////</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Error to raise when mutations are being deferred to an L2.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> chainId</span><span class="z-comment"> Chain ID to perform the deferred mutation to.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> contractAddress</span><span class="z-comment"> Contract Address at which the deferred mutation should transact with.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> StorageHandledByL2</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> chainId</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractAddress</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Error to raise when mutations are being deferred to an Off-Chain Database.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> sender</span><span class="z-comment"> the EIP-712 domain definition of the corresponding contract performing the off-chain database, write </span></span> <span class="giallo-l"><span class="z-comment"> * deferral reversion.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> url</span><span class="z-comment"> URL to request to perform the off-chain mutation.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> data</span><span class="z-comment"> the EIP-712 message signing data context used to authorize and instruct the mutation deferred to the </span></span> <span class="giallo-l"><span class="z-comment"> * off-chain database handler. </span></span> <span class="giallo-l"><span class="z-comment"> * In order to authorize the deferred mutation to be performed, the user must use the domain definition (sender) and message data </span></span> <span class="giallo-l"><span class="z-comment"> * (data) to construct a type data signature request defined in EIP-712. This signature, message data (data), and domainData (sender) </span></span> <span class="giallo-l"><span class="z-comment"> * are then included in the HTTP POST request, denoted sender, data, and signature.</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Example HTTP POST request:</span></span> <span class="giallo-l"><span class="z-comment"> * {</span></span> <span class="giallo-l"><span class="z-comment"> * &quot;sender&quot;: &lt;abi encoded domainData (sender)&gt;,</span></span> <span class="giallo-l"><span class="z-comment"> * &quot;data&quot;: &lt;abi encoded message data (data)&gt;,</span></span> <span class="giallo-l"><span class="z-comment"> * &quot;signature&quot;: &lt;EIP-712 typed data signature of corresponding message data &amp; domain definition&gt;</span></span> <span class="giallo-l"><span class="z-comment"> * }</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> StorageHandledByOffChainDatabase</span><span>(</span></span> <span class="giallo-l"><span> domainData sender</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> string</span><span> url</span><span>,</span><span> </span></span> <span class="giallo-l"><span> messageData data</span></span> <span class="giallo-l"><span> )</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="use-of-transactions-with-storage-deferral-reversions">Use of transactions with storage-deferral reversions</h3> <p>In some cases the contract might conditionally defer and handle mutations, in which case a transaction may be required. It is simple to use this method for sending transactions that may result in deferral reversions, as a client should receive the corresponding reversion while <code>preflighting</code> the transaction.</p> <p>This functionality is ideal for applications that want to allow their users to define the security guarantees and costs associated with their actions. For example, in the case of a decentralized identity profile, a user might not care if their data is decentralized and chooses to defer the handling of their records to the off-chain handler to reduce gas fees and on-chain transactions.</p> <h2 id="rationale">Rationale</h2> <h3 id="use-of-revert-to-convey-call-information">Use of <code>revert</code> to convey call information</h3> <p><a href="https://wg-eips.ritovision.com/3668/">EIP-3668</a> adopted the idea of using a <code>revert</code> to convey call information. It was proposed as a simple mechanism in which any pre-existing interface or function signature could be satisfied while maintain a mechanism to instruct and trigger an off-chain lookup.</p> <p>This is very similar for the write deferral protocol, defined in this EIP; without any modifications to the ABI or underlying EVM, <code>revert</code> provides a clean mechanism in which we can "return" a typed instruction - and the corresponding elements to complete that action - without modifying the signature of the corresponding function. This makes it easy to comply with pre-existing interfaces and infrastructure.</p> <h3 id="use-of-multiple-reversion-handler-types-to-better-define-security-guarantees">Use of multiple reversion &amp; handler types to better define security guarantees</h3> <p>By further defining the class of the handler, it gives the developer increased granularity to define the characteristics and different guarantees associated storing the data off-chain. In addition, different handlers require different parameters and verification mechanisms. This is very important for the transparency of the protocol, as they store data outside of the native ethereum ecosystem. Common implementations of this protocol could include storing non-operational data in L2 solutions and off-chain databases to reduce gas fees, while maintaining open interoperability.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing contracts that do not wish to use this specification are unaffected. Clients can add support for Cross Chain Write Deferrals to all contract calls without introducing any new overhead or incompatibilities.</p> <p>Contracts that require Cross Chain Write Deferrals will not function in conjunction with clients that do not implement this specification. Attempts to call these contracts from non-compliant clients will result in the contract throwing an exception that is propagated to the user.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Deferred mutations should never resolve to mainnet ethereum. Such attempts to defer the mutation back to ETH could include hijacking attempts in which the contract developer is trying to get the user to sign and send a malicious transaction. Furthermore, when a transaction is deferred to an L2 system, it must use the original <code>calldata</code>, this prevents against potentially malicious contextual changes in the transaction.</p> <h3 id="fingerprinting-attacks">Fingerprinting attacks</h3> <p>As all deferred mutations will include the <code>msg.sender</code> parameter in <code>data</code>, it is possible that <code>StorageHandledByOffChainDatabase</code> reversions could fingerprint wallet addresses and the corresponding IP address used to make the HTTP request. The impact of this is application-specific and something the user should understand is a risk associated with off-chain handlers. To minimize the security impact of this, we make the following recommendations:</p> <ol> <li>Smart contract developers should provide users with the option to resolve data directly on the network. Allowing them to enable on-chain storage provides the user with a simple cost-benefit analysis of where they would like their data to resolve and different guarantees / risks associated with the resolution location.</li> <li>Client libraries should provide clients with a hook to override Cross Chain Write Deferral <code>StorageHandledByOffChainDatabase</code> calls - either by rewriting them to use a proxy service, or by denying them entirely. This mechanism or another should be written so as to easily facilitate adding domains to allowlists or blocklists.</li> </ol> <p>We encourage applications to be as transparent as possible with their setup and different precautions put in place.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-06-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Hadrien Crouboishttps://github.com/amxx https://wg-eips.ritovision.com/5143/

An extension of EIP-4626 supporting improved EOA interactions.

<h2 id="abstract">Abstract</h2> <p>The following standard extends the <a href="https://wg-eips.ritovision.com/4626/">EIP-4626</a> Tokenized Vault standard with functions dedicated to the safe interaction between EOAs and the vault when price is subject to slippage.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/4626/">EIP-4626</a> security considerations section states that:</p> <blockquote> <p>"If implementors intend to support EOA account access directly, they should consider adding an additional function call for deposit/mint/withdraw/redeem with the means to accommodate slippage loss or unexpected deposit/withdrawal limits, since they have no other means to revert the transaction if the exact output amount is not achieved."</p> </blockquote> <p>Yet, EIP-4626 does not standardize the corresponding function signatures and behaviors. For improved interroperability, and better support by wallets, it is essential that this optional functions are also standardized.</p> <h2 id="specification">Specification</h2> <p>This ERC is an extension of EIP-4626. Any contract implementing it MUST also implement EIP-4626.</p> <h3 id="methods">Methods</h3> <h4 id="deposit">deposit</h4> <p>Overloaded version of ERC-4626's <code>deposit</code>.</p> <p>Mints <code>shares</code> Vault shares to <code>receiver</code> by depositing exactly <code>assets</code> of underlying tokens.</p> <p>MUST emit the <code>Deposit</code> event.</p> <p>MUST support <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> <code>approve</code> / <code>transferFrom</code> on <code>asset</code> as a deposit flow. MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the <code>deposit</code> execution, and are accounted for during <code>deposit</code>.</p> <p>MUST revert if all of <code>assets</code> cannot be deposited (due to deposit limit being reached, slippage, the user not approving enough underlying tokens to the Vault contract, etc). MUST revert if depositing <code>assets</code> underlying asset mints less then <code>minShares</code> shares.</p> <p>Note that most implementations will require pre-approval of the Vault with the Vault's underlying <code>asset</code> token.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> d</span><span class="z-string">eposit</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">ssets</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">eceiver</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">inShares</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> s</span><span class="z-string">hares</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="mint">mint</h4> <p>Overloaded version of ERC-4626's <code>mint</code>.</p> <p>Mints exactly <code>shares</code> Vault shares to <code>receiver</code> by depositing <code>assets</code> of underlying tokens.</p> <p>MUST emit the <code>Deposit</code> event.</p> <p>MUST support ERC-20 <code>approve</code> / <code>transferFrom</code> on <code>asset</code> as a mint flow. MAY support an additional flow in which the underlying tokens are owned by the Vault contract before the <code>mint</code> execution, and are accounted for during <code>mint</code>.</p> <p>MUST revert if all of <code>shares</code> cannot be minted (due to deposit limit being reached, slippage, the user not approving enough underlying tokens to the Vault contract, etc). MUST revert if minting <code>shares</code> shares cost more then <code>maxAssets</code> underlying tokens.</p> <p>Note that most implementations will require pre-approval of the Vault with the Vault's underlying <code>asset</code> token.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">int</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> s</span><span class="z-string">hares</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">eceiver</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">axAssets</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">ssets</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="withdraw">withdraw</h4> <p>Overloaded version of ERC-4626's <code>withdraw</code>.</p> <p>Burns <code>shares</code> from <code>owner</code> and sends exactly <code>assets</code> of underlying tokens to <code>receiver</code>.</p> <p>MUST emit the <code>Withdraw</code> event.</p> <p>MUST support a withdraw flow where the shares are burned from <code>owner</code> directly where <code>owner</code> is <code>msg.sender</code> or <code>msg.sender</code> has ERC-20 approval over the shares of <code>owner</code>. MAY support an additional flow in which the shares are transferred to the Vault contract before the <code>withdraw</code> execution, and are accounted for during <code>withdraw</code>.</p> <p>MUST revert if all of <code>assets</code> cannot be withdrawn (due to withdrawal limit being reached, slippage, the owner not having enough shares, etc). MUST revert if withdrawing <code>assets</code> underlying tokens requires burning more then <code>maxShares</code> shares.</p> <p>Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed. Those methods should be performed separately.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> w</span><span class="z-string">ithdraw</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">ssets</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">eceiver</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> o</span><span class="z-string">wner</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">axShares</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> s</span><span class="z-string">hares</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="redeem">redeem</h4> <p>Overloaded version of ERC-4626's <code>redeem</code>.</p> <p>Burns exactly <code>shares</code> from <code>owner</code> and sends <code>assets</code> of underlying tokens to <code>receiver</code>.</p> <p>MUST emit the <code>Withdraw</code> event.</p> <p>MUST support a redeem flow where the shares are burned from <code>owner</code> directly where <code>owner</code> is <code>msg.sender</code> or <code>msg.sender</code> has ERC-20 approval over the shares of <code>owner</code>. MAY support an additional flow in which the shares are transferred to the Vault contract before the <code>redeem</code> execution, and are accounted for during <code>redeem</code>.</p> <p>MUST revert if all of <code>shares</code> cannot be redeemed (due to withdrawal limit being reached, slippage, the owner not having enough shares, etc). MUST revert if redeeming <code>shares</code> shares sends less than <code>minAssets</code> underlying tokens to <code>receiver</code>.</p> <p>Note that some implementations will require pre-requesting to the Vault before a withdrawal may be performed. Those methods should be performed separately.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">edeem</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> s</span><span class="z-string">hares</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">eceiver</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> o</span><span class="z-string">wner</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">inAssets</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">ssets</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This ERC's functions do not replace ERC-4626 equivalent mechanisms. They are additional (overloaded) methods designed to protect EOAs interacting with the vault.</p> <p>When smart contracts interact with an ERC-4626 vault, they can preview any operation using the dedicated functions before executing the operation. This can be done atomically, with no risk of price change. This is not true of EOA, which will preview their operations on a UI, sign a transaction, and have it mined later. Between the preview and the transaction being executed, the blockchain state might change, resulting in unexpected outcomes. In particular, frontrunning make EOA's interractons with an ERC-4626 vault possibly risky.</p> <p>Other projects in the DeFi spaces, such as decentralized exchanges, already include similar mechanisms so a user can request its transaction reverts if the resulting exchange rate is not considered good enough.</p> <p>Implementing This ERC on top of an ERC-4626 contract can be done very easily. It just requires calling the corresponding ERC-4626 function and adding a revert check on the returned value.</p> <h3 id="alternative-approaches">Alternative approaches</h3> <p>This ERC aims at solving the security concerns (describes in the motivation section) at the vault level. For completeness, we have to mention that these issues can also be addressed using a generic ERC-4626 router, similar to how Uniswap V2 &amp; V3 use a router to provide good user workflows on top of the Uniswap pairs. The router approach is possibly more versatile and leaves more room for evolutions (the router can be replaced at any point) but it also leads to more expensive operations because the router needs to take temporary custody of the tokens going into the vault.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Given an existing ERC-4626 implementation</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC5143</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC4626</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deposit</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> assets</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> receiver</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> minShares</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> shares </span><span class="z-keyword">=</span><span class="z-entity z-name"> deposit</span><span>(</span><span>assets</span><span>,</span><span> receiver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>shares </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> minShares</span><span>,</span><span class="z-string"> &quot;ERC5143: deposit slippage protection&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> shares</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mint</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> shares</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> receiver</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> maxAssets</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> assets </span><span class="z-keyword">=</span><span class="z-entity z-name"> mint</span><span>(</span><span>shares</span><span>,</span><span> receiver</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>assets </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> maxAssets</span><span>,</span><span class="z-string"> &quot;ERC5143: mint slippage protection&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> assets</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> withdraw</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> assets</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> receiver</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> maxShares</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> shares </span><span class="z-keyword">=</span><span class="z-entity z-name"> withdraw</span><span>(</span><span>assets</span><span>,</span><span> receiver</span><span>,</span><span> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>shares </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> maxShares</span><span>,</span><span class="z-string"> &quot;ERC5143: withdraw slippage protection&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> shares</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> redeem</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> shares</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> receiver</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> minAssets</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> assets </span><span class="z-keyword">=</span><span class="z-entity z-name"> redeem</span><span>(</span><span>shares</span><span>,</span><span> receiver</span><span>,</span><span> owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>assets </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> minAssets</span><span>,</span><span class="z-string"> &quot;ERC5143: redeem slippage protection&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> assets</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This ERC addresses one of the security consideration raised by ERC-4626. Other considerations still apply.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-06-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sam Wilsonhttps://github.com/SamWilsn https://wg-eips.ritovision.com/5139/

Format for lists of RPC providers for Ethereum-like chains.

<h2 id="abstract">Abstract</h2> <p>This proposal specifies a JSON schema for describing lists of remote procedure call (RPC) providers for Ethereum-like chains, including their supported <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> <code>CHAIN_ID</code>.</p> <h2 id="motivation">Motivation</h2> <p>The recent explosion of alternate chains, scaling solutions, and other mostly Ethereum-compatible ledgers has brought with it many risks for users. It has become commonplace to blindly add new RPC providers using <a href="https://wg-eips.ritovision.com/3085/">EIP-3085</a> without evaluating their trustworthiness. At best, these RPC providers may be accurate, but track requests; and at worst, they may provide misleading information and frontrun transactions.</p> <p>If users instead are provided with a comprehensive provider list built directly by their wallet, with the option of switching to whatever list they so choose, the risk of these malicious providers is mitigated significantly, without sacrificing functionality for advanced users.</p> <h2 id="specification">Specification</h2> <p>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> <h3 id="list-validation-schema">List Validation &amp; Schema</h3> <p>List consumers (like wallets) MUST validate lists against the provided schema. List consumers MUST NOT connect to RPC providers present only in an invalid list.</p> <p>Lists MUST conform to the following JSON Schema:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$schema</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://json-schema.org/draft/2020-12/schema</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Ethereum RPC Provider List</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Schema for lists of RPC providers compatible with Ethereum wallets.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$defs</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">VersionBase</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Version of a list, used to communicate changes.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">major</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">minor</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">patch</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">major</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">integer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Major version of a list. Incremented when providers are removed from the list or when their chain ids change.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minimum</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minor</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">integer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Minor version of a list. Incremented when providers are added to the list.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minimum</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">patch</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">integer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Patch version of a list. Incremented for any change not covered by major or minor versions, like bug fixes.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minimum</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">preRelease</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Pre-release version of a list. Indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its major, minor, and patch versions.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">pattern</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">^[1-9A-Za-z][0-9A-Za-z]*(</span><span class="z-constant">\\</span><span class="z-string">.[1-9A-Za-z][0-9A-Za-z]*)*$</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Version</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">allOf</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/VersionBase</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">major</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minor</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">patch</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">preRelease</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">build</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Build metadata associated with a list.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">pattern</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">^[0-9A-Za-z-]+(</span><span class="z-constant">\\</span><span class="z-string">.[0-9A-Za-z-])*$</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">VersionRange</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">major</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minor</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">patch</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">preRelease</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">mode</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">allOf</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/VersionBase</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">oneOf</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">mode</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">enum</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">^</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">preRelease</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">preRelease</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mode</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">mode</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">enum</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Logo</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A URI to a logo; suggest SVG or PNG of size 64x64</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uri</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ProviderChain</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A single chain supported by a provider</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chainId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">endpoints</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">integer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Chain ID of an Ethereum-compatible network</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minimum</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoints</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">array</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minItems</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">uniqueItems</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">items</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uri</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Provider</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Description of an RPC provider.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chains</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Name of the provider.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minLength</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxLength</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 40</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">pattern</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">^[ </span><span class="z-constant">\\</span><span class="z-string">w.&#39;+</span><span class="z-constant">\\</span><span class="z-string">-%/À-ÖØ-öø-ÿ:&amp;</span><span class="z-constant">\\</span><span class="z-string">[</span><span class="z-constant">\\</span><span class="z-string">]</span><span class="z-constant">\\</span><span class="z-string">(</span><span class="z-constant">\\</span><span class="z-string">)]+$</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">logo</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/Logo</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priority</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">integer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Priority of this provider (where zero is the highest priority.)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minimum</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chains</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">array</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">items</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/ProviderChain</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Path</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A JSON Pointer path.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Patch</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">items</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">oneOf</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">value</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">op</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">path</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">path</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/Path</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The operation to perform.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">enum</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">add</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">replace</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">test</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">value</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The value to add, replace or test.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">op</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">path</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">path</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/Path</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The operation to perform.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">enum</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">remove</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">from</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">op</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">path</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">path</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/Path</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">op</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The operation to perform.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">enum</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">move</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">copy</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">from</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/Path</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A JSON Pointer path pointing to the location to move/copy from.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">array</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">timestamp</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Name of the provider list</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minLength</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxLength</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 40</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">pattern</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">^[</span><span class="z-constant">\\</span><span class="z-string">w ]+$</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">logo</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/Logo</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">version</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/Version</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">timestamp</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">date-time</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The timestamp of this list version; i.e. when this immutable version of the list was created</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">extends</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">changes</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">providers</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">oneOf</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">extends</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">changes</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">providers</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">extends</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">uri</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uri</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Location of the list to extend, as a URI.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ens</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Location of the list to extend using EIP-1577.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">version</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/VersionRange</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">oneOf</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">uri</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ens</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">ens</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">uri</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">changes</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/Patch</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">providers</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">changes</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">extends</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">providers</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">additionalProperties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/$defs/Provider</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>For illustrative purposes, the following is an example list following the schema:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Example Provider List</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">version</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">major</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">minor</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">patch</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">build</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">XPSr.p.I.g.l</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">timestamp</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2004-08-08T00:00:00.0Z</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">logo</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://mylist.invalid/logo.png</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">providers</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">some-key</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Frustrata</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chains</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoints</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://mainnet1.frustrata.invalid/</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://mainnet2.frustrana.invalid/</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 3</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoints</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://ropsten.frustrana.invalid/</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">other-key</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Sourceri</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">priority</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 3</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chains</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoints</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://mainnet.sourceri.invalid/</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 42</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">endpoints</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://kovan.sourceri.invalid</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="versioning">Versioning</h3> <p>List versioning MUST follow the <a href="https://wg-eips.ritovision.com/5139/assets/semver/">Semantic Versioning 2.0.0</a> (SemVer) specification.</p> <p>The major version MUST be incremented for the following modifications:</p> <ul> <li>Removing a provider.</li> <li>Changing a provider's key in the <code>providers</code> object.</li> <li>Removing the last <code>ProviderChain</code> for a chain id.</li> </ul> <p>The major version MAY be incremented for other modifications, as permitted by SemVer.</p> <p>If the major version is not incremented, the minor version MUST be incremented if any of the following modifications are made:</p> <ul> <li>Adding a provider.</li> <li>Adding the first <code>ProviderChain</code> of a chain id.</li> </ul> <p>The minor version MAY be incremented for other modifications, as permitted by SemVer.</p> <p>If the major and minor versions are unchanged, the patch version MUST be incremented for any change.</p> <h3 id="publishing">Publishing</h3> <p>Provider lists SHOULD be published to an Ethereum Name Service (ENS) name using <a href="https://wg-eips.ritovision.com/1577/">EIP-1577</a>'s <code>contenthash</code> mechanism on mainnet.</p> <p>Provider lists MAY instead be published using HTTPS. Provider lists published in this way MUST allow reasonable access from other origins (generally by setting the header <code>Access-Control-Allow-Origin: *</code>.)</p> <h3 id="priority">Priority</h3> <p>Provider entries MAY contain a <code>priority</code> field. A <code>priority</code> value of zero SHALL indicate the highest priority, with increasing <code>priority</code> values indicating decreasing priority. Multiple providers MAY be assigned the same priority. All providers without a <code>priority</code> field SHALL have equal priority. Providers without a <code>priority</code> field SHALL always have a lower priority than any provider with a <code>priority</code> field.</p> <p>List consumers MAY use <code>priority</code> fields to choose when to connect to a provider, but MAY ignore it entirely. List consumers SHOULD explain to users how their implementation interprets <code>priority</code>.</p> <h3 id="list-subtypes">List Subtypes</h3> <p>Provider lists are subdivided into two categories: root lists, and extension lists. A root list contains a list of providers, while an extension list contains a set of modifications to apply to another list.</p> <h4 id="root-lists">Root Lists</h4> <p>A root list has a top-level <code>providers</code> key.</p> <h4 id="extension-lists">Extension Lists</h4> <p>An extension list has top-level <code>extends</code> and <code>changes</code> keys.</p> <h5 id="specifying-a-parent-extends">Specifying a Parent (<code>extends</code>)</h5> <p>The <code>uri</code> and <code>ens</code> fields SHALL point to a source for the parent list.</p> <p>If present, the <code>uri</code> field MUST use a scheme specified in <a href="https://wg-eips.ritovision.com/5139/#publishing">Publishing</a>.</p> <p>If present, the <code>ens</code> field MUST specify an ENS name to be resolved using EIP-1577.</p> <p>The <code>version</code> field SHALL specify a range of compatible versions. List consumers MUST reject extension lists specifying an incompatible parent version.</p> <p>In the event of an incompatible version, list consumers MAY continue to use a previously saved parent list, but list consumers choosing to do so MUST display a prominent warning that the provider list is out of date.</p> <h6 id="default-mode">Default Mode</h6> <p>If the <code>mode</code> field is omitted, a parent version SHALL be compatible if and only if the parent's version number matches the left-most non-zero portion in the major, minor, patch grouping.</p> <p>For example:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">major</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">minor</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">patch</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">3</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Is equivalent to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&gt;=1.2.3, &lt;2.0.0</span></span></code></pre> <p>And:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">major</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">minor</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">patch</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">3</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Is equivalent to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&gt;=0.2.3, &lt;0.3.0</span></span></code></pre><h6 id="caret-mode">Caret Mode (<code>^</code>)</h6> <p>The <code>^</code> mode SHALL behave exactly as the default mode above.</p> <h6 id="exact-mode">Exact Mode (<code>=</code>)</h6> <p>In <code>=</code> mode, a parent version SHALL be compatible if and only if the parent's version number exactly matches the specified version.</p> <h5 id="specifying-changes-changes">Specifying Changes (<code>changes</code>)</h5> <p>The <code>changes</code> field SHALL be a JavaScript Object Notation (JSON) Patch document as specified in RFC 6902.</p> <p>JSON pointers within the <code>changes</code> field MUST be resolved relative to the <code>providers</code> field of the parent list. For example, see the following lists for a correctly formatted extension.</p> <h6 id="root-list">Root List</h6> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>TODO</span></span></code></pre><h6 id="extension-list">Extension List</h6> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>TODO</span></span></code></pre><h5 id="applying-extension-lists">Applying Extension Lists</h5> <p>List consumers MUST follow this algorithm to apply extension lists:</p> <ol> <li>Is the current list an extension list? <ul> <li>Yes: <ol> <li>Ensure that this <code>from</code> has not been seen before.</li> <li>Retrieve the parent list.</li> <li>Verify that the parent list is valid according to the JSON schema.</li> <li>Ensure that the parent list is version compatible.</li> <li>Set the current list to the parent list and go to step 1.</li> </ol> </li> <li>No: <ol> <li>Go to step 2.</li> </ol> </li> </ul> </li> <li>Copy the current list into a variable <code>$output</code>.</li> <li>Does the current list have a child: <ul> <li>Yes: <ol> <li>Apply the child's <code>changes</code> to <code>providers</code> in <code>$output</code>.</li> <li>Verify that <code>$output</code> is valid according to the JSON schema.</li> <li>Set the current list to the child.</li> <li>Go to step 3.</li> </ol> </li> <li>No: <ol> <li>Replace the current list's <code>providers</code> with <code>providers</code> from <code>$output</code>.</li> <li>The current list is now the resolved list; return it.</li> </ol> </li> </ul> </li> </ol> <p>List consumers SHOULD limit the number of extension lists to a reasonable number.</p> <h2 id="rationale">Rationale</h2> <p>This specification has two layers (provider, then chain id) instead of a flatter structure so that wallets can choose to query multiple independent providers for the same query and compare the results.</p> <p>Each provider may specify multiple endpoints to implement load balancing or redundancy.</p> <p>List version identifiers conform to SemVer to roughly communicate the kinds of changes that each new version brings. If a new version adds functionality (eg. a new chain id), then users can expect the minor version to be incremented. Similarly, if the major version is not incremented, list subscribers can assume dapps that work in the current version will continue to work in the next one.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Ultimately it is up to the end user to decide on what list to subscribe to. Most users will not change from the default list maintained by their wallet. Since wallets already have access to private keys, giving them additional control over RPC providers seems like a small increase in risk.</p> <p>While list maintainers may be incentivized (possibly financially) to include or exclude particular providers, actually doing so may jeopardize the legitimacy of their lists. This standard facilitates swapping lists, so if such manipulation is revealed, users are free to swap to a new list with little effort.</p> <p>If the list chosen by the user is published using EIP-1577, the list consumer has to have access to ENS in some way. This creates a paradox: how do you query Ethereum without an RPC provider? This paradox creates an attack vector: whatever method the list consumer uses to fetch the list can track the user, and even more seriously, <strong>can lie about the contents of the list</strong>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-06-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Wilkins Chunghttps://github.com/wwhchungwilkins@manifold.xyz Jalil Wahdatehaghhttps://github.com/jwahdatehagh Cryhttps://github.com/crydoteth Sillytunahttps://github.com/sillytuna Cyberpnkhttps://github.com/CyberpnkWin https://wg-eips.ritovision.com/5131/

Using ENS Text Records to facilitate safer and more convenient signing operations.

<h2 id="abstract">Abstract</h2> <p>This EIP links one or more signing wallets via Ethereum Name Service Specification (<a href="https://wg-eips.ritovision.com/137/">EIP-137</a>) to prove control and asset ownership of a main wallet.</p> <h2 id="motivation">Motivation</h2> <p>Proving ownership of an asset to a third party application in the Ethereum ecosystem is common. Users frequently sign payloads of data to authenticate themselves before gaining access to perform some operation. However, this method--akin to giving the third party root access to one's main wallet--is both insecure and inconvenient.</p> <p><em><strong>Examples:</strong></em></p> <ol> <li>In order for you to edit your profile on OpenSea, you must sign a message with your wallet.</li> <li>In order to access NFT gated content, you must sign a message with the wallet containing the NFT in order to prove ownership.</li> <li>In order to gain access to an event, you must sign a message with the wallet containing a required NFT in order to prove ownership.</li> <li>In order to claim an airdrop, you must interact with the smart contract with the qualifying wallet.</li> <li>In order to prove ownership of an NFT, you must sign a payload with the wallet that owns that NFT.</li> </ol> <p>In all the above examples, one interacts with the dApp or smart contract using the wallet itself, which may be</p> <ul> <li>inconvenient (if it is controlled via a hardware wallet or a multi-sig)</li> <li>insecure (since the above operations are read-only, but you are signing/interacting via a wallet that has write access)</li> </ul> <p>Instead, one should be able to approve multiple wallets to authenticate on behalf of a given wallet.</p> <h3 id="problems-with-existing-methods-and-solutions">Problems with existing methods and solutions</h3> <p>Unfortunately, we've seen many cases where users have accidentally signed a malicious payload. The result is almost always a significant loss of assets associated with the signing address.</p> <p>In addition to this, many users keep significant portions of their assets in 'cold storage'. With the increased security from 'cold storage' solutions, we usually see decreased accessibility because users naturally increase the barriers required to access these wallets.</p> <p>Some solutions propose dedicated registry smart contracts to create this link, or new protocols to be supported. This is problematic from an adoption standpoint, and there have not been any standards created for them.</p> <h3 id="proposal-use-the-ethereum-name-service-eip-137">Proposal: Use the Ethereum Name Service (EIP-137)</h3> <p>Rather than 're-invent the wheel', this proposal aims to use the widely adopted Ethereum Name Service in conjunction with the ENS Text Records feature (<a href="https://wg-eips.ritovision.com/634/">EIP-634</a>) in order to achieve a safer and more convenient way to sign and authenticate, and provide 'read only' access to a main wallet via one or more secondary wallets.</p> <p>From there, the benefits are twofold. This EIP gives users increased security via outsourcing potentially malicious signing operations to wallets that are more accessible (hot wallets), while being able to maintain the intended security assumptions of wallets that are not frequently used for signing operations.</p> <h4 id="improving-dapp-interaction-security">Improving dApp Interaction Security</h4> <p>Many dApps requires one to prove control of a wallet to gain access. At the moment, this means that you must interact with the dApp using the wallet itself. This is a security issue, as malicious dApps or phishing sites can lead to the assets of the wallet being compromised by having them sign malicious payloads.</p> <p>However, this risk would be mitigated if one were to use a secondary wallet for these interactions. Malicious interactions would be isolated to the assets held in the secondary wallet, which can be set up to contain little to nothing of value.</p> <h4 id="improving-multiple-device-access-security">Improving Multiple Device Access Security</h4> <p>In order for a non-hardware wallet to be used on multiple devices, you must import the seed phrase to each device. Each time a seed phrase is entered on a new device, the risk of the wallet being compromised increases as you are increasing the surface area of devices that have knowledge of the seed phrase.</p> <p>Instead, each device can have its own unique wallet that is an authorized secondary wallet of the main wallet. If a device specific wallet was ever compromised or lost, you could simply remove the authorization to authenticate.</p> <p>Further, wallet authentication can be chained so that a secondary wallet could itself authorize one or many tertiary wallets, which then have signing rights for both the secondary address as well as the root main address. This, can allow teams to each have their own signer while the main wallet can easily invalidate an entire tree, just by revoking rights from the root stem.</p> <h4 id="improving-convenience">Improving Convenience</h4> <p>Many invididuals use hardware wallets for maximum security. However, this is often inconvenient, since many do not want to carry their hardware wallet with them at all times.</p> <p>Instead, if you approve a non-hardware wallet for authentication activities (such as a mobile device), you would be able to use most dApps without the need to have your hardware wallet on hand.</p> <h2 id="specification">Specification</h2> <p>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> <p>Let:</p> <ul> <li><code>mainAddress</code> represent the wallet address we are trying to authenticate or prove asset ownership for.</li> <li><code>mainENS</code> represent the reverse lookup ENS string for <code>mainAddress</code>.</li> <li><code>authAddress</code> represent the address we want to use for signing in lieu of <code>mainAddress</code>.</li> <li><code>authENS</code> represent the reverse lookup ENS string for <code>authAddress</code>.</li> <li><code>authKey</code> represents a string in the format <code>[0-9A-Za-z]+</code>.</li> </ul> <p>Control of <code>mainAddress</code> and ownership of <code>mainAddress</code> assets by <code>authAddress</code> is proven if all the following conditions are met:</p> <ul> <li><code>mainAddress</code> has an ENS resolver record and a reverse record set to <code>mainENS</code>.</li> <li><code>authAddress</code> has an ENS resolver record and a reverse record set to <code>authENS</code>.</li> <li><code>authENS</code> has an ENS TEXT record <code>eip5131:vault</code> in the format <code>&lt;authKey&gt;:&lt;mainAddress&gt;</code>.</li> <li><code>mainENS</code> has an ENS TEXT record <code>eip5131:&lt;authKey&gt;</code>.</li> </ul> <h3 id="setting-up-one-or-many-authaddress-records-on-a-single-ens-domain">Setting up one or many <code>authAddress</code> records on a single ENS domain</h3> <p>The <code>mainAddress</code> MUST have an ENS resolver record and reverse record configured. In order to automatically discover the linked account, the <code>authAddress</code> SHOULD have an ENS resolver record and reverse record configured.</p> <ol> <li>Choose an unused <code>&lt;authKey&gt;</code>. This can be any string in the format <code>[0-0A-Za-z]+</code>.</li> <li>Set a TEXT record <code>eip5131:&lt;authKey&gt;</code> on <code>mainENS</code>, with the value set to the desired <code>authAddress</code>.</li> <li>Set a TEXT record <code>eip5131:vault</code> on <code>authENS</code>, with the value set to the <code>&lt;authKey&gt;:mainAddress</code>.</li> </ol> <p>Currently this EIP does not enforce an upper-bound on the number of <code>authAddress</code> entries you can include. Users can repeat this process with as many address as they like.</p> <h3 id="authenticating-mainaddress-via-authaddress">Authenticating <code>mainAddress</code> via <code>authAddress</code></h3> <p>Control of <code>mainAddress</code> and ownership of <code>mainAddress</code> assets is proven if any associated <code>authAddress</code> is the <code>msg.sender</code> or has signed the message.</p> <p>Practically, this would work by performing the following operations:</p> <ol> <li>Get the resolver for <code>authENS</code></li> <li>Get the <code>eip5131:vault</code> TEXT record of <code>authENS</code></li> <li>Parse <code>&lt;authKey&gt;:&lt;mainAddress&gt;</code> to determine the <code>authKey</code> and <code>mainAddress</code>.</li> <li>MUST get the reverse ENS record for <code>mainAddress</code> and verify that it matches <code>&lt;mainENS&gt;</code>. <ul> <li>Otherwise one could set up other ENS nodes (with auths) that point to <code>mainAddress</code> and authenticate via those.</li> </ul> </li> <li>Get the <code>eip5131:&lt;authKey&gt;</code> TEXT record of <code>mainENS</code> and ensure it matches <code>authAddress</code>.</li> </ol> <p>Note that this specification allows for both contract level and client/server side validation of signatures. It is not limited to smart contracts, which is why there is no proposed external interface definition.</p> <h3 id="revocation-of-authaddress">Revocation of <code>authAddress</code></h3> <p>To revoke permission of <code>authAddress</code>, delete the <code>eip5131:&lt;authKey&gt;</code> TEXT record of <code>mainENS</code> or update it to point to a new <code>authAddress</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="usage-of-eip-137">Usage of EIP-137</h3> <p>The proposed specification makes use of EIP-137 rather than introduce another registry paradigm. The reason for this is due to the existing wide adoption of EIP-137 and ENS.</p> <p>However, the drawback to EIP-137 is that any linked <code>authAddress</code> must contain some ETH in order to set the <code>authENS</code> reverse record as well as the <code>eip5131:vault</code> TEXT record. This can be solved by a separate reverse lookup registry that enables <code>mainAddress</code> to set the reverse record and TEXT record with a message signed by <code>authAddress</code>.</p> <p>With the advent of L2s and ENS Layer 2 functionalities, off chain verification of linked addresses is possible even with domains managed across different chains.</p> <h3 id="one-to-many-authentication-relationship">One-to-Many Authentication Relationship</h3> <p>This proposed specification allows for a one (<code>mainAddress</code>) to many (<code>authAddress</code>) authentication relationship. i.e. one <code>mainAddress</code> can authorize many <code>authAddress</code> to authenticate, but an <code>authAddress</code> can only authenticate itself or a single <code>mainAddress</code>.</p> <p>The reason for this design choice is to allow for simplicity of authentication via client and smart contract code. You can determine which <code>mainAddress</code> the <code>authAddress</code> is signing for without any additional user input.</p> <p>Further, you can design UX without any user interaction necessary to 'pick' the interacting address by display assets owned by <code>authAddress</code> and <code>mainAddress</code> and use the appropriate address dependent on the asset the user is attempting to authenticate with.</p> <h2 id="reference-implementation">Reference Implementation</h2> <h3 id="client-server-side">Client/Server Side</h3> <p>In typescript, the validation function, using ethers.js would be as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>export interface LinkedAddress {</span></span> <span class="giallo-l"><span> ens: string,</span></span> <span class="giallo-l"><span> address: string,</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>export async function getLinkedAddress(</span></span> <span class="giallo-l"><span> provider: ethers.providers.EnsProvider, address: string</span></span> <span class="giallo-l"><span>): Promise&lt;LinkedAddress | null&gt; {</span></span> <span class="giallo-l"><span> const addressENS = await provider.lookupAddress(address);</span></span> <span class="giallo-l"><span> if (!addressENS) return null;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> const vaultInfo = await (await provider.getResolver(addressENS))?.getText(&#39;eip5131:vault&#39;);</span></span> <span class="giallo-l"><span> if (!vaultInfo) return null;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> const vaultInfoArray = vaultInfo.split(&#39;:&#39;);</span></span> <span class="giallo-l"><span> if (vaultInfoArray.length !== 2) {</span></span> <span class="giallo-l"><span> throw new Error(&#39;EIP5131: Authkey and vault address not configured correctly.&#39;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> const [ authKey, vaultAddress ] = vaultInfoArray;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> const vaultENS = await provider.lookupAddress(vaultAddress);</span></span> <span class="giallo-l"><span> if (!vaultENS) {</span></span> <span class="giallo-l"><span> throw new Error(`EIP5131: No ENS domain with reverse record set for vault.`);</span></span> <span class="giallo-l"><span> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> const expectedSigningAddress = await (</span></span> <span class="giallo-l"><span> await provider.getResolver(vaultENS)</span></span> <span class="giallo-l"><span> )?.getText(`eip5131:${authKey}`);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if (expectedSigningAddress?.toLowerCase() !== address.toLowerCase()) {</span></span> <span class="giallo-l"><span> throw new Error(`EIP5131: Authentication mismatch.`);</span></span> <span class="giallo-l"><span> };</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> return {</span></span> <span class="giallo-l"><span> ens: vaultENS,</span></span> <span class="giallo-l"><span> address: vaultAddress</span></span> <span class="giallo-l"><span> };</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="contract-side">Contract side</h3> <h4 id="with-a-backend">With a backend</h4> <p>If your application operates a secure backend server, you could run the client/server code above, then use the result in conjunction with specs like <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> : <code>Standard Signature Validation Method for Contracts</code> for a cheap and secure way to validate that the message signer is indeed authenticated for the main address.</p> <h4 id="without-a-backend-javascript-only">Without a backend (JavaScript only)</h4> <p>Provided is a reference implementation for an internal function to verify that the message sender has an authentication link to the main address.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>pragma solidity ^0.8.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/// @author: manifold.xyz</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * ENS Registry Interface</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>interface ENS {</span></span> <span class="giallo-l"><span> function resolver(bytes32 node) external view returns (address);</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * ENS Resolver Interface</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>interface Resolver {</span></span> <span class="giallo-l"><span> function addr(bytes32 node) external view returns (address);</span></span> <span class="giallo-l"><span> function name(bytes32 node) external view returns (string memory);</span></span> <span class="giallo-l"><span> function text(bytes32 node, string calldata key) external view returns (string memory);</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * Validate a signing address is associtaed with a linked address</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>library LinkedAddress {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Validate that the message sender is an authentication address for mainAddress</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param ensRegistry Address of ENS registry</span></span> <span class="giallo-l"><span> * @param mainAddress The main address we want to authenticate for.</span></span> <span class="giallo-l"><span> * @param mainENSNodeHash The main ENS Node Hash</span></span> <span class="giallo-l"><span> * @param authKey The TEXT record of the authKey we are using for validation</span></span> <span class="giallo-l"><span> * @param authENSNodeHash The auth ENS Node Hash</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function validateSender(</span></span> <span class="giallo-l"><span> address ensRegistry,</span></span> <span class="giallo-l"><span> address mainAddress,</span></span> <span class="giallo-l"><span> bytes32 mainENSNodeHash,</span></span> <span class="giallo-l"><span> string calldata authKey,</span></span> <span class="giallo-l"><span> bytes32 authENSNodeHash</span></span> <span class="giallo-l"><span> ) internal view returns (bool) {</span></span> <span class="giallo-l"><span> return validate(ensRegistry, mainAddress, mainENSNodeHash, authKey, msg.sender, authENSNodeHash);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Validate that the authAddress is an authentication address for mainAddress</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @param ensRegistry Address of ENS registry</span></span> <span class="giallo-l"><span> * @param mainAddress The main address we want to authenticate for.</span></span> <span class="giallo-l"><span> * @param mainENSNodeHash The main ENS Node Hash</span></span> <span class="giallo-l"><span> * @param authAddress The address of the authentication wallet</span></span> <span class="giallo-l"><span> * @param authENSNodeHash The auth ENS Node Hash</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function validate(</span></span> <span class="giallo-l"><span> address ensRegistry,</span></span> <span class="giallo-l"><span> address mainAddress,</span></span> <span class="giallo-l"><span> bytes32 mainENSNodeHash,</span></span> <span class="giallo-l"><span> string calldata authKey,</span></span> <span class="giallo-l"><span> address authAddress,</span></span> <span class="giallo-l"><span> bytes32 authENSNodeHash</span></span> <span class="giallo-l"><span> ) internal view returns (bool) {</span></span> <span class="giallo-l"><span> _verifyMainENS(ensRegistry, mainAddress, mainENSNodeHash, authKey, authAddress);</span></span> <span class="giallo-l"><span> _verifyAuthENS(ensRegistry, mainAddress, authKey, authAddress, authENSNodeHash);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> return true;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // *********************</span></span> <span class="giallo-l"><span> // Helper Functions</span></span> <span class="giallo-l"><span> // *********************</span></span> <span class="giallo-l"><span> function _verifyMainENS(</span></span> <span class="giallo-l"><span> address ensRegistry,</span></span> <span class="giallo-l"><span> address mainAddress,</span></span> <span class="giallo-l"><span> bytes32 mainENSNodeHash,</span></span> <span class="giallo-l"><span> string calldata authKey,</span></span> <span class="giallo-l"><span> address authAddress</span></span> <span class="giallo-l"><span> ) private view {</span></span> <span class="giallo-l"><span> // Check if the ENS nodes resolve correctly to the provided addresses</span></span> <span class="giallo-l"><span> address mainResolver = ENS(ensRegistry).resolver(mainENSNodeHash);</span></span> <span class="giallo-l"><span> require(mainResolver != address(0), &quot;Main ENS not registered&quot;);</span></span> <span class="giallo-l"><span> require(mainAddress == Resolver(mainResolver).addr(mainENSNodeHash), &quot;Main address is wrong&quot;);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Verify the authKey TEXT record is set to authAddress by mainENS</span></span> <span class="giallo-l"><span> string memory authText = Resolver(mainResolver).text(mainENSNodeHash, string(abi.encodePacked(&quot;eip5131:&quot;, authKey)));</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> keccak256(bytes(authText)) == keccak256(bytes(_addressToString(authAddress))),</span></span> <span class="giallo-l"><span> &quot;Invalid auth address&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _verifyAuthENS(</span></span> <span class="giallo-l"><span> address ensRegistry,</span></span> <span class="giallo-l"><span> address mainAddress,</span></span> <span class="giallo-l"><span> string memory authKey,</span></span> <span class="giallo-l"><span> address authAddress,</span></span> <span class="giallo-l"><span> bytes32 authENSNodeHash</span></span> <span class="giallo-l"><span> ) private view {</span></span> <span class="giallo-l"><span> // Check if the ENS nodes resolve correctly to the provided addresses</span></span> <span class="giallo-l"><span> address authResolver = ENS(ensRegistry).resolver(authENSNodeHash);</span></span> <span class="giallo-l"><span> require(authResolver != address(0), &quot;Auth ENS not registered&quot;);</span></span> <span class="giallo-l"><span> require(authAddress == Resolver(authResolver).addr(authENSNodeHash), &quot;Auth address is wrong&quot;);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Verify the TEXT record is appropriately set by authENS</span></span> <span class="giallo-l"><span> string memory vaultText = Resolver(authResolver).text(authENSNodeHash, &quot;eip5131:vault&quot;);</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> keccak256(abi.encodePacked(authKey, &quot;:&quot;, _addressToString(mainAddress))) ==</span></span> <span class="giallo-l"><span> keccak256(bytes(vaultText)),</span></span> <span class="giallo-l"><span> &quot;Invalid auth text record&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> bytes16 private constant _HEX_SYMBOLS = &quot;0123456789abcdef&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function sha3HexAddress(address addr) private pure returns (bytes32 ret) {</span></span> <span class="giallo-l"><span> uint256 value = uint256(uint160(addr));</span></span> <span class="giallo-l"><span> bytes memory buffer = new bytes(40);</span></span> <span class="giallo-l"><span> for (uint256 i = 39; i &gt; 1; --i) {</span></span> <span class="giallo-l"><span> buffer[i] = _HEX_SYMBOLS[value &amp; 0xf];</span></span> <span class="giallo-l"><span> value &gt;&gt;= 4;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> return keccak256(buffer);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _addressToString(address addr) private pure returns (string memory ptr) {</span></span> <span class="giallo-l"><span> // solhint-disable-next-line no-inline-assembly</span></span> <span class="giallo-l"><span> assembly {</span></span> <span class="giallo-l"><span> ptr := mload(0x40)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Adjust mem ptr and keep 32 byte aligned</span></span> <span class="giallo-l"><span> // 32 bytes to store string length; address is 42 bytes long</span></span> <span class="giallo-l"><span> mstore(0x40, add(ptr, 96))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Store (string length, &#39;0&#39;, &#39;x&#39;) (42, 48, 120)</span></span> <span class="giallo-l"><span> // Single write by offsetting across 32 byte boundary</span></span> <span class="giallo-l"><span> ptr := add(ptr, 2)</span></span> <span class="giallo-l"><span> mstore(ptr, 0x2a3078)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Write string backwards</span></span> <span class="giallo-l"><span> for {</span></span> <span class="giallo-l"><span> // end is at &#39;x&#39;, ptr is at lsb char</span></span> <span class="giallo-l"><span> let end := add(ptr, 31)</span></span> <span class="giallo-l"><span> ptr := add(ptr, 71)</span></span> <span class="giallo-l"><span> } gt(ptr, end) {</span></span> <span class="giallo-l"><span> ptr := sub(ptr, 1)</span></span> <span class="giallo-l"><span> addr := shr(4, addr)</span></span> <span class="giallo-l"><span> } {</span></span> <span class="giallo-l"><span> let v := and(addr, 0xf)</span></span> <span class="giallo-l"><span> // if &gt; 9, use ascii &#39;a-f&#39; (no conditional required)</span></span> <span class="giallo-l"><span> v := add(v, mul(gt(v, 9), 39))</span></span> <span class="giallo-l"><span> // Add ascii for &#39;0&#39;</span></span> <span class="giallo-l"><span> v := add(v, 48)</span></span> <span class="giallo-l"><span> mstore8(ptr, v)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // return ptr to point to length (32 + 2 for &#39;0x&#39; - 1)</span></span> <span class="giallo-l"><span> ptr := sub(ptr, 33)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> return string(ptr);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>The core purpose of this EIP is to enhance security and promote a safer way to authenticate wallet control and asset ownership when the main wallet is not needed and assets held by the main wallet do not need to be moved. Consider it a way to do 'read only' authentication.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-05-13T00:00:00+00:00 2026-02-11T14:48:26+00:00 Luc van Kampenhttps://github.com/lucemans Jakob Helgessonhttps://github.com/svemat01 Joshua Hendrixhttps://github.com/thejoshuahendrix https://wg-eips.ritovision.com/5094/

A way of representing various network configurations as URLs.

<h2 id="abstract">Abstract</h2> <p>This standard includes all needed information for adding a network to a wallet via URL, by including parameters such as <code>chainId</code>, <code>rpc_url</code>, <code>chain_name</code> and others, such that the network configuration is provided through the URL itself.</p> <h2 id="motivation">Motivation</h2> <p>As observed with the use of <a href="https://wg-eips.ritovision.com/681/">EIP-681</a> and its implementation in current mobile wallets, transactions can be made, approved, viewed, and used. However, if the wallet is instructed to perform a transaction on a chain they have not yet been configured before, the operation tends to fail.</p> <p>This is understandable, as the <code>chain_id</code> provided makes up only one part of what is required to connect to a network. This EIP aims to introduce a new type of URL for usage with deep-linking, QR, and more, to allow users to seamlessly add new networks to their (for ex. mobile) wallet to then be able to more easily partake in <code>pay-</code>, <code>tx-</code>, or other Ethereum URL interactions.</p> <p>As an extension to <a href="https://wg-eips.ritovision.com/831/">EIP-831</a> and neighboring <a href="https://wg-eips.ritovision.com/681/">EIP-681</a> and <a href="https://wg-eips.ritovision.com/2400/">EIP-2400</a>, this document aims to standardize the addition of new networks and switching thereof through the means of URLs. User convenience in this case is primary.</p> <p>Introduction of this EIP is meant to bridge to a safer RPC listing system to be introduced in the near future.</p> <h2 id="specification">Specification</h2> <h3 id="syntax">Syntax</h3> <p>Network Switching URLs contain "ethereum" in their schema (protocol) part and are constructed as follows:</p> <pre class="giallo z-code"><code data-lang="ABNF"><span class="giallo-l"><span>network_add =</span><span class="z-variable z-other"> erc831</span><span class="z-variable z-other">_</span><span class="z-variable z-other">part</span><span class="z-string"> &quot;</span><span class="z-string">add</span><span class="z-string">&quot;</span><span class="z-string"> &quot;</span><span class="z-string">@</span><span class="z-string">&quot;</span><span class="z-variable z-other"> chain</span><span class="z-variable z-other">_</span><span class="z-variable z-other">id</span><span class="z-keyword"> [</span><span class="z-string"> &quot;</span><span class="z-string">/</span><span class="z-string">&quot;</span><span class="z-keyword"> ]</span><span class="z-string"> &quot;</span><span class="z-string">?</span><span class="z-string">&quot;</span><span class="z-variable z-other"> parameters</span></span> <span class="giallo-l"><span>erc831_part =</span><span class="z-string"> &quot;</span><span class="z-string">ethereum:network-</span><span class="z-string">&quot;</span></span> <span class="giallo-l"><span>chain_id =</span><span> 1*</span><span>DIGIT</span></span> <span class="giallo-l"><span>parameters =</span><span class="z-variable z-other"> parameter</span><span> *</span><span class="z-keyword">(</span><span class="z-string"> &quot;</span><span class="z-string">&amp;</span><span class="z-string">&quot;</span><span class="z-variable z-other"> parameter</span><span class="z-keyword"> )</span></span> <span class="giallo-l"><span>parameter =</span><span class="z-variable z-other"> key</span><span class="z-string"> &quot;</span><span class="z-string">=</span><span class="z-string">&quot;</span><span class="z-variable z-other"> value</span></span> <span class="giallo-l"><span>key =</span><span class="z-variable z-other"> required</span><span class="z-variable z-other">_</span><span class="z-variable z-other">keys</span><span class="z-keyword"> /</span><span class="z-variable z-other"> optional</span><span class="z-variable z-other">_</span><span class="z-variable z-other">keys</span></span> <span class="giallo-l"><span>required_keys =</span><span class="z-string"> &quot;</span><span class="z-string">rpc_url</span><span class="z-string">&quot;</span><span class="z-keyword"> /</span><span class="z-string"> &quot;</span><span class="z-string">chain_name</span><span class="z-string">&quot;</span></span> <span class="giallo-l"><span>optional_keys =</span><span class="z-string"> &quot;</span><span class="z-string">name</span><span class="z-string">&quot;</span><span class="z-keyword"> /</span><span class="z-string"> &quot;</span><span class="z-string">symbol</span><span class="z-string">&quot;</span><span class="z-keyword"> /</span><span class="z-string"> &quot;</span><span class="z-string">decimals</span><span class="z-string">&quot;</span><span class="z-keyword"> /</span><span class="z-string"> &quot;</span><span class="z-string">explorer_url</span><span class="z-string">&quot;</span><span class="z-keyword"> /</span><span class="z-string"> &quot;</span><span class="z-string">icon_url</span><span class="z-string">&quot;</span></span> <span class="giallo-l"><span>value =</span><span class="z-variable z-other"> STRING</span><span class="z-keyword"> /</span><span class="z-variable z-other"> number</span></span> <span class="giallo-l"><span>number =</span><span> 1*</span><span>DIGIT</span></span></code></pre> <p><code>STRING</code> is a URL-encoded Unicode string of arbitrary length, where delimiters and the percentage symbol (<code>%</code>) are mandatorily hex-encoded with a <code>%</code> prefix.</p> <p>If the <em>key</em> in the parameter is <code>decimals</code> the <em>value</em> MUST be a <code>number</code>.</p> <h3 id="semantics">Semantics</h3> <p><code>chain_id</code> is mandatory and denotes the decimal chain ID, such that we have the identifier of the network we would like to add.</p> <p><code>rpc_url</code> is represented as an array of RPC URLs. A minimum of 1 <code>rpc_url</code> MUST be present, in the format of <code>rpc_url=https%3A%2F%2Fpolygon-rpc.com</code>, or when multiple present <code>rpc_url=https%3A%2F%2Fpolygon-rpc.com&amp;rpc_url=https%3A%2F%2Frpc-mainnet.matic.network</code>.</p> <p><code>chain_name</code> is required to specify the name of the network to be added.</p> <p><code>name</code> and <code>symbol</code> if provided, SHOULD be a human-readable string representing the native token.</p> <p><code>decimals</code> if provided, MUST be a non-negative integer representing the decimal precision of the native token.</p> <p><code>explorer_url</code> if provided, MUST specify one or more URLs pointing to block explorer web sites for the chain.</p> <p><code>icon_url</code> if provided, MUST specify one or more URLs pointing to reasonably sized images that can be used to visually identify the chain.</p> <p>An example of adding a network with RPC endpoints <code>https://rpc-polygon.com</code> and <code>https://rpc-mainnet.matic.network</code>, the name <code>Polygon Mainnet</code>, token <code>Matic</code>, symbol <code>MATIC</code>, decimals <code>18</code>, explorer at <code>https://polygonscan.com/</code>, and Chain ID <code>137</code> would look as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ethereum:network-add@137/?chain_name=Polygon%20Mainnet&amp;rpc_url=https%3A%2F%2Frpc-polygon.com&amp;rpc_url=https%3A%2F%2Frpc-mainnet.matic.network&amp;name=Matic&amp;symbol=MATIC&amp;decimals=18&amp;explorer_url=https%3A%2F%2Fpolygonscan.com</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>In furtherance of the Ethereum URL saga, network configuration is a needed addition to the possibility of Ethereum URLs. This would improve functionality for URLs, and offer non-mainnet users a way to connect without needing to configure their wallet by hand.</p> <p>The URL follows <a href="https://wg-eips.ritovision.com/831/">EIP-831</a> with the <code>PREFIX</code> being <code>network</code> and the <code>PAYLOAD</code> being a composite of <code>add</code> and <a href="https://wg-eips.ritovision.com/681/">EIP-681</a>-like <code>chain_id</code> and parameters.</p> <p>The choice for <code>PREFIX</code> being <code>network</code> is to allow further expansion and allow variants following the pattern <code>network-x</code>.</p> <p>An example URL for adding the Optimism Network</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ethereum:network-add@10/?chain_name=Optimistic%20Ethereum</span></span> <span class="giallo-l"><span>&amp;rpc_url=https%3A%2F%2Fmainnet.optimism.io&amp;name=Ethereum&amp;symbol=ETH&amp;decimals=18&amp;explorer_url=https%3A%2F%2Foptimistic.etherscan.io</span></span></code></pre> <p>The specification allows for a multitude of <code>rpc_url</code> and <code>explorer_url</code> to be specified. This is done such to overlap with parsing of the <code>TYPE</code> mentioned in <a href="https://wg-eips.ritovision.com/681/">EIP-681</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>URLs can be malformed to deceive users. Users SHOULD confirm source of URL before using any links. As well as checking source and transaction details before confirming any transactions. Applications SHOULD display network config, prior to network addition, such that users can confirm the validity of the network configuration being added.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-05-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Aubayblockchain-team@aubay.com BOCA Jeabbyhttps://github.com/bjeabby1507 EL MERSHATI Laithhttps://github.com/lth-elm KEMP Eliahttps://github.com/eliakemp https://wg-eips.ritovision.com/6353/

Extension of EIP-20 token that can be partially donated to a charity project

<h2 id="abstract">Abstract</h2> <p>An extension to <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> that can automatically send an additional percentage of each transfer to a third party, and that provides an interface for retrieving this information. This can allow token owners to make donations to a charity with every transfer. This can also be used to allow automated savings programs.</p> <h2 id="motivation">Motivation</h2> <p>There are charity organizations with addresses on-chain, and there are token holders who want to make automated donations. Having a standardized way of collecting and managing these donations helps users and user interface developers. Users can make an impact with their token and can contribute to achieving sustainable blockchain development. Projects can easily retrieve charity donations addresses and rate for a given <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> token, token holders can compare minimum rate donation offers allowed by token contract owners. This standard provides functionality that allows token holders to donate easily.</p> <h2 id="specification">Specification</h2> <p>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> <p>Owner of the contract <strong>MAY</strong>, after review, register charity address in <code>whitelistedRate</code> and set globally a default rate of donation. To register the address, the rate <strong>MUST</strong> not be null.</p> <p>Token holders <strong>MAY</strong> choose and specify a default charity address from <code>_defaultAddress</code>, this address <strong>SHOULD</strong> be different from the null address for the donation to be activated.</p> <p>The donation is a percentage-based rate model, but the calculation can be done differently. Applications and individuals can implement this standard by retrieving information with <code>charityInfo()</code> , which specifies an assigned rate for a given address.</p> <p>This standard provides functionality that allows token holders to donate easily. The donation when activated is done directly in the overridden <code>transfer</code>, <code>transferFrom</code>, and <code>approve</code> functions.</p> <p>When <code>transfer</code>, <code>transferFrom</code> are called the sender's balance is reduced by the initial amount and a donation amount is deduced. The initial transferred amount is transferred to the recipient's balance and an additional donation amount is transferred to a third party (charity). The two transfer are done at the same time and emit two <code>Transfer</code> events. Also, if the account has an insufficient balance to cover the transfer and the donation the whole transfer would revert.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.4</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Required interface of an ERC20 Charity compliant contract.</span></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC20charity</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The EIP-165 identifier for this interface is 0x557512b6</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `toAdd` charity address is added to `whitelistedRate`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AddedToWhitelist</span><span> (</span><span class="z-support">address</span><span class="z-variable"> toAdd</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `toRemove` charity address is deleted from `whitelistedRate`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RemovedFromWhitelist</span><span> (</span><span class="z-support">address</span><span class="z-variable"> toRemove</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `_defaultAddress` charity address is modified and set to `whitelistedAddr`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DonnationAddressChanged</span><span> (</span><span class="z-support">address</span><span class="z-variable"> whitelistedAddr</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `_defaultAddress` charity address is modified and set to `whitelistedAddr` </span></span> <span class="giallo-l"><span class="z-comment"> * and _donation is set to `rate`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DonnationAddressAndRateChanged</span><span> (</span><span class="z-support">address</span><span class="z-variable"> whitelistedAddr</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> rate</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `whitelistedRate` for `whitelistedAddr` is modified and set to `rate`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ModifiedCharityRate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> whitelistedAddr</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> rate</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Called with the charity address to determine if the contract whitelisted the address</span></span> <span class="giallo-l"><span class="z-comment"> *and if it is the rate assigned.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> addr</span><span class="z-comment"> - the Charity address queried for donnation information.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> whitelisted</span><span class="z-comment"> - true if the contract whitelisted the address to receive donnation</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> defaultRate</span><span class="z-comment"> - the rate defined by the contract owner by default , the minimum rate allowed different from 0</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> charityInfo</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> addr</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> whitelisted</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> defaultRate</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Add address to whitelist and set rate to the default rate.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `toAdd` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> toAdd</span><span class="z-comment"> The address to whitelist.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addToWhitelist</span><span>(</span><span class="z-support">address</span><span class="z-variable"> toAdd</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Remove the address from the whitelist and set rate to the default rate.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `toRemove` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> toRemove</span><span class="z-comment"> The address to remove from whitelist.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deleteFromWhitelist</span><span>(</span><span class="z-support">address</span><span class="z-variable"> toRemove</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get all registered charity addresses.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAllWhitelistedAddresses</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span> ;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Display for a user the rate of the default charity address that will receive donation.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRate</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Set personlised rate for charity address in {whitelistedRate}.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `whitelistedAddr` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * - `rate` cannot be inferior to the default rate.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> whitelistedAddr</span><span class="z-comment"> The address to set as default.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> rate</span><span class="z-comment"> The personalised rate for donation.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setSpecificRate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> whitelistedAddr</span><span> ,</span><span class="z-support"> uint256</span><span class="z-variable"> rate</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Set for a user a default charity address that will receive donation. </span></span> <span class="giallo-l"><span class="z-comment"> * The default rate specified in {whitelistedRate} will be applied.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `whitelistedAddr` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> whitelistedAddr</span><span class="z-comment"> The address to set as default.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setSpecificDefaultAddress</span><span>(</span><span class="z-support">address</span><span class="z-variable"> whitelistedAddr</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Set for a user a default charity address that will receive donation. </span></span> <span class="giallo-l"><span class="z-comment"> * The rate is specified by the user.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `whitelistedAddr` cannot be the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> * - `rate` cannot be less than to the default rate </span></span> <span class="giallo-l"><span class="z-comment"> * or to the rate specified by the owner of this contract in {whitelistedRate}.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> whitelistedAddr</span><span class="z-comment"> The address to set as default.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> rate</span><span class="z-comment"> The personalised rate for donation.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setSpecificDefaultAddressAndRate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> whitelistedAddr</span><span> ,</span><span class="z-support"> uint256</span><span class="z-variable"> rate</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Display for a user the default charity address that will receive donation. </span></span> <span class="giallo-l"><span class="z-comment"> * The default rate specified in {whitelistedRate} will be applied.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> specificDefaultAddress</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> defaultAddress</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-storage z-type">@notice</span><span class="z-comment"> Delete The Default Address and so deactivate donnations .</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deleteDefaultAddress</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h3 id="functions">Functions</h3> <h4 id="addtowhitelist"><strong>addToWhitelist</strong></h4> <p>Add address to whitelist and set the rate to the default rate.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>toAdd</td><td>The address to the whitelist.</td></tr> </tbody></table> <h4 id="deletefromwhitelist"><strong>deleteFromWhitelist</strong></h4> <p>Remove the address from the whitelist and set rate to the default rate.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>toRemove</td><td>The address to remove from whitelist.</td></tr> </tbody></table> <h4 id="getallwhitelistedaddresses"><strong>getAllWhitelistedAddresses</strong></h4> <p>Get all registered charity addresses.</p> <h4 id="getrate"><strong>getRate</strong></h4> <p>Display for a user the rate of the default charity address that will receive donation.</p> <h4 id="setspecificrate"><strong>setSpecificRate</strong></h4> <p>Set personalized rate for charity address in {whitelistedRate}.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>whitelistedAddr</td><td>The address to set as default.</td></tr> <tr><td>rate</td><td>The personalised rate for donation.</td></tr> </tbody></table> <h4 id="setspecificdefaultaddress"><strong>setSpecificDefaultAddress</strong></h4> <p>Set for a user a default charity address that will receive donations. The default rate specified in {whitelistedRate} will be applied.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>whitelistedAddr</td><td>The address to set as default.</td></tr> </tbody></table> <h4 id="setspecificdefaultaddressandrate"><strong>setSpecificDefaultAddressAndRate</strong></h4> <p>Set for a user a default charity address that will receive donations. The rate is specified by the user.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>whitelistedAddr</td><td>The address to set as default.</td></tr> <tr><td>rate</td><td>The personalized rate for donation.</td></tr> </tbody></table> <h4 id="specificdefaultaddress"><strong>specificDefaultAddress</strong></h4> <p>Display for a user the default charity address that will receive donations. The default rate specified in {whitelistedRate} will be applied.</p> <h4 id="deletedefaultaddress"><strong>deleteDefaultAddress</strong></h4> <p>Delete The Default Address and so deactivate donations.</p> <h4 id="charityinfo"><strong>charityInfo</strong></h4> <p>Called with the charity address to determine if the contract whitelisted the address and if it is, the rate assigned.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>addr</td><td>The Charity address queried for donnation information.</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>This EIP chooses to whitelist charity addresses by using an array and keeping track of the "active" status with a mapping <code>whitelistedRate</code> to allow multiple choice of recipient and for transparence. The donation address can also be a single address chosen by the owner of the contract and modified by period.</p> <p>If the sender balance is insuficent i.e total amount of token (initial transfer + donation) is insuficent the transfer would revert. Donation are done in the <code>transfer</code> function to simplify the usage and to not add an additional function, but the implementation could be donne differently, and for example allow a transfer to go through without the donation amount when donation is activated. The token implementer can also choose to store the donation in the contract or in another one and add a withdrawal or claimable function, so the charity can claim the allocated amount of token themselves, the additional transfer will be triggered by the charity and not the token holder.</p> <p>Also, donations amount are calculated here as a percentage of the amount of token transferred to allow different case scenario, but the token implementer can decide to opt for another approach instead like rounding up the transaction value.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This implementation is an extension of the functionality of <a href="https://wg-eips.ritovision.com/20/">EIP-20</a>, it introduces new functionality retaining the core interfaces and functionality of the <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> standard. There is a small backwards compatibility issue, indeed if an account has insufficient balance, it's possible for the transfer to fail.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests can be found in <a href="https://wg-eips.ritovision.com/6353/./assets/test/charity.js"><code>charity.js</code></a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation of the standard can be found under <a href="https://wg-eips.ritovision.com/6353/./assets/contracts/ERC20Charity.sol"><code>contracts/</code></a> folder.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no additional security considerations compared to EIP-20.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-05-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv Nick Johnsonhttps://github.com/Arachnid Konrad Feldmeierkonrad@brainbot.com https://wg-eips.ritovision.com/5081/

This EIP adds a new transaction type of that includes expiration with a blocknum

<h2 id="abstract">Abstract</h2> <p>This EIP adds a new transaction type of that includes expiration with a blocknum.</p> <h2 id="motivation">Motivation</h2> <p>When a user sends a transaction <code>tx0</code> with a low gas price, sometimes it might not be high enough to be executed. A common resolution is for the user to submit the transaction again with the same nonce and higher gas price.</p> <p>That previous <code>tx0</code> can theoretically be included in any time in the future unless a <code>tx</code> with the exact same nonce is already executed.</p> <p>When network is congested, gas price are high, for critical transactions user might try gas price that is much higher than an average day. This cause the <code>tx0</code> choice might be very easy to executed in the average day.</p> <p>If user already uses a <code>tx1</code> with different nonce or from another account to execute the intended transaction, there is currently no clean way to cancel it, except for signing a new <code>tx0'</code> that shares the same nonce but with higher gas fee hoping that it will execute to <em>preempt</em>- than <code>tx0</code>.</p> <p>Given <code>tx0</code> was already high gas price, the current way of <em>preempting</em> <code>tx0</code> could be both unreliable and very costly.</p> <p>TODO(@xinbenlv): to include in the motivation:</p> <ul> <li> <p>Expiring transactions are transactions that have low time preference, but can easily become invalid in the future. For example, you may want to do a swap on an AMM but you don't want to pay a very high fee for it so you set the max fee to a low number. However, your transaction will almost certainly fail if it takes longer than a couple minutes to be mined. In this scenario, you would rather fail cheaply if your transaction doesn't get included quickly.</p> </li> <li> <p>Similarly, there are situations where there is a limited window of availability of some asset and if your transaction doesn't mine within that period you know with certainty that it will fail. In these cases, it would be nice to be able to express that to the system and not waste unnecessary resources just to have the transaction fail.</p> </li> </ul> <h2 id="specification">Specification</h2> <p>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> <h3 id="parameters">Parameters</h3> <ul> <li><code>FORK_BLKNUM</code> = <code>TBD</code></li> <li><code>CHAIN_ID</code> = <code>TBD</code></li> <li><code>TX_TYPE</code> = TBD, &gt; 0x02 (<a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>)</li> </ul> <p>As of <code>FORK_BLOCK_NUMBER</code>, a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction is introduced with <code>TransactionType</code> = <code>TX_TYPE(TBD)</code>.</p> <p>The intrinsic cost of the new transaction is inherited from <a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a>, specifically <code>21000 + 16 * non-zero calldata bytes + 4 * zero calldata bytes + 1900 * access list storage key count + 2400 * access list address count</code>.</p> <p>The <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>TransactionPayload</code> for this transaction is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>rlp([chain_id, expire_by, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, destination, amount, data, access_list, signature_y_parity, signature_r, signature_s])</span></span></code></pre> <p>The definition of <code>expire_by</code> is a block number the latest possible block to execute this transaction. Any block with a block number <code>block_num &gt; expire_by</code> MUST NOT execute this transaction.</p> <p>The definitions of all other fields share the same meaning with <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a></p> <p>The <code>signature_y_parity, signature_r, signature_s</code> elements of this transaction represent a secp256k1 signature over <code>keccak256(0x02 || rlp([chain_id, expire_by, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, destination, amount, data, access_list]))</code>.</p> <p>The <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>ReceiptPayload</code> for this transaction is <code>rlp([status, cumulative_transaction_gas_used, logs_bloom, logs])</code>.</p> <h2 id="rationale">Rationale</h2> <p>TODO</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>TODO</p> <h2 id="security-considerations">Security Considerations</h2> <ol> <li> <p>If <code>current_block_num</code> is available, client MUST drop and stop propagating/broadcasting any transactions that has a <code>transaction_type == TX_TYPE</code> AND <code>current_block_num &gt; expire_by</code></p> </li> <li> <p>It is suggested but not required that a <code>currentBlockNum</code> SHOULD be made available to client. Any client doing PoW calculation on blocks expire tx or propagating such are essentially penalized for wasting of work, mitigating possible denial of service attack.</p> </li> <li> <p>It is suggested but not required that client SHOULD introduce a <code>gossip_ttl</code> in unit of block_num as a safe net so that it only propagate a tx if <code>current_block_num + gossip_ttl &lt;= expire_by</code>. Backward compatibility: for nodes that doesn't have <code>current_block_num</code> or <code>gossip_ttl</code> available, they should be presumed to be <code>0</code>.</p> </li> <li> <p>It is suggested by not required that any propagating client SHOULD properly deduct the <code>gossip_ttl</code> based on the network environment it sees fit.</p> </li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-05-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Julian Traversahttps://github.com/JTraversa Robert Robbinshttps://github.com/robrobbins Alberto Cuesta Cañadahttps://github.com/alcueca https://wg-eips.ritovision.com/5095/

Principal tokens (zero-coupon tokens) are redeemable for a single underlying EIP-20 token at a future timestamp.

<h2 id="abstract">Abstract</h2> <p>Principal tokens represent ownership of an underlying <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> token at a future timestamp.</p> <p>This specification is an extension on the <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> token that provides basic functionality for depositing and withdrawing tokens and reading balances and the <a href="https://wg-eips.ritovision.com/2612/">EIP-2612</a> specification that provides <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> signature based approvals.</p> <h2 id="motivation">Motivation</h2> <p>Principal tokens lack standardization which has led to a difficult to navigate development space and diverse implementation schemes.</p> <p>The primary examples include yield tokenization platforms which strip future yield leaving a principal token behind, as well as fixed-rate money-markets which utilize principal tokens as a medium to lend/borrow.</p> <p>This inconsistency in implementation makes integration difficult at the application layer as well as wallet layer which are key catalysts for the space's growth. Developers are currently expected to implement individual adapters for each principal token, as well as adapters for their pool contracts, and many times adapters for their custodial contracts as well, wasting significant developer resources.</p> <h2 id="specification">Specification</h2> <p>All Principal Tokens (PTs) MUST implement <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> to represent ownership of future underlying redemption. If a PT is to be non-transferrable, it MAY revert on calls to <code>transfer</code> or <code>transferFrom</code>. The <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> operations <code>balanceOf</code>, <code>transfer</code>, <code>totalSupply</code>, etc. operate on the Principal Token balance.</p> <p>All Principal Tokens MUST implement <a href="https://wg-eips.ritovision.com/20/">EIP-20</a>'s optional metadata extensions. The <code>name</code> and <code>symbol</code> functions SHOULD reflect the underlying token's <code>name</code> and <code>symbol</code> in some way, as well as the origination protocol, and in the case of yield tokenization protocols, the origination money-market.</p> <p>All Principal Tokens MAY implement <a href="https://wg-eips.ritovision.com/2612/">EIP-2612</a> to improve the UX of approving PTs on various integrations.</p> <h3 id="definitions">Definitions:</h3> <ul> <li>underlying: The token that Principal Tokens are redeemable for at maturity. Has units defined by the corresponding <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> contract.</li> <li>maturity: The timestamp (unix) at which a Principal Token matures. Principal Tokens become redeemable for underlying at or after this timestamp.</li> <li>fee: An amount of underlying or Principal Token charged to the user by the Principal Token. Fees can exist on redemption or post-maturity yield.</li> <li>slippage: Any difference between advertised redemption value and economic realities of PT redemption, which is not accounted by fees.</li> </ul> <h3 id="methods">Methods</h3> <h4 id="underlying"><code>underlying</code></h4> <p>The address of the underlying token used by the Principal Token for accounting, and redeeming.</p> <p>MUST be an EIP-20 token contract.</p> <p>MUST <em>NOT</em> revert.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> u</span><span class="z-string">nderlying</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span><span> [</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> u</span><span class="z-string">nderlyingAddress</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span></code></pre><h4 id="maturity"><code>maturity</code></h4> <p>The unix timestamp (uint256) at or after which Principal Tokens can be redeemed for their underlying deposit.</p> <p>MUST <em>NOT</em> revert.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">aturity</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span><span> [</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> t</span><span class="z-string">imestamp</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="converttounderlying"><code>convertToUnderlying</code></h4> <p>The amount of underlying that would be exchanged for the amount of PTs provided, in an ideal scenario where all the conditions are met.</p> <p>Before maturity, the amount of underlying returned is as if the PTs would be at maturity.</p> <p>MUST NOT be inclusive of any fees that are charged against redemptions.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT reflect slippage or other on-chain conditions, when performing the actual redemption.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p> <p>MUST round down towards 0.</p> <p>This calculation MAY NOT reflect the "per-user" price-per-principal-token, and instead should reflect the "average-user's" price-per-principal-token, meaning what the average user should expect to see when exchanging to and from.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> c</span><span class="z-string">onvertToUnderlying</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">rincipalAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> u</span><span class="z-string">nderlyingAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="converttoprincipal"><code>convertToPrincipal</code></h4> <p>The amount of principal tokens that the principal token contract would request for redemption in order to provide the amount of underlying specified, in an ideal scenario where all the conditions are met.</p> <p>MUST NOT be inclusive of any fees.</p> <p>MUST NOT show any variations depending on the caller.</p> <p>MUST NOT reflect slippage or other on-chain conditions, when performing the actual exchange.</p> <p>MUST NOT revert unless due to integer overflow caused by an unreasonably large input.</p> <p>MUST round down towards 0.</p> <p>This calculation MAY NOT reflect the "per-user" price-per-principal-token, and instead should reflect the "average-user's" price-per-principal-token, meaning what the average user should expect to see when redeeming.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> c</span><span class="z-string">onvertToPrincipal</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> u</span><span class="z-string">nderlyingAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">rincipalAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="maxredeem"><code>maxRedeem</code></h4> <p>Maximum amount of principal tokens that can be redeemed from the <code>holder</code> balance, through a <code>redeem</code> call.</p> <p>MUST return the maximum amount of principal tokens that could be transferred from <code>holder</code> through <code>redeem</code> and not cause a revert, which MUST NOT be higher than the actual maximum that would be accepted (it should underestimate if necessary).</p> <p>MUST factor in both global and user-specific limits, like if redemption is entirely disabled (even temporarily) it MUST return 0.</p> <p>MUST NOT revert.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">axRedeem</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> h</span><span class="z-string">older</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">axPrincipalAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="previewredeem"><code>previewRedeem</code></h4> <p>Allows an on-chain or off-chain user to simulate the effects of their redeemption at the current block, given current on-chain conditions.</p> <p>MUST return as close to and no more than the exact amount of underliyng that would be obtained in a <code>redeem</code> call in the same transaction. I.e. <code>redeem</code> should return the same or more <code>underlyingAmount</code> as <code>previewRedeem</code> if called in the same transaction.</p> <p>MUST NOT account for redemption limits like those returned from maxRedeem and should always act as though the redemption would be accepted, regardless if the user has enough principal tokens, etc.</p> <p>MUST be inclusive of redemption fees. Integrators should be aware of the existence of redemption fees.</p> <p>MUST NOT revert due to principal token contract specific user/global limits. MAY revert due to other conditions that would also cause <code>redeem</code> to revert.</p> <p>Note that any unfavorable discrepancy between <code>convertToUnderlying</code> and <code>previewRedeem</code> SHOULD be considered slippage in price-per-principal-token or some other type of condition.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">reviewRedeem</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">rincipalAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> u</span><span class="z-string">nderlyingAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="redeem"><code>redeem</code></h4> <p>At or after maturity, burns exactly <code>principalAmount</code> of Principal Tokens from <code>from</code> and sends <code>underlyingAmount</code> of underlying tokens to <code>to</code>.</p> <p>Interfaces and other contracts MUST NOT expect fund custody to be present. While custodial redemption of Principal Tokens through the Principal Token contract is extremely useful for integrators, some protocols may find giving the Principal Token itself custody breaks their backwards compatibility.</p> <p>MUST emit the <code>Redeem</code> event.</p> <p>MUST support a redeem flow where the Principal Tokens are burned from <code>holder</code> directly where <code>holder</code> is <code>msg.sender</code> or <code>msg.sender</code> has EIP-20 approval over the principal tokens of <code>holder</code>. MAY support an additional flow in which the principal tokens are transferred to the Principal Token contract before the <code>redeem</code> execution, and are accounted for during <code>redeem</code>.</p> <p>MUST revert if all of <code>principalAmount</code> cannot be redeemed (due to withdrawal limit being reached, slippage, the holder not having enough Principal Tokens, etc).</p> <p>Note that some implementations will require pre-requesting to the Principal Token before a withdrawal may be performed. Those methods should be performed separately.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">edeem</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">rincipalAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> t</span><span class="z-string">o</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> f</span><span class="z-string">rom</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> u</span><span class="z-string">nderlyingAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="maxwithdraw"><code>maxWithdraw</code></h4> <p>Maximum amount of the underlying asset that can be redeemed from the <code>holder</code> principal token balance, through a <code>withdraw</code> call.</p> <p>MUST return the maximum amount of underlying tokens that could be redeemed from <code>holder</code> through <code>withdraw</code> and not cause a revert, which MUST NOT be higher than the actual maximum that would be accepted (it should underestimate if necessary).</p> <p>MUST factor in both global and user-specific limits, like if withdrawals are entirely disabled (even temporarily) it MUST return 0.</p> <p>MUST NOT revert.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">axWithdraw</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> h</span><span class="z-string">older</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> m</span><span class="z-string">axUnderlyingAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="previewwithdraw"><code>previewWithdraw</code></h4> <p>Allows an on-chain or off-chain user to simulate the effects of their withdrawal at the current block, given current on-chain conditions.</p> <p>MUST return as close to and no fewer than the exact amount of principal tokens that would be burned in a <code>withdraw</code> call in the same transaction. I.e. <code>withdraw</code> should return the same or fewer <code>principalAmount</code> as <code>previewWithdraw</code> if called in the same transaction.</p> <p>MUST NOT account for withdrawal limits like those returned from maxWithdraw and should always act as though the withdrawal would be accepted, regardless if the user has enough principal tokens, etc.</p> <p>MUST be inclusive of withdrawal fees. Integrators should be aware of the existence of withdrawal fees.</p> <p>MUST NOT revert due to principal token contract specific user/global limits. MAY revert due to other conditions that would also cause <code>withdraw</code> to revert.</p> <p>Note that any unfavorable discrepancy between <code>convertToPrincipal</code> and <code>previewWithdraw</code> SHOULD be considered slippage in price-per-principal-token or some other type of condition.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">reviewWithdraw</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> v</span><span class="z-string">iew</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> u</span><span class="z-string">nderlyingAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">rincipalAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h4 id="withdraw"><code>withdraw</code></h4> <p>Burns <code>principalAmount</code> from <code>holder</code> and sends exactly <code>underlyingAmount</code> of underlying tokens to <code>receiver</code>.</p> <p>MUST emit the <code>Redeem</code> event.</p> <p>MUST support a withdraw flow where the principal tokens are burned from <code>holder</code> directly where <code>holder</code> is <code>msg.sender</code> or <code>msg.sender</code> has <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> approval over the principal tokens of <code>holder</code>. MAY support an additional flow in which the principal tokens are transferred to the principal token contract before the <code>withdraw</code> execution, and are accounted for during <code>withdraw</code>.</p> <p>MUST revert if all of <code>underlyingAmount</code> cannot be withdrawn (due to withdrawal limit being reached, slippage, the holder not having enough principal tokens, etc).</p> <p>Note that some implementations will require pre-requesting to the principal token contract before a withdrawal may be performed. Those methods should be performed separately.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> w</span><span class="z-string">ithdraw</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> u</span><span class="z-string">nderlyingAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">eceiver</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> h</span><span class="z-string">older</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> p</span><span class="z-string">rincipalAmount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h3 id="events">Events</h3> <h4 id="redeem-1">Redeem</h4> <p><code>from</code> has exchanged <code>principalAmount</code> of Principal Tokens for <code>underlyingAmount</code> of underlying, and transferred that underlying to <code>to</code>.</p> <p>MUST be emitted when Principal Tokens are burnt and underlying is withdrawn from the contract in the <code>EIP5095.redeem</code> method.</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> R</span><span class="z-string">edeem</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> e</span><span class="z-string">vent</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> f</span><span class="z-string">rom</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> t</span><span class="z-string">o</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">mount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ndexed</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The Principal Token interface is designed to be optimized for integrators with a core minimal interface alongside optional interfaces to enable backwards compatibility. Details such as accounting and management of underlying are intentionally not specified, as Principal Tokens are expected to be treated as black boxes on-chain and inspected off-chain before use.</p> <p><a href="https://wg-eips.ritovision.com/20/">EIP-20</a> is enforced as implementation details such as token approval and balance calculation directly carry over. This standardization makes Principal Tokens immediately compatible with all <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> use cases in addition to EIP-5095.</p> <p>All principal tokens are redeemable upon maturity, with the only variance being whether further yield is generated post-maturity. Given the ubiquity of redemption, the presence of <code>redeem</code> allows integrators to purchase Principal Tokens on an open market, and them later redeem them for a fixed-yield solely knowing the address of the Principal Token itself.</p> <p>This EIP draws heavily on the design of <a href="https://wg-eips.ritovision.com/4626/">EIP-4626</a> because technically Principal Tokens could be described as a subset of Yield Bearing Vaults, extended with a <code>maturity</code> variable and restrictions on the implementation. However, extending <a href="https://wg-eips.ritovision.com/4626/">EIP-4626</a> would force PT implementations to include methods (namely, <code>mint</code> and <code>deposit</code>) that are not necessary to the business case that PTs solve. It can also be argued that partial redemptions (implemented via <code>withdraw</code>) are rare for PTs.</p> <p>PTs mature at a precise second, but given the reactive nature of smart contracts, there can't be an event marking maturity, because there is no guarantee of any activity at or after maturity. Emitting an event to notify of maturity in the first transaction after maturity would be imprecise and expensive. Instead, integrators are recommended to either use the first <code>Redeem</code> event, or to track themselves when each PT is expected to have matured.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backward compatible with the <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> specification and has no known compatibility issues with other standards. For production implementations of Principal Tokens which do not use EIP-5095, wrapper adapters can be developed and used, or wrapped tokens can be implemented.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span>pragma solidity 0.8.14;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>import {ERC20} from &quot;yield-utils-v2/contracts/token/ERC20.sol&quot;;</span></span> <span class="giallo-l"><span>import {MinimalTransferHelper} from &quot;yield-utils-v2/contracts/token/MinimalTransferHelper.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>contract ERC5095 is ERC20 {</span></span> <span class="giallo-l"><span> using MinimalTransferHelper for ERC20;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /* EVENTS</span></span> <span class="giallo-l"><span> *****************************************************************************************************************/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> event Redeem(address indexed from, address indexed to, uint256 underlyingAmount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /* MODIFIERS</span></span> <span class="giallo-l"><span> *****************************************************************************************************************/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice A modifier that ensures the current block timestamp is at or after maturity.</span></span> <span class="giallo-l"><span> modifier afterMaturity() virtual {</span></span> <span class="giallo-l"><span> require(block.timestamp &gt;= maturity, &quot;BEFORE_MATURITY&quot;);</span></span> <span class="giallo-l"><span> _;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /* IMMUTABLES</span></span> <span class="giallo-l"><span> *****************************************************************************************************************/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> ERC20 public immutable underlying;</span></span> <span class="giallo-l"><span> uint256 public immutable maturity;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /* CONSTRUCTOR</span></span> <span class="giallo-l"><span> *****************************************************************************************************************/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> constructor(</span></span> <span class="giallo-l"><span> string memory name_,</span></span> <span class="giallo-l"><span> string memory symbol_,</span></span> <span class="giallo-l"><span> uint8 decimals_,</span></span> <span class="giallo-l"><span> ERC20 underlying_,</span></span> <span class="giallo-l"><span> uint256 maturity_</span></span> <span class="giallo-l"><span> ) ERC20(name_, symbol_, decimals_) {</span></span> <span class="giallo-l"><span> underlying = underlying_;</span></span> <span class="giallo-l"><span> maturity = maturity_;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /* CORE FUNCTIONS</span></span> <span class="giallo-l"><span> *****************************************************************************************************************/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Burns an exact amount of principal tokens in exchange for an amount of underlying.</span></span> <span class="giallo-l"><span> /// @dev This reverts if before maturity.</span></span> <span class="giallo-l"><span> /// @param principalAmount The exact amount of principal tokens to be burned.</span></span> <span class="giallo-l"><span> /// @param from The owner of the principal tokens to be redeemed. If not msg.sender then must have prior approval.</span></span> <span class="giallo-l"><span> /// @param to The address to send the underlying tokens.</span></span> <span class="giallo-l"><span> /// @return underlyingAmount The total amount of underlying tokens sent.</span></span> <span class="giallo-l"><span> function redeem(</span></span> <span class="giallo-l"><span> uint256 principalAmount,</span></span> <span class="giallo-l"><span> address from,</span></span> <span class="giallo-l"><span> address to</span></span> <span class="giallo-l"><span> ) public virtual afterMaturity returns (uint256 underlyingAmount) {</span></span> <span class="giallo-l"><span> _decreaseAllowance(from, principalAmount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // Check for rounding error since we round down in previewRedeem.</span></span> <span class="giallo-l"><span> require((underlyingAmount = _previewRedeem(principalAmount)) != 0, &quot;ZERO_ASSETS&quot;);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _burn(from, principalAmount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> emit Redeem(from, to, principalAmount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _transferOut(to, underlyingAmount);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Burns a calculated amount of principal tokens in exchange for an exact amount of underlying.</span></span> <span class="giallo-l"><span> /// @dev This reverts if before maturity.</span></span> <span class="giallo-l"><span> /// @param underlyingAmount The exact amount of underlying tokens to be received.</span></span> <span class="giallo-l"><span> /// @param from The owner of the principal tokens to be redeemed. If not msg.sender then must have prior approval.</span></span> <span class="giallo-l"><span> /// @param to The address to send the underlying tokens.</span></span> <span class="giallo-l"><span> /// @return principalAmount The total amount of underlying tokens redeemed.</span></span> <span class="giallo-l"><span> function withdraw(</span></span> <span class="giallo-l"><span> uint256 underlyingAmount,</span></span> <span class="giallo-l"><span> address from,</span></span> <span class="giallo-l"><span> address to</span></span> <span class="giallo-l"><span> ) public virtual afterMaturity returns (uint256 principalAmount) {</span></span> <span class="giallo-l"><span> principalAmount = _previewWithdraw(underlyingAmount); // No need to check for rounding error, previewWithdraw rounds up.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _decreaseAllowance(from, principalAmount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _burn(from, principalAmount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> emit Redeem(from, to, principalAmount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> _transferOut(to, underlyingAmount);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice An internal, overridable transfer function.</span></span> <span class="giallo-l"><span> /// @dev Reverts on failed transfer.</span></span> <span class="giallo-l"><span> /// @param to The recipient of the transfer.</span></span> <span class="giallo-l"><span> /// @param amount The amount of the transfer.</span></span> <span class="giallo-l"><span> function _transferOut(address to, uint256 amount) internal virtual {</span></span> <span class="giallo-l"><span> underlying.safeTransfer(to, amount);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /* ACCOUNTING FUNCTIONS</span></span> <span class="giallo-l"><span> *****************************************************************************************************************/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Calculates the amount of underlying tokens that would be exchanged for a given amount of principal tokens.</span></span> <span class="giallo-l"><span> /// @dev Before maturity, it converts to underlying as if at maturity.</span></span> <span class="giallo-l"><span> /// @param principalAmount The amount principal on which to calculate conversion.</span></span> <span class="giallo-l"><span> /// @return underlyingAmount The total amount of underlying that would be received for the given principal amount..</span></span> <span class="giallo-l"><span> function convertToUnderlying(uint256 principalAmount) external view returns (uint256 underlyingAmount) {</span></span> <span class="giallo-l"><span> return _convertToUnderlying(principalAmount);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _convertToUnderlying(uint256 principalAmount) internal view virtual returns (uint256 underlyingAmount) {</span></span> <span class="giallo-l"><span> return principalAmount;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Converts a given amount of underlying tokens to principal exclusive of fees.</span></span> <span class="giallo-l"><span> /// @dev Before maturity, it converts to principal as if at maturity.</span></span> <span class="giallo-l"><span> /// @param underlyingAmount The total amount of underlying on which to calculate the conversion.</span></span> <span class="giallo-l"><span> /// @return principalAmount The amount principal tokens required to provide the given amount of underlying.</span></span> <span class="giallo-l"><span> function convertToPrincipal(uint256 underlyingAmount) external view returns (uint256 principalAmount) {</span></span> <span class="giallo-l"><span> return _convertToPrincipal(underlyingAmount);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _convertToPrincipal(uint256 underlyingAmount) internal view virtual returns (uint256 principalAmount) {</span></span> <span class="giallo-l"><span> return underlyingAmount;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Allows user to simulate redemption of a given amount of principal tokens, inclusive of fees and other</span></span> <span class="giallo-l"><span> /// current block conditions.</span></span> <span class="giallo-l"><span> /// @dev This reverts if before maturity.</span></span> <span class="giallo-l"><span> /// @param principalAmount The amount of principal that would be redeemed.</span></span> <span class="giallo-l"><span> /// @return underlyingAmount The amount of underlying that would be received.</span></span> <span class="giallo-l"><span> function previewRedeem(uint256 principalAmount) external view afterMaturity returns (uint256 underlyingAmount) {</span></span> <span class="giallo-l"><span> return _previewRedeem(principalAmount);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _previewRedeem(uint256 principalAmount) internal view virtual returns (uint256 underlyingAmount) {</span></span> <span class="giallo-l"><span> return _convertToUnderlying(principalAmount); // should include fees/slippage</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Calculates the maximum amount of principal tokens that an owner could redeem.</span></span> <span class="giallo-l"><span> /// @dev This returns 0 if before maturity.</span></span> <span class="giallo-l"><span> /// @param owner The address for which the redemption is being calculated.</span></span> <span class="giallo-l"><span> /// @return maxPrincipalAmount The maximum amount of principal tokens that can be redeemed by the given owner.</span></span> <span class="giallo-l"><span> function maxRedeem(address owner) public view returns (uint256 maxPrincipalAmount) {</span></span> <span class="giallo-l"><span> return block.timestamp &gt;= maturity ? _balanceOf[owner] : 0;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Allows user to simulate withdraw of a given amount of underlying tokens.</span></span> <span class="giallo-l"><span> /// @dev This reverts if before maturity.</span></span> <span class="giallo-l"><span> /// @param underlyingAmount The amount of underlying tokens that would be withdrawn.</span></span> <span class="giallo-l"><span> /// @return principalAmount The amount of principal tokens that would be redeemed.</span></span> <span class="giallo-l"><span> function previewWithdraw(uint256 underlyingAmount) external view afterMaturity returns (uint256 principalAmount) {</span></span> <span class="giallo-l"><span> return _previewWithdraw(underlyingAmount);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function _previewWithdraw(uint256 underlyingAmount) internal view virtual returns (uint256 principalAmount) {</span></span> <span class="giallo-l"><span> return _convertToPrincipal(underlyingAmount); // should include fees/slippage</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Calculates the maximum amount of underlying tokens that can be withdrawn by a given owner.</span></span> <span class="giallo-l"><span> /// @dev This returns 0 if before maturity.</span></span> <span class="giallo-l"><span> /// @param owner The address for which the withdraw is being calculated.</span></span> <span class="giallo-l"><span> /// @return maxUnderlyingAmount The maximum amount of underlying tokens that can be withdrawn by a given owner.</span></span> <span class="giallo-l"><span> function maxWithdraw(address owner) public view returns (uint256 maxUnderlyingAmount) {</span></span> <span class="giallo-l"><span> return _previewWithdraw(maxRedeem(owner));</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Fully permissionless use cases could fall prey to malicious implementations which only conform to the interface in this EIP but not the specification, failing to implement proper custodial functionality but offering the ability to purchase Principal Tokens through secondary markets.</p> <p>It is recommended that all integrators review each implementation for potential ways of losing user deposits before integrating.</p> <p>The <code>convertToUnderlying</code> method is an estimate useful for display purposes, and do <em>not</em> have to confer the <em>exact</em> amount of underlying assets their context suggests.</p> <p>As is common across many standards, it is strongly recommended to mirror the underlying token's <code>decimals</code> if at all possible, to eliminate possible sources of confusion and simplify integration across front-ends and for other off-chain users.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-04-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Tylerhttps://github.com/radiocaca Alexhttps://github.com/gojazdev Johnhttps://github.com/sfumato00 https://wg-eips.ritovision.com/5058/

Lockable EIP-721 tokens

<h2 id="abstract">Abstract</h2> <p>We propose to extend the <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> standard with a secure locking mechanism. The NFT owners approve the operator to lock the NFT through <code>setLockApprovalForAll()</code> or <code>lockApprove()</code>. The approved operator locks the NFT through <code>lock()</code>. The locked NFTs cannot be transferred until the end of the locking period. An immediate use case is to allow NFTs to participate in smart contracts without leaving the wallets of their owners.</p> <h2 id="motivation">Motivation</h2> <p>NFTs, enabled by <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>, have exploded in demand. The total market value and the ecosystem continue to grow with more and more blue chip NFTs, which are approximately equivalent to popular intellectual properties in a conventional sense. Despite the vast success, something is left to be desired. Liquidity has always been one of the biggest challenges for NFTs. Several attempts have been made to tackle the liquidity challenge: NFTFi and BendDAO, to name a few. Utilizing the currently prevalent EIP-721 standard, these projects require participating NFTs to be transferred to the projects' contracts, which poses inconveniences and risks to the owners:</p> <ol> <li>Smart contract risks: NFTs can be lost or stolen due to bugs or vulnerabilities in the contracts.</li> <li>Loss of utility: NFTs have utility values, such as profile pictures and bragging rights, which are lost when the NFTs are no longer seen under the owners' custody.</li> <li>Missing Airdrops: The owners can no longer directly receive airdrops entitled to the NFTs. Considering the values and price fluctuation of some of the airdrops, either missing or not getting the airdrop on time can financially impact the owners.</li> </ol> <p>All of the above are bad UX, and we believe the EIP-721 standard can be improved by adopting a native locking mechanism:</p> <ol> <li>Instead of being transferred to a smart contract, an NFT remains in self-custody but locked.</li> <li>While an NFT is locked, its transfer is prohibited. Other properties remain unaffected.</li> <li>The owners can receive or claim airdrops themselves.</li> </ol> <p>The value of an NFT can be reflected in two aspects: collection value and utility value. Collection value needs to ensure that the holder's wallet retains ownership of the NFT forever. Utility value requires ensuring that the holder can verify their NFT ownership in other projects. Both of these aspects require that the NFT remain in its owner's wallet.</p> <p>The proposed standard allows the underlying NFT assets to be managed securely and conveniently by extending the EIP-721 standard to natively support common NFTFi use cases including locking, staking, lending, and crowdfunding. We believe the proposed standard will encourage NFT owners to participate more actively in NFTFi projects and, hence, improve the livelihood of the whole NFT ecosystem.</p> <h2 id="specification">Specification</h2> <p>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> <p>Lockable EIP-721 <strong>MUST</strong> implement the <code>IERC5058</code> interfaces:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.8</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> EIP-721 Non-Fungible Token Standard, optional lockable extension</span></span> <span class="giallo-l"><span class="z-comment"> * ERC721 Token that can be locked for a certain period and cannot be transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * This is designed for a non-escrow staking contract that comes later to lock a user&#39;s NFT</span></span> <span class="giallo-l"><span class="z-comment"> * while still letting them keep it in their wallet.</span></span> <span class="giallo-l"><span class="z-comment"> * This extension can ensure the security of user tokens during the staking period.</span></span> <span class="giallo-l"><span class="z-comment"> * If the nft lending protocol is compatible with this extension, the trouble caused by the NFT</span></span> <span class="giallo-l"><span class="z-comment"> * airdrop can be avoided, because the airdrop is still in the user&#39;s wallet</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5058</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `tokenId` token is locked by `operator` from `from`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Locked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> expired</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `tokenId` token is unlocked by `operator` from `from`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Unlocked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `owner` enables `approved` to lock the `tokenId` token.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LockApproval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> approved</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `owner` enables or disables (`approved`) `operator` to lock all of its tokens.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LockApprovalForAll</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> approved</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the locker who is locking the `tokenId` token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lockerOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> locker</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Lock `tokenId` token until the block number is greater than `expired` to be unlocked.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` token must be owned by `owner`.</span></span> <span class="giallo-l"><span class="z-comment"> * - `expired` must be greater than block.number</span></span> <span class="giallo-l"><span class="z-comment"> * - If the caller is not `owner`, it must be approved to lock this token</span></span> <span class="giallo-l"><span class="z-comment"> * by either {lockApprove} or {setLockApprovalForAll}.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {Locked} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lock</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> expired</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Unlock `tokenId` token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` token must be owned by `owner`.</span></span> <span class="giallo-l"><span class="z-comment"> * - the caller must be the operator who locks the token by {lock}</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {Unlocked} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unlock</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Gives permission to `to` to lock `tokenId` token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - The caller must own the token or be an approved lock operator.</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {LockApproval} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lockApprove</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Approve or remove `operator` as an lock operator for the caller.</span></span> <span class="giallo-l"><span class="z-comment"> * Operators can call {lock} for any token owned by the caller.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - The `operator` cannot be the caller.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits an {LockApprovalForAll} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setLockApprovalForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> approved</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the account lock approved for `tokenId` token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLockApproved</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns if the `operator` is allowed to lock all of the assets of `owner`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * See {setLockApprovalForAll}</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isLockApprovedForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns if the `tokenId` token is locked.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isLocked</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns the `tokenId` token lock expired time.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lockExpiredTime</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="nft-lock-approvals">NFT lock approvals</h3> <p>An NFT owner can give another trusted operator the right to lock his NFT through the approve functions. The <code>lockApprove()</code> function only approves for the specified NFT, whereas <code>setLockApprovalForAll()</code> approves for all NFTs of the collection under the wallet. When a user participates in an NFTFi project, the project contract calls <code>lock()</code> to lock the user's NFT. Locked NFTs cannot be transferred, but the NFTFi project contract can use the unlock function <code>unlock()</code> to unlock the NFT.</p> <h3 id="nft-lock-unlock">NFT lock/unlock</h3> <p>Authorized project contracts have permission to lock NFT with the <code>lock</code> method. Locked NFTs cannot be transferred until the lock time expires. The project contract also has permission to unlock NFT in advance through the <code>unlock</code> function. Note that only the address of the locked NFT has permission to unlock that NFT.</p> <h3 id="nft-lock-period">NFT lock period</h3> <p>When locking an NFT, one must specify the lock expiration block number, which must be greater than the current block number. When the current block number exceeds the expiration block number, the NFT is automatically released and can be transferred.</p> <h3 id="bound-nft">Bound NFT</h3> <p>Bound NFT is an extension of this EIP, which implements the ability to mint a boundNFT during the NFT locking period. The boundNFT is identical to the locked NFT metadata and can be transferred. However, a boundNFT only exists during the NFT locking period and will be destroyed after the NFT is unlocked. BoundNFT can be used to lend, as a staking credential for the contract. The credential can be locked in the contract, but also to the user. In NFT leasing, boundNFT can be rented to users because boundNFT is essentially equivalent to NFT. This consensus, if accepted by all projects, boundNFT will bring more creativity to NFT.</p> <h3 id="bound-nft-factory">Bound NFT Factory</h3> <p>Bound NFT Factory is a common boundNFT factory, similar to Uniswap's <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> pairs factory. It uses the create2 method to create a boundNFT contract address for any NFT deterministic. BoundNFT contract that has been created can only be controlled by the original NFT contract.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard is compatible with EIP-721.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases written using hardhat can be found <a href="https://wg-eips.ritovision.com/5058/./assets/test/test.ts">here</a></p> <h2 id="reference-implementation">Reference Implementation</h2> <p>You can find an implementation of this standard in the <a href="https://wg-eips.ritovision.com/5058/./assets/ERC5058.sol">assets</a> folder.</p> <h2 id="security-considerations">Security Considerations</h2> <p>After being locked, the NFT can not be transferred, so before authorizing locking rights to other project contracts, you must confirm that the project contract can unlock NFT. Otherwise there is a risk of NFT being permanently locked. It is recommended to give a reasonable locking period in use for projects. NFT can be automatically unlocked, which can reduce the risk to a certain extent.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-04-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Mudit Guptahttps://github.com/maxsam4 https://wg-eips.ritovision.com/5065/

Instruction for just transferring ether without transferring the flow of execution

<h2 id="abstract">Abstract</h2> <p>Add a new instruction that transfers ether to a destination address without handing over the flow of execution to it. It should work similarly to how <code>SELFDESTRUCT (0xFF)</code> transfers ether to the destination without making a call to it.</p> <h2 id="motivation">Motivation</h2> <p>From an architectural point of view, execution flow should never be handed over to an untrusted contract. Ethereum currently does not have any ideal way to transfer ether without transferring the flow of execution. People have come up with reentrancy guards and similar solutions to prevent some types of attacks but it's not an ideal solution. The only way to transfer ether from smart contracts without triggering a call is to create a dummy contract, send the precise amount of ether to it and then call <code>SELFDESTRUCT (0xFF)</code> from it.</p> <h2 id="specification">Specification</h2> <p>Introduce a new instruction, <code>AIRDROP</code> (<code>0xFG</code>) that transfers ether to the destination without making a call to it.</p> <h3 id="stack-input">Stack input</h3> <p>address: the account to send ether to. value: value in wei to send to the account.</p> <h3 id="gas">Gas</h3> <p>The total gas cost should be the sum of a static cost + address_access_cost + value_to_empty_account_cost.</p> <ul> <li>Static cost: 6700</li> <li>Dynamic cost: <ol> <li>address_access_cost: If the target is not in <code>accessed_addresses</code>, charge <code>COLD_ACCOUNT_ACCESS_COST</code> gas, and add the address to <code>accessed_addresses</code>. Otherwise, charge <code>WARM_STORAGE_READ_COST</code> gas. Currently, <code>COLD_ACCOUNT_ACCESS_COST</code> is 2600 while <code>WARM_STORAGE_READ_COST</code> is 100.</li> <li>value_to_empty_account_cost: If value is not 0 and the address given points to an empty account, then value_to_empty_account_cost is the account creation gas cost which currently is 25000. An account is empty if its balance is 0, its nonce is 0 and it has no code.</li> </ol> </li> </ul> <h2 id="rationale">Rationale</h2> <p>This behavior is already possible by deploying a new contract that does <code>SELFDESTRUCT (0xFF)</code> but it is prohibitively expensive. In most scenarios, the contract author only wants to transfer ether rather than transferring control of the execution. ERC20 can be used as a case study for this where most users transfer funds without a post-transfer hook.</p> <p>This instruction allows contracts to safely pass ether to an untrusted address without worrying about reentrancy or other malicious things an untrusted contract can do on.</p> <p>The static gas cost is derived by subtracting the gas stipend (2300) from the positive_value_cost of <code>CALL (0xF1)</code> opcode which is currently set to 9000.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No known issues as this is a new instruction that does not affect any old instructions and does not break any valid assumptions since it make not anything impossible possible.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO</p> <h2 id="security-considerations">Security Considerations</h2> <p>No known security risks.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a rel="external" href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p> 2022-04-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Qi Zhouhttps://github.com/qizhou https://wg-eips.ritovision.com/5027/

Change the limit on contract size from 24576 to infinity

<h2 id="abstract">Abstract</h2> <p>Remove the limit on the contract code size, i.e., only limit the contract code size by block gas limit, with minimal changes to existing code and proper gas metering adjustment to avoid possible attacks.</p> <h2 id="motivation">Motivation</h2> <p>The motivation is to remove the limit on the code size so that users can deploy a large-code contract without worrying about splitting the contract into several sub-contracts.</p> <p>With the dramatic growth of dApplications, the functionalities of smart contracts are becoming more and more complicated, and thus, the sizes of newly developed contracts are steadily increasing. As a result, we are facing more and more issues with the 24576-bytes contract size limit. Although several techniques such as splitting a large contract into several sub-contracts can alleviate the issue, these techniques inevitably increase the burden of developing/deploying/maintaining smart contracts.</p> <p>The proposal implements a solution to remove the existing 24576-bytes limit of the code size. Further, the proposal aims to minimize the changes in the client implementation (e.g., Geth) with</p> <ul> <li>proper gas metering to avoid abusing the node resources for contract-related opcodes, i.e, <code>CODESIZE (0x38)/CODECOPY (0x39)/EXTCODESIZE (0x3B)/EXTCODECOPY (0x3C)/EXTCODEHASH (0x3F)/DELEGATECALL (0xF4)/CALL (0xF1)/CALLCODE (0xF2)/STATICCALL (0xFA)/CREATE (0xF0)/CREATE2 (0xF5)</code>; and</li> <li>no change to the existing structure of the Ethereum state.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLKNUM</code></td><td>TBD</td></tr> <tr><td><code>CODE_SIZE_UNIT</code></td><td>24576</td></tr> <tr><td><code>COLD_ACCOUNT_CODE_ACCESS_COST_PER_UNIT</code></td><td>2600</td></tr> <tr><td><code>CREATE_DATA_GAS</code></td><td>200</td></tr> </tbody></table> <p>If <code>block.number &gt;= FORK_BLKNUM</code>, the contract creation initialization can return data with any length, but the contract-related opcodes will take extra gas as defined below:</p> <ul> <li> <p>For <code>CODESIZE/CODECOPY/EXTCODESIZE/EXTCODEHASH</code>, the gas is unchanged.</p> </li> <li> <p>For CREATE/CREATE2, if the newly created contract size &gt; <code>CODE_SIZE_UNIT</code>, the opcodes will take extra write gas as</p> </li> </ul> <p><code>(CODE_SIZE - CODE_SIZE_UNIT) * CREATE_DATA_GAS</code>.</p> <ul> <li>For <code>EXTCODECOPY/CALL/CALLCODE/DELEGATECALL/STATICCALL</code>, if the contract code size &gt; <code>CODE_SIZE_UNIT</code>, then the opcodes will take extra gas as</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(CODE_SIZE - 1) // CODE_SIZE_UNIT * COLD_ACCOUNT_CODE_ACCESS_COST_PER_UNIT</span></span></code></pre> <p>if the contract is not in <code>accessed_code_in_addresses</code> or <code>0</code> if the contract is in <code>accessed_code_in_addresses</code>, where <code>//</code> is the integer divide operator, and <code>accessed_code_in_addresses: Set[Address]</code> is a transaction-context-wide set similar to <code>access_addresses</code> and <code>accessed_storage_keys</code>.</p> <p>When a transaction execution begins, <code>accessed_code_in_addresses</code> will include <code>tx.sender</code>, <code>tx.to</code>, and all precompiles.</p> <p>When <code>CREATE/CREATE2/EXTCODECOPY/CALL/CALLCODE/DELEGATECALL/STATICCALL</code> is called, immediately add the address to <code>accessed_code_in_addresses</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="gas-metering">Gas Metering</h3> <p>The goal is to measure the CPU/IO cost of the contract read/write operations reusing existing gas metering so that the resources will not be abused.</p> <ul> <li> <p>For code-size-related opcodes (<code>CODESIZE</code>/<code>EXTCODESIZE</code>), we would expect the client to implement a mapping from the hash of code to the size, so reading the code size of a large contract should still be O(1).</p> </li> <li> <p>For <code>CODECOPY</code>, the data is already loaded in memory (as part of <code>CALL/CALLCODE/DELEGATECALL/STATICCALL</code>), so we do not charge extra gas.</p> </li> <li> <p>For <code>EXTCODEHASH</code>, the value is already in the account, so we do not charge extra gas.</p> </li> <li> <p>For <code>EXTCODECOPY/CALL/CALLCODE/DELEGATECALL/STATICCALL</code>, since it will read extra data from the database, we will additionally charge <code>COLD_ACCOUNT_CODE_ACCESS_COST_PER_UNIT</code> per extra <code>CODE_SIZE_UNIT</code>.</p> </li> <li> <p>For <code>CREATE/CREATE2</code>, since it will create extra data to the database, we will additionally charge <code>CREATE_DATA_GAS</code> per extra bytes.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>All existing contracts will not be impacted by the proposal.</p> <p>Only contracts deployed before <a href="https://wg-eips.ritovision.com/170/">EIP-170</a> could possibly be longer than the current max code size, and the reference implementation was able to successfully import all blocks before that fork.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation on Geth is available at <a href="https://wg-eips.ritovision.com/5027/./assets/0001-unlimit-code-size.patch">0001-unlimit-code-size.patch</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-04-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Greenhttps://github.com/greenlucid https://wg-eips.ritovision.com/5022/ <h3 id="abstract">Abstract</h3> <p>Increase the price of the SSTORE opcode from <code>20_000</code> gas to <code>40_000</code> gas when the original slot is zero and the resultant slot is non-zero.</p> <h3 id="motivation">Motivation</h3> <p>The cost of creating a piece of new state increases as state is larger. However, the price for creating every new storage slot has not increased. All resources are merged into the same pricing mechanism. If the price for creating new storage slots is fixed, then it needs to be manually changed.</p> <p>One of the main reasons for not increasing gas limit is the increase of state. In that regard, because the cost of creating storage is higher than its price, all the users of all the other opcodes are subsidizing the creation of state. If state creation was more precisely priced, raising gas limit would be more feasible, and would benefit the users.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-not-also-raise-the-cost-of-non-zero-to-non-zero">Why not also raise the cost of non-zero to non-zero?</h3> <p>Rewriting storage does not affect state growth, which is the main issue this EIP is addressing. Rewriting storage may also be underpriced. Increasing the price of state growth will, at least, incentivize developers to reuse storage instead.</p> <h3 id="why-not-also-increase-the-gas-refund-from-setting-non-zero-to-zero">Why not also increase the gas refund from setting non-zero to zero?</h3> <p>More discussion is needed on this.</p> <h3 id="why-not-a-better-state-solution">Why not a better state solution?</h3> <p>Whereas solutions like state rent, or state expiry have been researched for a long time, they will not be ready on the short to medium term. So, it is desirable to patch pricing for the short term. Opcode repricing has been done before, so it should not impose a large development time investment for clients.</p> <h3 id="why-was-that-specific-amount-chosen">Why was that specific amount chosen?</h3> <p>The current pricing was made off a naive approach of benchmarking opcodes in a laptop. Not only it did not consider the long term problem of having the same price for a resource that costs more over time, the benchmark itself was wrong. This price is closer to what the naive original benchmark should have been. It could go higher, but that may be too disruptive.</p> <h3 id="is-this-too-disruptive">Is this too disruptive?</h3> <p>This change will severely impact the gas cost of many applications. The network does not have to subsidize state growth at the expense of more expensive regular transactions, so even if it is too disruptive, it will increase the health of the network.</p> <h3 id="specification">Specification</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLOCK</code></td><td>TBD</td></tr> <tr><td><code>NEW_STORAGE_PRICE</code></td><td><code>40_000</code></td></tr> </tbody></table> <p>For blocks where <code>block.number &gt;= FORK_BLOCK</code>, a new gas schedule applies. Make <code>SSTORE_SET_GAS</code>, the price when a slot is set from zero to non-zero, equal <code>NEW_STORAGE_PRICE</code>. All other costs remain the same.</p> <h3 id="backwards-compatibility">Backwards compatibility</h3> <p>Contracts that depend on hardcoded gas costs will break if they create state.</p> <p>It is a gas schedule change, so transactions from an epoch before FORK_BLOCK should be treated with previous gas costs.</p> <h2 id="implementation">Implementation</h2> <p>https://github.com/ethereum/go-ethereum/pull/24725</p> <h2 id="security-considerations">Security considerations</h2> <p>TODO</p> 2022-04-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Qi Zhouhttps://github.com/qizhou https://wg-eips.ritovision.com/5018/

An interface to provide access to binary objects similar to filesystems.

<h2 id="abstract">Abstract</h2> <p>The following standardizes an API for directories and files within smart contracts, similar to traditional filesystems. This standard provides basic functionality to read/write binary objects of any size, as well as allow reading/writing chunks of the object if the object is too large to fit in a single transaction.</p> <h2 id="motivation">Motivation</h2> <p>A standard interface allows any binary objects on EVM-based blockchain to be re-used by other dApps.</p> <p>With <a href="https://wg-eips.ritovision.com/4804/">EIP-4804</a>, we are able to locate a Web3 resource on blockchain using HTTP-style URIs. One application of Web3 resources are web contents that are referenced within a directory using relative paths such as HTML/SVG. This standard proposes a contract-based directory to simplify the mapping between local web contents and on-chain web contents. Further, with relative paths referenced in the web contents and EIP-4804, the users will have a consistent view of the web contents locally and on-chain.</p> <h2 id="specification">Specification</h2> <h3 id="directory">Directory</h3> <h4 id="methods">Methods</h4> <h5 id="write">write</h5> <p>Writes binary <code>data</code> to the file <code>name</code> in the directory by an account with write permission.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function write(bytes memory name, bytes memory data) external payable</span></span></code></pre><h5 id="read">read</h5> <p>Returns the binary <code>data</code> from the file <code>name</code> in the directory and existence of the file.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function read(bytes memory name) external view returns (bytes memory data, bool exist)</span></span></code></pre><h5 id="fallback-read">fallback read</h5> <p>Returns the binary <code>data</code> from the file <code>prefixedName</code> (prefixed with <code>/</code>) in the directory.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>fallback(bytes calldata prefixedName) external returns (bytes memory data) </span></span></code></pre><h5 id="size">size</h5> <p>Returns the size of the <code>data</code> from the file <code>name</code> in the directory and the number of chunks of the data.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function size(bytes memory name) external view returns (uint256 size, uint256 chunks)</span></span></code></pre><h5 id="remove">remove</h5> <p>Removes the file <code>name</code> in the directory and returns the number of chunks removed (0 means the file does not exist) by an account with write permission.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function remove(bytes memory name) external returns (uint256 numOfChunksRemoved)</span></span></code></pre><h5 id="countchunks">countChunks</h5> <p>Returns the number of chunks of the file <code>name</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function countChunks(bytes memory name) external view returns (uint256 numOfChunks);</span></span></code></pre><h5 id="writechunk">writeChunk</h5> <p>Writes a chunk of data to the file by an account with write permission. The write will fail if <code>chunkId &gt; numOfChunks</code>, i.e., the write must append the file or replace the existing chunk.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> function writeChunk(bytes memory name, uint256 chunkId, bytes memory chunkData) external payable;</span></span></code></pre><h5 id="readchunk">readChunk</h5> <p>Returns the chunk data of the file <code>name</code> and the existence of the chunk.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function readChunk(bytes memory name, uint256 chunkId) external view returns (bytes memory chunkData, bool exist);</span></span></code></pre><h5 id="chunksize">chunkSize</h5> <p>Returns the size of a chunk of the file <code>name</code> and the existence of the chunk.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function chunkSize(bytes memory name, uint256 chunkId) external view returns (uint256 chunkSize, bool exist);</span></span></code></pre><h5 id="removechunk">removeChunk</h5> <p>Removes a chunk of the file <code>name</code> and returns <code>false</code> if such chunk does not exist. The method should be called by an account with write permission.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function removeChunk(bytes memory name, uint256 chunkId) external returns (bool exist);</span></span></code></pre><h5 id="truncate">truncate</h5> <p>Removes the chunks of the file <code>name</code> in the directory from the given <code>chunkId</code> and returns the number of chunks removed by an account with write permission. When <code>chunkId = 0</code>, the method is essentially the same as <code>remove()</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function truncate(bytes memory name, uint256 chunkId) external returns (uint256 numOfChunksRemoved);</span></span></code></pre><h5 id="getchunkhash">getChunkHash</h5> <p>Returns the hash value of the chunk data.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getChunkHash(bytes memory name, uint256 chunkId) external view returns (bytes32);</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>One issue of uploading the web contents to the blockchain is that the web contents may be too large to fit into a single transaction. As a result, the standard provides chunk-based operations so that uploading a content can be split into several transactions. Meanwhile, the read operation can be done in a single transaction, i.e., with a single Web3 URL defined in EIP-4804.</p> <h3 id="interactions-between-unchunked-chunked-functions">Interactions Between Unchunked/Chunked Functions</h3> <p><code>read</code> method should return the concatenated chunked data written by <code>writeChunk</code> method. The following gives some examples of the interactions:</p> <ul> <li><code>read("hello.txt")</code> =&gt; "" (file is empty)</li> <li><code>writeChunk("hello.txt", 0, "abc")</code> will succeed</li> <li><code>read("hello.txt")</code> =&gt; "abc"</li> <li><code>writeChunk("hello.txt", 1, "efg")</code> will succeed</li> <li><code>read("hello.txt")</code> =&gt; "abcefg"</li> <li><code>writeChunk("hello.txt", 0, "aaa")</code> will succeed (replace chunk 0's data)</li> <li><code>read("hello.txt")</code> =&gt; "aaaefg"</li> <li><code>writeChunk("hello.txt", 3, "hij")</code> will fail because the operation is not replacement or append.</li> </ul> <p>With <code>writeChunk</code> method, we allow writing a file with external data that exceeds the current calldata limit (e.g., 1.8MB now), and it is able to read the whole file in a single <code>read</code> method (which is friendly for large web objects such as HTML/SVG/PNG/JPG, etc).</p> <p>For <code>write</code> method, calling a <code>write</code> method will replace all data chunks of the file with <code>write</code> method data, and one implementation can be:</p> <ol> <li><code>writeChunk(filename, chunkId=0, data_from_write)</code> to chunk 0 with the same <code>write</code> method data; and</li> <li><code>truncate(filename, chunkId=1)</code>, which will remove the rest chunks.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility issues were identified.</p> <h2 id="security-considerations">Security Considerations</h2> <p>No security considerations were found.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-04-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 DerivStudiohttps://github.com/DerivStudio https://wg-eips.ritovision.com/5187/

Separate ownership and usage rights of EIP-1155 to allow users to use NFTs for an allotted time and return them to owners after expiration.

<h2 id="abstract">Abstract</h2> <p>This standard is an extension of <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>. It proposes to introduce separable, rentable, and transferable usage rights (in the form of NFT-IDs), enabling the property owner (the only NFT holder) to rent out the NFT to multiple users (ID holders) at the same time for different terms, and be withdrawn by smart contract upon expiration.</p> <p>The property owner always retains ownership and is able to transfer the NFT to others during the lease.</p> <p>The proposal also supports the sublease and renewal of the rental so that users can freely transfer the usage rights among each other and extend the lease term. Early return of NFTs can also be achieved by subletting the usage rights back to the property owners.</p> <h2 id="motivation">Motivation</h2> <p>The well-accepted <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and EIP-1155 standards focused on the ownership of unique assets, quite sensible in the time of NFTs being used primarily as arts and collectibles, or, you can say, as private property rights.</p> <h3 id="first-step-expirable-nfts">First Step: "Expirable" NFTs</h3> <p>The advent of private ownership in the real world has promoted the vigorous development of the modern economy, and we believe that the usage right will be the first detachable right widely applied in the blockchain ecosystem. As NFTs are increasingly applied in rights, finance, games, and the Metaverse, the value of NFT is no longer simply the proof of ownership, but with limitless practice use scenarios. For example, artists may wish to rent out their artworks to media or audiences within specific periods, and game guilds may wish to rent out game items to new players to reduce their entry costs.</p> <p>The lease/rental of NFTs in the crypto space is not a new topic, but the implementation of leasing has long relied on over-collateralization, centralized custody, or pure trust, which significantly limits the boom of the leasing market. Therefore, a new type of "expirable" NFTs that can be automatically withdrawn upon expiration through smart contract is proposed, at the technical level, to eliminate those bottlenecks. Based on that, a new leasing model that is decentralized, collateral-free, and operated purely "on-chain" may disrupt the way people trade and use NFTs. Thus, this EIP proposal is here to create "expirable" NFTs compatible with EIP-1155.</p> <h3 id="then-make-everything-transferable">Then, Make Everything Transferable</h3> <p>The way we achieve leasing is to separate ownership and usage rights, and beyond that, we focus more on making them freely priced and traded after separation, which is impossible to happen in the traditional financial field. Imagine the below scenarios: i) as a landlord, you can sell your house in rental to others without affecting the tenancy, and your tenants will then pay rent to the new landlord; ii) as a tenant, you can sublet the house to others without the consent of the landlord, and even the one sublets can continue subletting the house until the lease term is close the last tenant can apply for a renewal of the lease. All of this can happen in the blockchain world, and that's the beauty of blockchain. Without permission, without trust, code is the law.</p> <p>Making ownership and usage rights transferable may further revolutionize the game rules in NFT's field, both in capital allocation and NFT development. Buying NFT ownership is more like investing in stocks, and the price is determined by market expectations of the project; renting the usage right is less speculative, so the price is easier to determine based on supply and demand. The ownership market and the usage-right market will function to meet the needs of target participants and achieve a balance that is conducive to the long-term and stable development of NFT projects. Based on the above, we propose this EIP standard to complement the current EIP scopes and introduce those functions as new standards.</p> <h2 id="specification">Specification</h2> <p>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> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x6938e358.</span></span> <span class="giallo-l"><span class="z-storage z-type"> interface</span><span class="z-entity z-name"> IRental</span><span class="z-comment"> /*</span><span class="z-comment"> is IERC165,IERC1155 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> This emits when user rent NFT</span></span> <span class="giallo-l"><span class="z-comment"> * - `id` The id of the current token</span></span> <span class="giallo-l"><span class="z-comment"> * - `user` The address to rent the NFT usage rights</span></span> <span class="giallo-l"><span class="z-comment"> * - `amount` The amount of usage rights</span></span> <span class="giallo-l"><span class="z-comment"> * - `expire` The specified period of time to rent</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Rented</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> id</span><span>,</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> expire</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * MUST trigger on any successful call to `renew(address user,uint256 id)`</span></span> <span class="giallo-l"><span class="z-comment"> * - `id` The id of the current token</span></span> <span class="giallo-l"><span class="z-comment"> * - `user` The user of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> * - `expire` The new specified period of time to rent</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Renew</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> id</span><span>,</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> expire</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * MUST trigger on any successful call to `renew(address user,uint256 id,uint256 expire)`</span></span> <span class="giallo-l"><span class="z-comment"> * - `id` The id of the current token</span></span> <span class="giallo-l"><span class="z-comment"> * - `from` The current user of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> * - `to` The new user</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Sublet</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> id</span><span>,</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>,</span><span class="z-support">address</span><span class="z-variable"> to</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> This emits when the NFT owner takes back the usage rights from the tenant (the `user`)</span></span> <span class="giallo-l"><span class="z-comment"> * - id The id of the current token</span></span> <span class="giallo-l"><span class="z-comment"> * - user The address to rent the NFT&#39;s usage rights</span></span> <span class="giallo-l"><span class="z-comment"> * - amount Amount of usage rights</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TakeBack</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> id</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Function to rent out usage rights</span></span> <span class="giallo-l"><span class="z-comment"> * - from The address to approve</span></span> <span class="giallo-l"><span class="z-comment"> * - to The address to rent the NFT usage rights</span></span> <span class="giallo-l"><span class="z-comment"> * - id The id of the current token</span></span> <span class="giallo-l"><span class="z-comment"> * - amount The amount of usage rights</span></span> <span class="giallo-l"><span class="z-comment"> * - expire The specified period of time to rent</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeRent</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> expire</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Function to take back usage rights after the end of the tenancy</span></span> <span class="giallo-l"><span class="z-comment"> * - user The address to rent the NFT&#39;s usage rights</span></span> <span class="giallo-l"><span class="z-comment"> * - tokenId The id of the current token</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> takeBack</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Return the NFT to the address of the NFT property right owner.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> propertyRightOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Return the total supply amount of the current token</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Return expire The specified period of time to rent</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> expireAt</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * extended rental period</span></span> <span class="giallo-l"><span class="z-comment"> * - `id` The id of the current token</span></span> <span class="giallo-l"><span class="z-comment"> * - `user` The user of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> * - `expire` The new specified period of time to rent</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> renew</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> expire</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * transfer of usage right</span></span> <span class="giallo-l"><span class="z-comment"> * - `id` The id of the current token</span></span> <span class="giallo-l"><span class="z-comment"> * - `user` The user of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> * - `expire` The new specified period of time to rent</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> sublet</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support">uint256</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <p>Implementing the proposal to create rentable NFTs has two main benefits.</p> <p>One is that NFTs with multiple usage rights allow NFT property owners to perform the safeRent function and rent out usage rights to multiple users at the same time. For each usage right leased and expires, the property owner can perform the takeBack function to retrieve the usage right.</p> <p>Another benefit is that the transfer of usage rights can be quite flexible. The user can transfer the usage rights to other users by calling the Sublet function during the lease period, and can also extend the lease period of the usage rights by asking the property owner to perform the Renewal function. It is worth mentioning that if the user sublet the NFT to the property owner, it will realize the early return of NFT before the end of the lease period.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As mentioned at the beginning, this is an extension of EIP-1155. Therefore, it is fully backward compatible with EIP-1155.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Disclaimer of copyright and related rights through <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-04-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Auryn Macmillanhttps://github.com/auryn-macmillan Kei Kreutlerhttps://github.com/keikreutler https://wg-eips.ritovision.com/5005/

Composable interoperable programmable accounts

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes interfaces for composable and interoperable tooling for programmable Ethereum accounts. These interfaces separate contract accounts ("avatars") from their authentication and execution logic ("guards" and "modules"). Avatars implement the <code>IAvatar</code> interface, and guards implement the <code>IGuard</code> interface. Modules may take any form.</p> <h2 id="motivation">Motivation</h2> <p>Currently, most programmable accounts (like DAO tools and frameworks) are built as monolithic systems where the authorization and execution logic are coupled, either within the same contract or in a tightly integrated system of contracts. This needlessly inhibits the flexibility of these tools and encourages platform lock-in via high switching costs.</p> <p>By using the this EIP standard to separate concerns (decoupling authentication and execution logic), users are able to:</p> <ol> <li>Enable flexible, module-based control of programmable accounts</li> <li>Easily switch between tools and frameworks without unnecessary overhead.</li> <li>Enable multiple control mechanism in parallel.</li> <li>Enable cross-chain / cross-layer governance.</li> <li>Progressively decentralize their governance as their project and community matures.</li> </ol> <h2 id="specification">Specification</h2> <p>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> <p>This EIP consists of four key concepts:</p> <ul> <li><strong>Avatars</strong> are programmable Ethereum accounts. Avatars are the address that holds balances, owns systems, executes transaction, is referenced externally, and ultimately represents your DAO. Avatars MUST implement the <code>IAvatar</code> interface.</li> <li><strong>Modules</strong> are contracts enabled by an avatar that implement some execution logic.</li> <li><strong>Modifiers</strong> are contracts that sit between modules and avatars to modify the module's behavior. For example, they might enforce a delay on all functions a module attempts to execute or limit the scope of transactions that can be initiated by the module. Modifiers MUST implement the <code>IAvatar</code> interface.</li> <li><strong>Guards</strong> are contracts that MAY be enabled on modules or modifiers and implement pre- or post-checks on each transaction executed by those modules or modifiers. This allows avatars to do things like limit the scope of addresses and functions that a module or modifier can call or ensure a certain state is never changed by a module or modifier. Guards MUST expose the <code>IGuard</code> interface. Modules, modifiers, and avatars that wish to be guardable MUST inherit <code>Guardable</code>, MUST call <code>checkTransaction()</code> before triggering execution on their target, and MUST call <code>checkAfterExecution()</code> after execution is complete.</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> Avatar - A contract that manages modules that can execute transactions via this contract.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.7.0</span><span class="z-keyword"> &lt;</span><span class="z-constant">0.9</span><span>.</span><span class="z-constant">0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./Enum.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IAvatar</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> EnabledModule</span><span>(</span><span class="z-support">address</span><span class="z-variable"> module</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DisabledModule</span><span>(</span><span class="z-support">address</span><span class="z-variable"> module</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ExecutionFromModuleSuccess</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> module</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ExecutionFromModuleFailure</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> module</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Enables a module on the avatar.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Can only be called by the avatar.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Modules should be stored as a linked list.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Must emit EnabledModule(address module) if successful.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> module</span><span class="z-comment"> Module to be enabled.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> enableModule</span><span>(</span><span class="z-support">address</span><span class="z-variable"> module</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Disables a module on the avatar.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Can only be called by the avatar.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Must emit DisabledModule(address module) if successful.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> prevModule</span><span class="z-comment"> Address that pointed to the module to be removed in the linked list</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> module</span><span class="z-comment"> Module to be removed.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> disableModule</span><span>(</span><span class="z-support">address</span><span class="z-variable"> prevModule</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> module</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Allows a Module to execute a transaction.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Can only be called by an enabled module.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Must emit ExecutionFromModuleSuccess(address module) if successful.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Must emit ExecutionFromModuleFailure(address module) if unsuccessful.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> to</span><span class="z-comment"> Destination address of module transaction.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> value</span><span class="z-comment"> Ether value of module transaction.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> data</span><span class="z-comment"> Data payload of module transaction.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> operation</span><span class="z-comment"> Operation type of module transaction: 0 == call, 1 == delegate call.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> execTransactionFromModule</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Enum</span><span>.</span><span class="z-support z-variable">Operation</span><span class="z-variable"> operation</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Allows a Module to execute a transaction and return data</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Can only be called by an enabled module.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Must emit ExecutionFromModuleSuccess(address module) if successful.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Must emit ExecutionFromModuleFailure(address module) if unsuccessful.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> to</span><span class="z-comment"> Destination address of module transaction.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> value</span><span class="z-comment"> Ether value of module transaction.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> data</span><span class="z-comment"> Data payload of module transaction.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> operation</span><span class="z-comment"> Operation type of module transaction: 0 == call, 1 == delegate call.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> execTransactionFromModuleReturnData</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Enum</span><span>.</span><span class="z-support z-variable">Operation</span><span class="z-variable"> operation</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> returnData</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Returns if an module is enabled</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if the module is enabled</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isModuleEnabled</span><span>(</span><span class="z-support">address</span><span class="z-variable"> module</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Returns array of modules.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> start</span><span class="z-comment"> Start of the page.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> pageSize</span><span class="z-comment"> Maximum number of modules that should be returned.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> array</span><span class="z-comment"> Array of modules.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> next</span><span class="z-comment"> Start of the next page.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getModulesPaginated</span><span>(</span><span class="z-support">address</span><span class="z-variable"> start</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> pageSize</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> array</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> next</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.7.0</span><span class="z-keyword"> &lt;</span><span class="z-constant">0.9</span><span>.</span><span class="z-constant">0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./Enum.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IGuard</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkTransaction</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Enum</span><span>.</span><span class="z-support z-variable">Operation</span><span class="z-variable"> operation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> safeTxGas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> baseGas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> gasPrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> gasToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> payable</span><span class="z-variable"> refundReceiver</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> signatures</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> msgSender</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkAfterExecution</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> txHash</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> success</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.7.0</span><span class="z-keyword"> &lt;</span><span class="z-constant">0.9</span><span>.</span><span class="z-constant">0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./Enum.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./BaseGuard.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> Guardable - A contract that manages fallback calls made to this contract</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Guardable</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> guard</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ChangedGuard</span><span>(</span><span class="z-support">address</span><span class="z-variable"> guard</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `guard_` does not implement IERC165.</span></span> <span class="giallo-l"><span class="z-storage z-type"> error</span><span class="z-entity z-name"> NotIERC165Compliant</span><span>(</span><span class="z-support">address</span><span> guard_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Set a guard that checks transactions before execution.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _guard</span><span class="z-comment"> The address of the guard to be used or the 0 address to disable the guard.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setGuard</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _guard</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_guard </span><span class="z-keyword">!=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span class="z-entity z-name">BaseGuard</span><span>(</span><span>_guard</span><span>)</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-variable z-language">type</span><span>(</span><span>IGuard</span><span>)</span><span>.</span><span>interfaceId</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span class="z-entity z-name"> NotIERC165Compliant</span><span>(</span><span>_guard</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> guard </span><span class="z-keyword">=</span><span> _guard</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ChangedGuard</span><span>(</span><span>guard</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getGuard</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _guard</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> guard</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.7.0</span><span class="z-keyword"> &lt;</span><span class="z-constant">0.9</span><span>.</span><span class="z-constant">0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./Enum.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IGuard.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">abstract</span><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> BaseGuard</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> pure</span></span> <span class="giallo-l"><span class="z-storage z-type"> override</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IGuard</span><span>)</span><span>.</span><span>interfaceId </span><span class="z-keyword">||</span><span class="z-comment"> //</span><span class="z-comment"> 0xe6d7a83a</span></span> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC165</span><span>)</span><span>.</span><span>interfaceId</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x01ffc9a7</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Module transactions only use the first four parameters: to, value, data, and operation.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Module.sol hardcodes the remaining parameters as 0 since they are not used for module transactions.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkTransaction</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Enum</span><span>.</span><span class="z-support z-variable">Operation</span><span class="z-variable"> operation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> safeTxGas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> baseGas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> gasPrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> gasToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> payable</span><span class="z-variable"> refundReceiver</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> signatures</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> msgSender</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> virtual</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkAfterExecution</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> txHash</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> success</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> virtual</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.7.0</span><span class="z-keyword"> &lt;</span><span class="z-constant">0.9</span><span>.</span><span class="z-constant">0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> Enum - Collection of enums</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Enum</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> Operation</span><span> {</span><span class="z-variable z-other z-enummember">Call</span><span>,</span><span class="z-variable z-other z-enummember"> DelegateCall</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The interface defined in this standard is designed to be mostly compatible with most popular programmable accounts in use right now, to minimize the need for changes to existing tooling.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward compatibility issues are introduced by this standard.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are some considerations that module developers and users should take into account:</p> <ol> <li><strong>Modules have absolute control:</strong> Modules have absolute control over any avatar on which they are enabled, so any module implementation should be treated as security critical and users should be vary cautious about enabling new modules. ONLY ENABLE MODULES THAT YOU TRUST WITH THE FULL VALUE OF THE AVATAR.</li> <li><strong>Race conditions:</strong> A given avatar may have any number of modules enabled, each with unilateral control over the safe. In such cases, there may be race conditions between different modules and/or other control mechanisms.</li> <li><strong>Don't brick your avatar:</strong> There are no safeguards to stop you adding or removing modules. If you remove all of the modules that let you control an avatar, the avatar will cease to function and all funds will be stuck.</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-04-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Daniel Tedescohttps://github.com/dtedesco1 https://wg-eips.ritovision.com/4974/

An interface for assigning and managing numerical ratings

<h2 id="abstract">Abstract</h2> <p>This standard defines a standardized interface for assigning and managing numerical ratings on the Ethereum blockchain. This allows ratings to be codified within smart contracts and recognized by other applications, enabling a wide range of new use cases for tokens.</p> <h2 id="motivation">Motivation</h2> <p>Traditionally, blockchain applications have focused on buying and selling digital assets. However, the asset-centric model has often been detrimental to community-based blockchain projects, as seen in the pay-to-play dynamics of many EVM-based games and DAOs in 2021.</p> <p>This proposal addresses this issue by allowing ratings to be assigned to contracts and wallets, providing a new composable primitive for blockchain applications. This allows for a diverse array of new use cases, such as:</p> <ul> <li> <p>Voting weight in a DAO: Ratings assigned using this standard can be used to determine the voting weight of members in a decentralized autonomous organization (DAO). For example, a DAO may assign higher ratings to members who have demonstrated a strong track record of contributing to the community, and use these ratings to determine the relative influence of each member in decision-making processes.</p> </li> <li> <p>Experience points in a decentralized game ecosystem: Ratings can be used to track the progress of players in a decentralized game ecosystem, and to reward them for achieving specific milestones or objectives. For example, a game may use ratings to assign experience points to players, which can be used to unlock new content or abilities within the game.</p> </li> <li> <p>Loyalty points for customers of a business: Ratings can be used to track the loyalty of customers to a particular business or service, and to reward them for their continued support. For example, a business may use ratings to assign loyalty points to customers, which can be redeemed for special offers or discounts.</p> </li> <li> <p>Asset ratings for a decentralized insurance company: Ratings can be used to evaluate the risk profile of assets in a decentralized insurance company, and to determine the premiums and coverage offered to policyholders. For example, a decentralized insurance company may use ratings to assess the risk of different types of assets, and to provide lower premiums and higher coverage to assets with lower risk ratings.</p> </li> </ul> <p>This standard is influenced by the <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> and <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> token standards and takes cues from each in its structure, style, and semantics.</p> <h2 id="specification">Specification</h2> <p>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> <p>Every compliant contract MUST implement the following interfaces:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// SPDX-License-Identifier: CC0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>pragma solidity ^0.8.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/// @title EIP-4974 Ratings</span></span> <span class="giallo-l"><span>/// @dev See https://eips.ethereum.org/EIPS/EIP-4974</span></span> <span class="giallo-l"><span>/// Note: the EIP-165 identifier for this interface is #######.</span></span> <span class="giallo-l"><span>/// Must initialize contracts with an `operator` address that is not `address(0)`.</span></span> <span class="giallo-l"><span>interface IERC4974 /* is ERC165 */ {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev Emits when operator changes.</span></span> <span class="giallo-l"><span> /// MUST emit when `operator` changes by any mechanism.</span></span> <span class="giallo-l"><span> /// MUST ONLY emit by `setOperator`.</span></span> <span class="giallo-l"><span> event NewOperator(address indexed _operator);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev Emits when operator issues a rating. </span></span> <span class="giallo-l"><span> /// MUST emit when rating is assigned by any mechanism.</span></span> <span class="giallo-l"><span> /// MUST ONLY emit by `rate`.</span></span> <span class="giallo-l"><span> event Rating(address _rated, int8 _rating);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev Emits when operator removes a rating. </span></span> <span class="giallo-l"><span> /// MUST emit when rating is removed by any mechanism.</span></span> <span class="giallo-l"><span> /// MUST ONLY emit by `remove`.</span></span> <span class="giallo-l"><span> event Removal(address _removed);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Appoint operator authority.</span></span> <span class="giallo-l"><span> /// @dev MUST throw unless `msg.sender` is `operator`.</span></span> <span class="giallo-l"><span> /// MUST throw if `operator` address is either already current `operator`</span></span> <span class="giallo-l"><span> /// or is the zero address.</span></span> <span class="giallo-l"><span> /// MUST emit an `Appointment` event.</span></span> <span class="giallo-l"><span> /// @param _operator New operator of the smart contract.</span></span> <span class="giallo-l"><span> function setOperator(address _operator) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Rate an address.</span></span> <span class="giallo-l"><span> /// MUST emit a Rating event with each successful call.</span></span> <span class="giallo-l"><span> /// @param _rated Address to be rated.</span></span> <span class="giallo-l"><span> /// @param _rating Total EXP tokens to reallocate.</span></span> <span class="giallo-l"><span> function rate(address _rated, int8 _rating) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Remove a rating from an address.</span></span> <span class="giallo-l"><span> /// MUST emit a Remove event with each successful call.</span></span> <span class="giallo-l"><span> /// @param _removed Address to be removed.</span></span> <span class="giallo-l"><span> function removeRating(address _removed) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @notice Return a rated address&#39; rating.</span></span> <span class="giallo-l"><span> /// @dev MUST register each time `Rating` emits.</span></span> <span class="giallo-l"><span> /// SHOULD throw for queries about the zero address.</span></span> <span class="giallo-l"><span> /// @param _rated An address for whom to query rating.</span></span> <span class="giallo-l"><span> /// @return int8 The rating assigned.</span></span> <span class="giallo-l"><span> function ratingOf(address _rated) external view returns (int8);</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC165 {</span></span> <span class="giallo-l"><span> /// @notice Query if a contract implements an interface.</span></span> <span class="giallo-l"><span> /// @dev Interface identification is specified in EIP-165. This function</span></span> <span class="giallo-l"><span> /// uses less than 30,000 gas.</span></span> <span class="giallo-l"><span> /// @param interfaceID The interface identifier, as specified in EIP-165.</span></span> <span class="giallo-l"><span> /// @return bool `true` if the contract implements `interfaceID` and</span></span> <span class="giallo-l"><span> /// `interfaceID` is not 0xffffffff, `false` otherwise.</span></span> <span class="giallo-l"><span> function supportsInterface(bytes4 interfaceID) external view returns (bool);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="rating-assignment">Rating Assignment</h3> <p>Ratings SHALL be at the sole discretion of the contract operator. This party may be a sports team coach or a multisig DAO wallet. We decide not to specify how governance occurs, but only <em>that</em> governance occurs. This allows for a wider range of potential use cases than optimizing for particular decision-making forms.</p> <p>This proposal standardizes a control mechanism to allocate community reputation without encouraging financialization of that recognition. While it does not ensure meritocracy, it opens the door.</p> <h3 id="choice-of-int8">Choice of int8</h3> <p>It's signed: Reviewers should be able to give neutral and negative ratings for the wallets and contracts they interact with. This is especially important for decentralized applications that may be subject to malicious actors.</p> <p>It's 8bit: The objective here is to keep ratings within some fathomably comparable range. Longer term, this could encourage easy aggregation of ratings, versus using larger numbers where users might employ a great variety of scales.</p> <h3 id="rating-changes">Rating Changes</h3> <p>Ratings SHOULD allow rating updates by contract operators. If Bob has contributed greatly to the community, but then is caught stealing from Alice, the community may decide this should lower Bob's standing and influence in the community. Again, while this does not ensure an ethical standard within the community, it opens the door.</p> <p>Relatedly, ratings SHOULD allow removal of ratings to rescind a rating if the rater does not have confidence in their ability to rate effectively.</p> <h3 id="interface-detection">Interface Detection</h3> <p>We chose Standard Interface Detection (<a href="https://wg-eips.ritovision.com/165/">EIP-165</a>) to expose the interfaces that a compliant smart contract supports.</p> <h3 id="metadata-choices">Metadata Choices</h3> <p>We have required <code>name</code> and <code>description</code> functions in the metadata extension. <code>name</code> common among major standards for blockchain-based primitives. We included a <code>description</code> function that may be helpful for games or other applications with multiple ratings systems.</p> <p>We remind implementation authors that the empty string is a valid response to <code>name</code> and <code>description</code> if you protest to the usage of this mechanism. We also remind everyone that any smart contract can use the same name and description as your contract. How a client may determine which ratings smart contracts are well-known (canonical) is outside the scope of this standard.</p> <h3 id="drawbacks">Drawbacks</h3> <p>One potential drawback of using this standard is that ratings are subjective and may not always accurately reflect the true value or quality of a contract or wallet. However, the standard provides mechanisms for updating and removing ratings, allowing for flexibility and evolution over time.</p> <p>Users identified in the motivation section have a strong need to identify how a contract or community evaluates another. While some users may be proud of ratings they receive, others may rightly or wrongly receive negative ratings from certain contracts. Negative ratings may allow for nefarious activities such as bullying and discrimination. We implore all implementers to be mindful of the consequences of any ratings systems they create with this standard.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>We have adopted the <code>name</code> semantics from the EIP-20 and EIP-721 specifications.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation of this standard can be found in the assets folder.</p> <!-- [./assets/ERC4974.sol](./assets/ERC4974.sol). --> <h2 id="security-considerations">Security Considerations</h2> <p>One potential security concern with this standard is the risk of malicious actors assigning false or misleading ratings to contracts or wallets. This could be used to manipulate voting weights in a DAO, or to deceive users into making poor decisions based on inaccurate ratings.</p> <p>To address this concern, the standard includes mechanisms for updating and removing ratings, allowing for corrections to be made in cases of false or misleading ratings. Additionally, the use of a single operator address to assign and update ratings provides a single point of control, which can be used to enforce rules and regulations around the assignment of ratings.</p> <p>Another potential security concern is the potential for an attacker to gain control of the operator address and use it to manipulate ratings for their own benefit. To mitigate this risk, it is recommended that the operator address be carefully managed and protected, and that multiple parties be involved in its control and oversight.</p> <p>Overall, the security of compliant contracts will depend on the careful management and protection of the operator address, as well as the development of clear rules and regulations around the assignment of ratings.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-03-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Víctor Muñozhttps://github.com/victormunoz Josep Lluis de la Rosahttps://github.com/peplluis7 Easy Innovahttps://github.com/easyinnova https://wg-eips.ritovision.com/4950/

ERC-721 extension with two tokens minted that are tied together

<h2 id="abstract">Abstract</h2> <p>This EIP defines an interface for delegating control of a smart contract wallet to pairs of users using entangled <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> non-fungible tokens.</p> <h2 id="motivation">Motivation</h2> <p>The motivation is to provide an easy way to share a wallet through NFTs, so that the act of buying an NFT (in a marketplace) gives the buyer the privilege to have access to a given wallet. This wallet could have budget in many tokens, or even be the owner of other NFTs.</p> <p>A use case is to keep contact between an artist and an buyer of its NFTs. If an artist T has created a digital piece of art P with an NFT, then T creates 2 entangled tokens A and B so that he keeps A and transfer B to P. By construction of entangled tokens, only one transfer is possible for them, thus the artist proofs he’s been the creator of P by sending a transaction to A that is visible from B. Otherwise, the owner of P might check the authenticity of the artist by sending a transaction to B so that the artist might proof by showing the outcome out of A.</p> <p>A version of this use case is when one user U mints his piece of art directly in the form of an entangled token A; then the user U sells/transfers it while keeping the entangled token B in the U's wallet. The piece of art and the artists will be entangled whoever is the A's owner.</p> <p>These applications of entangled tokens are envisaged to be useful for:</p> <ol> <li>NFT authorship / art creation</li> <li>Distribution of royalties by the creator.</li> <li>Authenticity of a work of art: creation limited to the author (e.g. only 1000 copies if there are 1000 1000 entangled tokens in that NFT).</li> <li>Usowners (users that consume an NFT also become -partial- owners of the NFT)</li> <li>Reformulation of property rights: the one who owns the property receives it without having to follow in the footsteps of the owners.</li> <li>Identity: Only those credentials that have an entangled token with you are related to you.</li> <li>Vreservers (value-reservers).</li> </ol> <h2 id="specification">Specification</h2> <p>An entangled token contract implements <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> with the additional restriction that it only ever mints exactly two tokens at contract deployment: one with a <code>tokenId</code> of <code>0</code>, the other with a <code>tokenId</code> of <code>1</code>. The entangled token contract also implements a smart contract wallet that can be operated by the owners of those two tokens.</p> <p>Also, a <code>tokenTransfer</code> function is to be be added in order to allow the token owners to transact with the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens owned by the contract/NFT itself. The function signature is as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenTransfer</span><span>(</span><span class="z-storage z-type">IERC20</span><span class="z-variable"> token</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> recipient</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyOwners</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>We decide to extend <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> (<a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> could be also possible) because the main purpose of this is to be compatible with current marketplaces platforms. This entangled NFTs will be listed in a marketplace, and the user who buys it will have then the possibility to transact with the wallet properties (fungible and non fungible tokens).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility issues.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Mint two tokens, and only two, at the contract constructor, and set the <code>minted</code> property to true:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bool</span><span class="z-storage z-type"> private</span><span> _minted</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">constructor</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> symbol</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> base_uri</span><span>)</span><span class="z-entity z-name"> ERC721</span><span>(</span><span>name, symbol) </span><span>{</span></span> <span class="giallo-l"><span> baseUri </span><span class="z-keyword">=</span><span> base_uri</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _mint</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _mint</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _minted </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> _mint</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> override</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-keyword">!</span><span>_minted</span><span>,</span><span class="z-string"> &quot;ERC4950: already minted&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_mint</span><span>(</span><span>to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Add additional functions to allow both NFT user owners to operate with other ERC-20 tokens owned by the contract:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlyOwners</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Caller does not own any of the tokens&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> tokenTransfer</span><span>(</span><span class="z-storage z-type">IERC20</span><span class="z-variable"> token</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> recipient</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyOwners</span><span> {</span></span> <span class="giallo-l"><span> token</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>recipient</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>There are no security considerations.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-03-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Víctor Muñozhttps://github.com/victormunoz Josep Lluis de la Rosahttps://github.com/peplluis7 Andres El-Fakdihttps://github.com/Bluezfish https://wg-eips.ritovision.com/4944/

An ERC-721 compatible single-token NFT

<h2 id="abstract">Abstract</h2> <p>The following describes standard functions for an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compatible contract with a total supply of one. This allows an NFT to be associated uniquely with a single contract address.</p> <h2 id="motivation">Motivation</h2> <p>If the ERC-721 was modified to mint only 1 token (per contract), then the contract address could be identified uniquely with that minted token (instead of the tuple contract address + token id, as ERC-721 requires). This change would enable automatically all the capabilities of composable tokens <a href="https://wg-eips.ritovision.com/998/">ERC-998</a> (own other ERC-721 or <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>) natively without adding any extra code, just forbidding to mint more than one token per deployed contract. Then the NFT minted with this contract could operate with his "budget" (the ERC-20 he owned) and also trade with the other NFTs he could own. Just like an autonomous agent, that could decide what to do with his properties (sell his NFTs, buy other NFTs, etc).</p> <p>The first use case that is devised is for value preservation. Digital assets, as NFTs, have value that has to be preserved in order to not be lost. If the asset has its own budget (in other ERC-20 coins), could use it to autopreserve itself.</p> <h2 id="specification">Specification</h2> <p>The constructor should mint the unique token of the contract, and then the mint function should add a restriction to avoid further minting.</p> <p>Also, a <code>tokenTransfer</code> function should be added in order to allow the contract owner to transact with the ERC-20 tokens owned by the contract/NFT itself. So that if the contract receives a transfer of ERC-20 tokens, the owner of the NFT could spend it from the contract wallet.</p> <h2 id="rationale">Rationale</h2> <p>The main motivation is to keep the contract compatible with current ERC-721 platforms.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backwards compatibility issues.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Add the variable <code>_minted</code> in the contract:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support"> bool</span><span class="z-storage z-type"> private</span><span> _minted</span><span>;</span></span></code></pre> <p>In the constructor, automint the first token and set the variable to true:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> symbol</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> base_uri</span><span>)</span><span class="z-entity z-name"> ERC721</span><span>(</span><span>name, symbol) </span><span>{</span></span> <span class="giallo-l"><span> baseUri </span><span class="z-keyword">=</span><span> base_uri</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> mint</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _minted </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>Add additional functions to interact with the NFT properties (for instance, ERC-20):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlyOwner</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;Caller is not the owner of the NFT&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferTokens</span><span>(</span><span class="z-storage z-type">IERC20</span><span class="z-variable"> token</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> recipient</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span> token</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>recipient</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceTokens</span><span>(</span><span class="z-storage z-type">IERC20</span><span class="z-variable"> token</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> token</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>No security issues found.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-03-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Harikrishnan Mulackalhttps://github.com/hrkrshnn Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast https://wg-eips.ritovision.com/5000/

Introduce a new instruction to perform x * y / z in 512-bit precision

<h2 id="abstract">Abstract</h2> <p>Introduce a new instruction, <code>MULDIV(x, y, z)</code>, to perform <code>((x * y) / z) % 2**256</code> in 512-bit precision. <code>z = 0</code> is a special case for <code>(x * y) / 2**256</code>.</p> <h2 id="motivation">Motivation</h2> <p>Fixed point operations in high level languages are very commonly used on Ethereum, especially in the domain of financial applications.</p> <p>While fixed point addition and subtraction can be done with merely <code>add</code> and <code>sub</code> respectively, being able to efficiently do fixedpoint multiplication and division is a very sought after feature. A commonly used workaround relies on a <code>mulmod</code>-based, rather complex implementation (taking around 50 instructions, excluding stack manipulation). This instruction reduces that to a single opcode.</p> <p>A secondary use case is likely in cryptographic applications, where the <code>muldiv</code> instruction allows full precision 256x256-&gt;512 multiplication. <code>mul(x y)</code> (or <code>muldiv(x, y, 1)</code>) computes the lower order 256 bits and <code>muldiv(x, y, 0)</code> computes the higher order 256 bits.</p> <p>Finally we aimed to provide an instruction which can be efficiently used both in <em>checked</em> and <em>unchecked arithmetic</em> use cases. By <em>checked</em> we mean to abort on conditions including division-by-zero and wrapping behaviour.</p> <h2 id="specification">Specification</h2> <p>A new instruction is introduced: <code>MULDIV</code> (<code>0x1e</code>).</p> <ul> <li>Pops 3 values from the stack, first <code>x</code>, then <code>y</code> and <code>z</code>.</li> <li>If <code>z == 0</code>, <code>r = (uint512(x) * y) / 2**256</code>.</li> <li>Otherwise <code>r = (uint512(x) * y / z) % 2**256</code>, where the intermediate calculation is performed with 512-bit precision.</li> <li>Pushes <code>r</code> on the stack.</li> </ul> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> operations `*` and `//` are done in 512 bit precision</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> muldiv</span><span>(</span><span class="z-variable z-parameter z-function">x</span><span>,</span><span class="z-variable z-parameter z-function"> y</span><span>,</span><span class="z-variable z-parameter z-function"> z</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> z</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>x</span><span class="z-keyword"> *</span><span> y</span><span>)</span><span class="z-keyword"> //</span><span> (</span><span class="z-constant">2</span><span class="z-keyword">**</span><span class="z-constant">256</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>(</span><span>x</span><span class="z-keyword"> *</span><span> y</span><span>)</span><span class="z-keyword"> //</span><span> z</span><span>)</span><span class="z-keyword"> %</span><span> (</span><span class="z-constant">2</span><span class="z-keyword">**</span><span class="z-constant">256</span><span>)</span></span></code></pre> <p>The cost of the instruction is 8 gas (aka <code>mid</code>), the same as for <code>addmod</code> and <code>mulmod</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="the-special-0-case">The special 0 case</h3> <p>All the arithmetic instructions in EVM handle division or modulo 0 specially: the instructions return 0. We have decided to break consistency in order to provide a flexible opcode, which can be used to detect wrapping behaviour.</p> <p>Alternate options include:</p> <ul> <li>Returning a flag for wrapping</li> <li>Returning two stack items, higher and lower order bits</li> <li>Compute the higher order 256 bits in EVM:</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Returns `hi` such that `x × y = hi × 2**256 + mul(x, y)`</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> hob</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> x</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> y</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> hi</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> uint_max </span><span class="z-keyword">=</span><span class="z-variable z-language"> type</span><span>(</span><span class="z-support">uint</span><span>)</span><span>.</span><span>max</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> lo </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mul</span><span>(</span><span>x</span><span>,</span><span> y</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> mm </span><span class="z-keyword">:=</span><span class="z-support"> mulmod</span><span>(</span><span>x</span><span>,</span><span> y</span><span>,</span><span> uint_max</span><span>)</span></span> <span class="giallo-l"><span> hi </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sub</span><span>(</span><span class="z-entity z-name">sub</span><span>(</span><span>mm</span><span>,</span><span> lo</span><span>)</span><span>,</span><span class="z-entity z-name"> lt</span><span>(</span><span>mm</span><span>,</span><span> lo</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>While this feature is clever and useful, callers must be aware that unlike other EVM instructions, passing 0 will have a vastly different behaviour.</p> <h3 id="argument-ordering">Argument ordering</h3> <p>The order of arguments matches <code>addmod</code> and <code>mulmod</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a new instruction not present prior.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>MULDIV</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>PUSH 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</span></span> <span class="giallo-l"><span>MULDIV</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0x0000000000000000000000000000000000000000000000000de0b6b3a7640000</span></span> <span class="giallo-l"><span>PUSH 0x000000000000000000000000000000000000000000000000016345785d8a0000</span></span> <span class="giallo-l"><span>PUSH 0x00000000000000000000000000000000000000000000d3c21bcecceda1000000</span></span> <span class="giallo-l"><span>MULDIV</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>0x00000000000000000000000000000000000000000000152d02c7e14af6800000</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>TBA</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-03-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gavin Johnhttps://github.com/Pandapip1 Zainan Victor Zhouhttps://github.com/xinbenlv Sam Wilsonhttps://github.com/SamWilsn Jochem Brouwerhttps://github.com/jochem-brouwer Charles Cooperhttps://github.com/charles-cooper https://wg-eips.ritovision.com/5920/

Introduces a new opcode, PAY, to send ether to an address without calling any of its functions

<h2 id="abstract">Abstract</h2> <p>This EIP introduces a new opcode, <code>PAY</code>, taking two stack parameters, <code>addr</code> and <code>val</code>, that transfers <code>val</code> wei to the address <code>addr</code> without calling any of its functions.</p> <h2 id="motivation">Motivation</h2> <p>Currently, to send ether to an address requires you to call into that address, which transfers execution context to that address, which creates several issues:</p> <ul> <li>First of all, it opens a reentrancy attack vector, as the recipient can call back into the sender. More generally, the recipient can unilaterally execute arbitrary state changes, limited only by the gas forwarded, which is not desirable from the point of view of the sender. <ul> <li>In practice, when calling into another account and sending ether, 2300 gas (the "gas stipend") is always available "for free" in the newly created call frame. Although it is currently not possible to make storage state changes with the 2300 gas stipend (see the last minute rejection of <a href="https://wg-eips.ritovision.com/1283/">EIP-1283</a> from Constantinople to be replaced with the "gas stipend safe" <a href="https://wg-eips.ritovision.com/2200/">EIP-2200</a> version in Istanbul), it is possible to do this with transient storage (<a href="https://wg-eips.ritovision.com/1153/">EIP-1153</a>). This is a security risk where potentially the transient storage gets changed unintentionally. The goal is to send ether, and not have to consider these potential unintuitive security problems.</li> </ul> </li> <li>Secondly, it opens a DoS vector. Contracts wanting to send ether must be cognizant of the possibility that the recipient will run out of gas or revert.</li> <li>Future potential call-like opcodes may not provide a way to restrict the amount of gas being forwarded to the recipient, so the meager mitigation against unintended side effects in use today (gas limit) is not guaranteed to be available.</li> <li>The <code>CALL</code> and <code>EXTCALL</code> opcodes will execute code on the recipient, which is unintended when wanting to send ether and which could lead to unintentional operations. The code execution also has to be paid for in gas, even when the intention is to only send ether, which is thus an unnecessary waste of gas.</li> <li>Finally, <a href="https://wg-eips.ritovision.com/7702/">EIP-7702</a> allows to delegate externally owned accounts (EOAs) to other accounts, which breaks the invariant that EOAs cannot contain code. Therefore, calling such EOA with the intention to send ether will thus also execute code and cost unnecessary gas.</li> </ul> <p>Having a dedicated opcode for ether transfers solves all of these issues, and would be a useful addition to the EVM.</p> <h2 id="specification">Specification</h2> <h3 id="constants">Constants</h3> <table><thead><tr><th>Constant</th><th>Definition</th></tr></thead><tbody> <tr><td><code>WARM_STORAGE_READ_COST</code></td><td><a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a></td></tr> <tr><td><code>COLD_ACCOUNT_ACCESS_COST</code></td><td><a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a></td></tr> <tr><td><code>GAS_NEW_ACCOUNT</code></td><td><a rel="external" href="https://github.com/ethereum/execution-specs/blob/4d953035fb0cceda7cf21d71b2ab7a9a6f4632f0/src/ethereum/frontier/vm/gas.py#L52">EELS</a></td></tr> <tr><td><code>GAS_CALL_VALUE</code></td><td><a rel="external" href="https://github.com/ethereum/execution-specs/blob/4d953035fb0cceda7cf21d71b2ab7a9a6f4632f0/src/ethereum/frontier/vm/gas.py#L53">EELS</a></td></tr> </tbody></table> <h3 id="behavior">Behavior</h3> <p>A new opcode is introduced: <code>PAY</code> (<code>0xfc</code>), which:</p> <ul> <li>Halt with exceptional failure if the current frame is static, as defined in <a href="https://wg-eips.ritovision.com/214/">EIP-214</a>.</li> <li>Pops two values from the stack: <code>addr</code> then <code>val</code>.</li> <li>Exceptionally halts if <code>addr</code> has any of the high 12 bytes set to a non-zero value (i.e. it does not contain a 20-byte address).</li> <li>Charges the gas cost detailed below.</li> <li>Marks <code>addr</code> as warm (adding <code>addr</code> to <code>accessed_addresses</code>).</li> <li>Transfers <code>val</code> wei from the current address to the address <code>addr</code>, only if the current address has a balance greater than or equal to <code>val</code>.</li> <li>Push <code>1</code> on the stack if the <code>PAY</code> operation was successful, or <code>0</code> if it failed. <ul> <li>Currently only insufficient balance would produce a <code>0</code> return value.</li> </ul> </li> </ul> <h3 id="gas-cost">Gas Cost</h3> <p>The gas cost for <code>PAY</code> is the sum of the following:</p> <ul> <li>Is <code>addr</code> in <code>accessed_addresses</code>? <ul> <li>If yes, <code>WARM_STORAGE_READ_COST</code>;</li> <li>Otherwise, <code>COLD_ACCOUNT_ACCESS_COST</code>.</li> </ul> </li> <li>Does <code>addr</code> exist or is <code>val</code> zero? <ul> <li>If yes to either, zero;</li> <li>Otherwise, <code>GAS_NEW_ACCOUNT</code>.</li> </ul> </li> <li>Is <code>val</code> zero? <ul> <li>If yes, zero;</li> <li>Otherwise, <code>GAS_CALL_VALUE</code>.</li> </ul> </li> </ul> <p><code>PAY</code> cannot be implemented on networks with empty accounts (see <a href="https://wg-eips.ritovision.com/7523/">EIP-7523</a>).</p> <h2 id="rationale">Rationale</h2> <h3 id="argument-order">Argument order</h3> <p>The order of arguments mimics that of <code>CALL</code>, which pops <code>addr</code> before <code>val</code>. Beyond consistency, though, this ordering aids validators pattern-matching MEV opportunities, so <code>PAY</code> always appears immediately after <code>COINBASE</code>.</p> <h3 id="halting-for-invalid-address">Halting for invalid address</h3> <p>The halting behavior is designed to allow for Address Space Extension. If the high bytes were truncated, as in <code>CALL</code>, contracts could depend on the truncating behavior. If the address space were extended beyond 20 bytes, <code>PAY</code> would either not be able to target those accounts, or code expecting truncation could send ether to the wrong address.</p> <p>Because this behavior may be changed, contracts should not rely on this halting behavior and use methods designated to intentionally halt (such as the <a href="https://wg-eips.ritovision.com/141/"><code>INVALID</code></a> opcode).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change requires a hard fork.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Existing contracts should not rely on their balance being under their control, since it is already possible to send ether to an address without calling it, by using the <code>SELFDESTRUCT</code> opcode (somewhat restricted in <a href="https://wg-eips.ritovision.com/6780/">EIP-6780</a>). It is also possible to involuntarily fund an account with priority fees sent to a <code>block.coinbase</code>. However, this opcode does make this process cheaper and easier. It thus does not break an invariant.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-03-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jules Laihttps://github.com/julesl23 https://wg-eips.ritovision.com/4885/

An interface for subscription tokens that gives holders subscriptions to NFTs and multi tokens

<h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for subscribing to non-fungible and multi tokens. <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> tokens are deposited in exchange for subscription tokens that give the right to use said non-fungible and multi tokens for a specified time limited or unlimited period.</p> <h2 id="motivation">Motivation</h2> <p>This standard offers a flexible, general purpose way to subscribe to the use of assets or services offered by <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> or <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> contracts. From here on in, for the sake of simplicity, these contracts will be known as NFTs; the provider is the issuer of said NFTs and the subscriber(s) uses them.</p> <p>This proposal was originally conceived from the want to give creators of music and film, back control. The distribution and delivery of digital content is currently the purview of centralised tech corporations who offer homogeneous subscription models to their customers. This proposal specifies a standard for dapp developers to give creators the ability to set their own custom subscription models and hence, open up new revenue streams that can lead to decentralised distribution and delivery models.</p> <p>Use cases include any sort of periodic (e.g. daily, weekly, monthly, quarterly, yearly/annual, or seasonal) use of or access to assets or services such as:</p> <ul> <li>Subscriptions for streaming music, video, e-learning or book/news services</li> <li>Sharing of digital assets among subscribers</li> <li>Club memberships such as health clubs</li> <li>Season tickets for sports and e-sports</li> <li>Agreement between parties to exchange fixed rate subscription stream with variable income in DeFi</li> <li>Renting in-game assets</li> <li>Etc.</li> </ul> <p>The subscription token borrows a few functions from the EIP-20 specification. An implementer is free to implement the rest of the standard; allowing for example subscription tokens to be transferred in secondary markets, sent as gifts or for refunds etc.</p> <h2 id="specification">Specification</h2> <p>The subscriber deposits EIP-20 to receive an NFT and subscription. Subscription tokens balance automatically decreases linearly over the lifetime of usage of the NFT, and use of the NFT is disabled once the subscription token balance falls to zero. The subscriber can top up the balance to extend the lifetime of the subscription by depositing EIP-20 tokens in exchange for more subscription tokens.</p> <p>Smart contracts implementing this EIP standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> supportsInterface function and MUST return the constant value true if 0xC1A48422 is passed through the interfaceID argument. Note that revert in this document MAY mean a require, throw (not recommended as depreciated) or revert solidity statement with or without error messages.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ISubscriptionToken</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when the subscription token constructor or initialize method is</span></span> <span class="giallo-l"><span class="z-comment"> executed.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> name</span><span class="z-comment"> The name of the subscription token</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> symbol</span><span class="z-comment"> The symbol of the subscription token</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> provider</span><span class="z-comment"> The provider of the subscription whom receives the deposits</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subscriptionToken</span><span class="z-comment"> The subscription token contract address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> baseToken</span><span class="z-comment"> The ERC-20 compatible token to use for the deposits.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> nft</span><span class="z-comment"> Address of the `nft` contract that the provider mints/transfers from.</span></span> <span class="giallo-l"><span class="z-comment"> All tokenIds referred to in this interface MUST be token instances of this `nft` contract.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> InitializeSubscriptionToken</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> name</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> symbol</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> provider</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> subscriptionToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> baseToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> nft</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> uri</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits for every new subscriber to `nft` contract of token `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> `subscriber` MUST have received `nft` of token `tokenId` in their account.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subscriber</span><span class="z-comment"> The subscriber account</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> MUST be token id of `nft` sent to `subscriber`</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> uri</span><span class="z-comment"> MUST be uri of the `nft` that was sent to `subscriber` or empty string</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SubscribeToNFT</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> subscriber</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> uri</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emits when `subscriber` deposits ERC-20 of token type `baseToken` via the `deposit method.</span></span> <span class="giallo-l"><span class="z-comment"> This tops up `subscriber` balance of subscription tokens</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> depositAmount</span><span class="z-comment"> The amount of ERC-20 of type `baseToken` deposited</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subscriptionTokenAmount</span><span class="z-comment"> The amount of subscription tokens sent in exchange to `subscriber`</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subscriptionPeriod</span><span class="z-comment"> Amount of additional time in seconds subscription is extended</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Deposit</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> subscriber</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> depositAmount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subscriptionTokenAmount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subscriptionPeriod</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> name of the subscription token</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> name</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> symbol of the subscription token</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> symbol</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Subscribes `subscriber` to `nft` of &#39;tokenId&#39;. `subscriber` MUST receive `nft`</span></span> <span class="giallo-l"><span class="z-comment"> of token `tokenId` in their account.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if `subscriber` is already subscribed to `nft` of &#39;tokenId&#39;</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if &#39;nft&#39; has not approved the `subscriptionToken` contract address as operator.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subscriber</span><span class="z-comment"> The subscriber account. MUST revert if zero address.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> MUST be token id of `nft` contract sent to `subscriber`</span></span> <span class="giallo-l"><span class="z-comment"> `tokenId` emitted from event `SubscribeToNFT` MUST be the same as tokenId except when</span></span> <span class="giallo-l"><span class="z-comment"> tokenId is zero; allows OPTIONAL tokenid that is then set internally and minted by</span></span> <span class="giallo-l"><span class="z-comment"> `nft` contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> uri</span><span class="z-comment"> The OPTIONAL uri of the `nft`.</span></span> <span class="giallo-l"><span class="z-comment"> `uri` emitted from event `SubscribeToNFT` MUST be the same as uri except when uri is empty.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> subscribeToNFT</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> subscriber</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> uri</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Top up balance of subscription tokens held by `subscriber`</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if `subscriber` is not subscribed to `nft` of &#39;tokenId&#39;</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if &#39;nft&#39; has not approved the `subscriptionToken` contract address as operator.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> subscriber</span><span class="z-comment"> The subscriber account. MUST revert if zero address.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The token id of `nft` contract to subscribe to</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> depositAmount</span><span class="z-comment"> The amount of ERC-20 token of contract address `baseToken` to deposit</span></span> <span class="giallo-l"><span class="z-comment"> in exchange for subscription tokens of contract address `subscriptionToken`</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deposit</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> subscriber</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> depositAmount</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> balance of subscription tokens held by `subscriber`.</span></span> <span class="giallo-l"><span class="z-comment"> RECOMMENDED that the balance decreases linearly to zero for time limited subscriptions</span></span> <span class="giallo-l"><span class="z-comment"> RECOMMENDED that the balance remains the same for life long subscriptions</span></span> <span class="giallo-l"><span class="z-comment"> MUST return zero balance if the `subscriber` does not hold `nft` of &#39;tokenId&#39;</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if subscription has not yet started via the `deposit` function</span></span> <span class="giallo-l"><span class="z-comment"> When the balance is zero, the use of `nft` of `tokenId` MUST NOT be allowed for `subscriber`</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> subscriber</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="subscription-token-balances">Subscription token balances</h3> <p>An example implementation mints an amount of subscription token that totals to one subscription token per day of the subscription period length paid for by the subscriber; for example a week would be for seven subscription tokens. The subscription token balance then decreases automatically at a rate of one token per day continuously and linearly over time until zero. The <code>balanceOf</code> function can be implemented lazily by calculating the amount of subscription tokens left only when it is called as a view function, thus has no gas cost.</p> <h3 id="subscription-token-price">Subscription token price</h3> <p>Subscription token price paid per token per second can be calculated from the <code>Deposit</code> event parameters as <code>depositAmount</code> / (<code>subscriptionTokenAmount</code> * <code>subscriptionPeriod</code>)</p> <h3 id="nft-metadata">NFT metadata</h3> <p>The NFT's metadata can store information of the asset/service offered to the subscriber by the provider for the duration of the subscription. This MAY be the terms and conditions of the agreed subscription service offered by the provider to the subscriber. It MAY also be the metadata of the NFT asset if this is offered directly. This standard is kept purposely general to cater for many different use cases of NFTs.</p> <h3 id="subscription-expiry">Subscription expiry</h3> <p>When the subscription token balance falls to zero for a subscriber (signifying that the subscription has expired) then it is up to the implementer on how to handle this for their particular use case. For example, a provider may stop streaming media service to a subscriber. For an NFT that represents an image stored off-chain, perhaps the NFT's <code>uri</code> function no longer returns back a link to its metadata.</p> <h3 id="caveats">Caveats</h3> <p>With some traditional subscription models based on fiat currencies, the subscribers' saved payment credentials are used to automatically purchase to extend the subscription period, at or just before expiry. This feature is not possible in this proposal specification as recurring payments will have to have allowance approved for signed by a subscriber for each payment when using purely cryptocurrencies.</p> <p>This proposal does not deal with pausing subscriptions directly, implementers can write their own or inherit off 3rd party smart contract abstractions such as OpenZeppelin's Pausable. In that case, <code>balanceOf</code> method would need extra logic and storage to account for the length of time the subscription tokens were paused.</p> <h2 id="rationale">Rationale</h2> <h3 id="tokenisation-of-subscriptions">Tokenisation of subscriptions</h3> <p>The subscription itself has value when it is exchanged for a deposit. This proposal enables subscriptions to be 'tokenised' thus secondary markets can exist where the subscription tokens can be bought and sold. For example, a fan might want to sell their season ticket, that gives access to live sporting events, on to another fan. This would not be as easily possible if there was only a date expiry extension feature added to NFTs. An implementer can simply implement the rest of the EIP-20 functions for subscription tokens to be traded. It is left to the implementer to decide if the subscription service offered is non-fungible or fungible. If non-fungible then buying the subscription tokens would simply give the same period left to expiration. If fungible and the purchaser already had an existing subscription for the same service then their total subscription period can be extended by the amount of subscription tokens bought.</p> <h3 id="cater-for-current-and-future-uses-of-nfts">Cater for current and future uses of NFTs</h3> <p>This proposal purposely keeps <code>tokenId</code> and <code>uri</code> optional in the <code>subcribeToNFT</code> method to keep the specification general purpose. Some use cases such as pre-computed image NFT collections don't require a different 'uri', just a different <code>tokenId</code> for each NFT. However, in other use cases such as those that require legal contracts between both parties, individual <code>uri</code> links are probably required as the NFT's metadata may require information from both parties to be stored on immutable storage.</p> <h3 id="giving-back-users-control">Giving back users control</h3> <p>Traditional subscription models, particularly with streaming services, control of the subscription model is totally with that of the central service provider. This proposal gives decentralised services a standard way to give control back to their users. Hence each user is able to develop their own subscription eco system and administer it towards one that suits theirs and their subscribers' needs.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>A subscription token contract can be fully compatible with EIP-20 specification to allow, for example, transfers from one subscriber to another subscriber or user. EIP-20 methods <code>name</code>, <code>symbol</code> and <code>balanceOf</code> are already part of the specification of this proposal, and it is left to the implementer to choose whether to implement the rest of EIP-20's interface by considering their own use case.</p> <p>Use of subscription tokens is in effect an indirect way to control the lifetime of an NFT. As such it is assumed that this arrangement would work best when the NFTs and subscription token contracts subscribing to the NFTs, are deployed by the same platform or decentralised app. It MUST NOT have an impact or dependencies to existing NFTs that have not approved the subscription token as an operator. Indeed in this case, any other parties wouldn't be aware of and any NFT lifetime dependencies will be ignored, hence should not work anyway. To this end, this proposal specifies that the 'nft' MUST have approved the <code>subscriptionToken</code> contract address as operator.</p> <h2 id="security-considerations">Security Considerations</h2> <p>It is normal for service providers to receive subscriber payments upfront before the subscriber gets to use the service. Indeed this proposal via the <code>deposit</code> method follows this remit. It would therefore be possible that a service provider sets up, receives the deposits and then does not provide or provides the service poorly to its subscribers. This happens in the traditional world too and this proposal does not cover how to resolve this.</p> <p>The <code>subscribeToNFT</code> method takes a parameter <code>uri</code> link to the <code>nft</code> metadata. It is possible if stored on centralised storage that the owners can change the metadata, or perhaps the metadata is hacked which is an issue with vanilla NFT contracts too. But because the <code>uri</code> is provided at the time of subscription rather then deployment, it is RECOMMENDED that where the use case requires, implementers ensure that the <code>uri</code> link is to immutable storage.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-02-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Stokeshttps://github.com/ralexstokes Danny Ryanhttps://github.com/djrtwo https://wg-eips.ritovision.com/4863/

Support validator withdrawals from the beacon chain to the EVM via a new "push-style" transaction type.

<h2 id="abstract">Abstract</h2> <p>Introduce a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718 transaction type</a> to support validator withdrawals that are "pushed" from the beacon chain to the EVM.</p> <p>Add block validations to ensure the withdrawal transactions are sound with respect to withdrawal processing on the beacon chain.</p> <h2 id="motivation">Motivation</h2> <p>This EIP provides a way for validator withdrawals made on the beacon chain to enter into the EVM. The architecture is "push"-based, rather than "pull"-based, where withdrawals are required to be processed in the execution block as soon as they are dequeued from the beacon chain.</p> <p>This approach is more involved than "pull"-based alternatives (e.g. <a href="https://wg-eips.ritovision.com/4788/">EIP-4788</a> + user-space withdrawal contract) with respect to the core protocol (by providing a new transaction type with special semantics) but does provide tighter integration of a critical feature into the protocol itself.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>constants</th><th>value</th><th>units</th></tr></thead><tbody> <tr><td><code>FORK_TIMESTAMP</code></td><td>TBD</td><td></td></tr> <tr><td><code>WITHDRAWAL_TX_TYPE</code></td><td><code>0x3</code></td><td>byte</td></tr> </tbody></table> <p>Beginning with the execution timestamp <code>FORK_TIMESTAMP</code>, execution clients <strong>MUST</strong> introduce the following extensions to transaction processing and block validation:</p> <h3 id="new-transaction-type">New transaction type</h3> <p>Define a new <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> transaction type with <code>TransactionType</code> <code>WITHDRAWAL_TX_TYPE</code>.</p> <p>The <code>TransactionPayload</code> is an RLP-encoded list <code>RLP([index, address, amount])</code> where the <code>index</code> is a 64-bit value uniquely labeling a specific withdrawal, the <code>address</code> refers to an execution layer account and the <code>amount</code> refers to an ether value given in units of wei.</p> <p>These values are provided by the consensus layer.</p> <h3 id="block-validity">Block validity</h3> <p>If a block contains <em>any</em> transactions with <code>WITHDRAWAL_TX_TYPE</code> type, they <strong>MUST</strong> come after <strong>ALL</strong> other transactions in the block.</p> <p>If the execution client receives a block where this is not the case, it <strong>MUST</strong> consider the block invalid.</p> <h3 id="transaction-processing">Transaction processing</h3> <p>When processing a transaction with <code>WITHDRAWAL_TX_TYPE</code> type, the implementation should increase the balance of the <code>address</code> specified by the <code>WithdrawalTransaction</code> by the <code>amount</code> of wei specified.</p> <p>This balance change is unconditional and <strong>MUST</strong> not fail.</p> <p>This transaction type has no associated gas costs.</p> <p>TODO: add logs?</p> <h2 id="rationale">Rationale</h2> <h3 id="push-vs-pull-approach">Push vs pull approach</h3> <p>This push approach gives validators a small subsidy with respect to processing, in lieu of needing to buy gas via normal EVM processing that would be required for a pull-based approach.</p> <p>This style also happens automatically when the requisite conditions are met on the beacon chain which is nicer UX for validators.</p> <h3 id="why-a-new-transaction-type">Why a new transaction type?</h3> <p>This EIP suggests a new transaction type as it has special semantics different from other existing types of EVM transactions.</p> <p>An entirely new transaction type firewalls off generic EVM execution from this type of processing to simplify testing and security review of withdrawals.</p> <h3 id="why-no-gas-costs-for-new-transaction-type">Why no (gas) costs for new transaction type?</h3> <p>The maximum number of this transaction type that can reach the execution layer at a given time is bounded (enforced by the consensus layer) and this limit is kept small so that any execution layer operational costs are negligible in the context of the broader block execution.</p> <h3 id="why-only-balance-updates-no-general-evm-execution">Why only balance updates? No general EVM execution?</h3> <p>More general processing introduces the risk of failures, which complicates accounting on the beacon chain.</p> <p>This EIP suggests a route for withdrawals that provides most of the benefits for a minimum of the (complexity) cost.</p> <h3 id="why-new-block-validations">Why new block validations?</h3> <p>The beacon chain must be able to efficiently validate that the withdrawal transactions in a given execution block are the ones expected based on its own internal scheduling logic to maintain the soundness of the withdrawal mechanism.</p> <p>By requiring all withdrawal transactions to be at the back of every block where they are applicable, the algorithm to check consistency becomes a straightforward linear walk from the start of the set until a known, bounded (small) number.</p> <p>Having a simple ordering scheme like this facilitates optimizations clients may do with respect to withdrawal processing, which would be hampered if withdrawal transactions could be placed in the block freely.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No issues.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Consensus-layer validation of withdrawal transactions is critical to ensure that the proper amount of ETH is withdrawn back into the execution layer. This consensus-layer to execution-layer ETH transfer does not have a current analog in the EVM and thus deserves very high security scrutiny.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-02-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 David Buckmanhttps://github.com/davidbuckman Isaac Buckmanhttps://github.com/isaacbuckman https://wg-eips.ritovision.com/4799/

A standardized interface for designating ownership of an NFT

<h2 id="abstract">Abstract</h2> <p>The following defines a standard interface for designating ownership of an NFT to someone while the NFT is held in escrow by a smart contract. The standard allows for the construction of a directed acyclic graph of NFTs, where the designated owner of every NFT in a given chain is the terminal address of that chain. This enables the introduction of additional functionality to pre-existing NFTs, without having to give up the authenticity of the original. In effect, this means that all NFTs are composable and can be rented, used as collateral, fractionalized, and more.</p> <h2 id="motivation">Motivation</h2> <p>Many NFTs aim to provide their holders with some utility - utility that can come in many forms. This can be the right to inhabit an apartment, access to tickets to an event, an airdrop of tokens, or one of the infinitely many other potential applications. However, in their current form, NFTs are limited by the fact that the only verifiable wallet associated with an NFT is the owner, so clients that want to distribute utility are forced to do so to an NFT's listed owner. This means that any complex ownership agreements must be encoded into the original NFT contract - there is no mechanism by which an owner can link the authenticity of their original NFT to any external contract.</p> <p>The goal of this standard is to allow users and developers the ability to define arbitrarily complex ownership agreements on NFTs that have already been minted. This way, new contracts with innovative ownership structures can be deployed, but they can still leverage the authenticity afforded by established NFT contracts - in the past a wrapping contract meant brand new NFTs with no established authenticity.</p> <p>Prior to this standard, wrapping an NFT inside another contract was the only way to add functionality after the NFT contract had been deployed, but this meant losing access to the utility of holding the original NFT. Any application querying for the owner of that NFT would determine the wrapping smart contract to be the owner. Using this standard, applications will have a standardized method of interacting with wrapping contracts so that they can continue to direct their utility to users even when the NFT has been wrapped.</p> <h2 id="specification">Specification</h2> <p>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> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/introspection/IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4799NFT</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when ownership of any NFT changes by any mechanism.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This event emits when NFTs are created (`from` == 0) and destroyed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (`to` == 0). Exception: during contract creation, any number of NFTs</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> may be created and assigned without emitting Transfer. At the time of</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> any transfer, the approved address for that NFT (if any) is reset to none.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Find the owner of an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> NFTs assigned to zero address are considered invalid, and queries</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> about them throw</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The identifier for an NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> address of the owner of the NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-4799 Non-Fungible Token Ownership Designation Standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See https://eips.ethereum.org/EIPS/eip-4799</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is [</span><span class="z-keyword">TODO</span><span class="z-comment">].</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/introspection/IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4799NFT.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4799</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emitted when a source token designates its ownership to the owner of the target token</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OwnershipDesignation</span><span>(</span></span> <span class="giallo-l"><span class="z-variable"> IERC4799NFT</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> sourceContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> sourceTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> IERC4799NFT</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> targetContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> targetTokenId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Find the designated NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sourceContract</span><span class="z-comment"> The contract address of the source NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sourceTokenId</span><span class="z-comment"> The tokenId of the source NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-comment"> (targetContract, targetTokenId) contract address and tokenId of the parent NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> designatedTokenOf</span><span>(</span><span class="z-storage z-type">IERC4799NFT</span><span class="z-variable"> sourceContract</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> sourceTokenId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">IERC4799NFT</span><span>,</span><span class="z-support"> uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The authenticity of designated ownership of an NFT is conferred by the designating ERC-4799 contract’s ownership of the original NFT according to the source contract. This MUST be verified by clients by querying the source contract.</p> <p>Clients respecting this specification SHALL NOT distribute any utility to the address of the ERC-4799 contract. Instead, they MUST distribute it to the owner of the designated token that the ERC-4799 contract points them to.</p> <h2 id="rationale">Rationale</h2> <p>To maximize the future compatibility of the wrapping contract, we first defined a canonical NFT interface. We created <code>IERC4799NFT</code>, an interface implicitly implemented by virtually all popular NFT contracts, including all deployed contracts that are <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> compliant. This interface represents the essence of an NFT: a mapping from a token identifier to the address of a singular owner, represented by the function <code>ownerOf</code>.</p> <p>The core of our proposal is the <code>IERC4799</code> interface, an interface for a standard NFT ownership designation contract (ODC). ERC4799 requires the implementation of a <code>designatedTokenOf</code> function, which maps a source NFT to exactly one target NFT. Through this function, the ODC expresses its belief of designated ownership. This designated ownership is only authentic if the ODC is listed as the owner of the original NFT, thus maintaining the invariant that every NFT has exactly one designated owner.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The <code>IERC4799NFT</code> interface is backwards compatible with <code>IERC721</code>, as <code>IERC721</code> implicitly extends <code>IERC4799NFT</code>. This means that the ERC-4799 standard, which wraps NFTs that implement <code>ERC4799NFT</code>, is fully backwards compatible with ERC-721.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.8.0</span><span class="z-keyword"> &lt;</span><span class="z-constant">0.9</span><span>.</span><span class="z-constant">0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4799.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4799NFT.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC721/IERC721Receiver.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC721Composable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC4799</span><span>, </span><span class="z-entity z-name">IERC721Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span>IERC4799NFT </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span> IERC4799NFT</span><span>)</span><span>)</span><span class="z-storage z-type"> private</span><span> _targetContracts</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span>IERC4799NFT </span><span class="z-keyword">=&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span>)</span><span class="z-storage z-type"> private</span><span> _targetTokenIds</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> designatedTokenOf</span><span>(</span><span class="z-storage z-type">IERC4799NFT</span><span class="z-variable"> sourceContract</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> sourceTokenId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-storage z-type"> override</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">IERC4799NFT</span><span>,</span><span class="z-support"> uint256</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC4799NFT</span><span>(</span><span>_targetContracts</span><span>[</span><span>sourceContract</span><span>]</span><span>[</span><span>sourceTokenId</span><span>]</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> _targetTokenIds</span><span>[</span><span>sourceContract</span><span>]</span><span>[</span><span>sourceTokenId</span><span>]</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> designateToken</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC4799NFT</span><span class="z-variable"> sourceContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> sourceTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC4799NFT</span><span class="z-variable"> targetContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> targetTokenId</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC721</span><span>(</span><span class="z-support">address</span><span>(</span><span>sourceContract</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>sourceTokenId</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span class="z-keyword"> ||</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC721</span><span>(</span><span class="z-support">address</span><span>(</span><span>sourceContract</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">getApproved</span><span>(</span><span>sourceTokenId</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-string"> &quot;ERC721Composable: Only owner or approved address can set a designate ownership&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _targetContracts</span><span>[</span><span>sourceContract</span><span>]</span><span>[</span><span>sourceTokenId</span><span>]</span><span class="z-keyword"> =</span><span> targetContract</span><span>;</span></span> <span class="giallo-l"><span> _targetTokenIds</span><span>[</span><span>sourceContract</span><span>]</span><span>[</span><span>sourceTokenId</span><span>]</span><span class="z-keyword"> =</span><span> targetTokenId</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> OwnershipDesignation</span><span>(</span></span> <span class="giallo-l"><span> sourceContract</span><span>,</span><span> </span></span> <span class="giallo-l"><span> sourceTokenId</span><span>,</span><span> </span></span> <span class="giallo-l"><span> targetContract</span><span>,</span></span> <span class="giallo-l"><span> targetTokenId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onERC721Received</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> sourceTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC721</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span>from</span><span>,</span><span> sourceTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> IERC721Receiver</span><span>.</span><span>onERC721Received</span><span>.</span><span>selector</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-storage z-type"> virtual</span></span> <span class="giallo-l"><span class="z-storage z-type"> override</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span> (</span><span>interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC4799</span><span>)</span><span>.</span><span>interfaceId </span><span class="z-keyword">||</span></span> <span class="giallo-l"><span> interfaceId </span><span class="z-keyword">==</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC721Receiver</span><span>)</span><span>.</span><span>interfaceId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.8.0</span><span class="z-keyword"> &lt;</span><span class="z-constant">0.9</span><span>.</span><span class="z-constant">0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4799.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4799NFT.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/introspection/ERC165Checker.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> DesignatedOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> designatedOwnerOf</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> IERC4799NFT</span><span class="z-variable"> tokenContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> maxDepth</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> owner </span><span class="z-keyword">=</span><span> tokenContract</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>ERC165Checker</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>owner</span><span>,</span><span class="z-variable z-language"> type</span><span>(</span><span>IERC4799</span><span>)</span><span>.</span><span>interfaceId</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>maxDepth </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;designatedOwnerOf: depth limit exceeded&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span>tokenContract</span><span>,</span><span> tokenId</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> IERC4799</span><span>(</span><span>owner</span><span>)</span><span>.</span><span class="z-entity z-name">designatedTokenOf</span><span>(</span></span> <span class="giallo-l"><span> tokenContract</span><span>,</span></span> <span class="giallo-l"><span> tokenId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> designatedOwnerOf</span><span>(</span><span>tokenContract</span><span>,</span><span> tokenId</span><span>,</span><span> maxDepth </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <h3 id="long-cyclical-chains-of-ownership">Long/Cyclical Chains of Ownership</h3> <p>The primary security concern is that of malicious actors creating excessively long or cyclical chains of ownership, leading applications that attempt to query for the designated owner of a given token to run out of gas and be unable to function. To address this, clients are expected to always query considering a <code>maxDepth</code> parameter, cutting off computation after a certain number of chain traversals.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-02-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Guillaume Ballethttps://github.com/gballet Vitalik Buterinhttps://github.com/vbuterin Dankrad Feisthttps://github.com/dankrad https://wg-eips.ritovision.com/4758/

Deactivate SELFDESTRUCT by changing it to SENDALL, which does recover all funds to the caller but does not delete any code or storage.

<h2 id="abstract">Abstract</h2> <p>This EIP renames the <code>SELFDESTRUCT</code> opcode to <code>SENDALL</code>, and replaces its functionality. The new functionality will be only to send all Ether in the account to the caller.</p> <h2 id="motivation">Motivation</h2> <p>The <code>SELFDESTRUCT</code> opcode requires large changes to the state of an account, in particular removing all code and storage. This will not be possible in the future with Verkle trees: Each account will be stored in many different account keys, which will not be obviously connected to the root account.</p> <p>This EIP implements this change. Applications that only use <code>SELFDESTRUCT</code> to retrieve funds will still work.</p> <h2 id="specification">Specification</h2> <ul> <li>The <code>SELFDESTRUCT</code> opcode is renamed to <code>SENDALL</code>, and now only immediately moves all ETH in the account to the target; it no longer destroys code or storage or alters the nonce</li> <li>All refunds related to <code>SELFDESTRUCT</code> are removed</li> </ul> <h2 id="rationale">Rationale</h2> <p>Getting rid of the <code>SELFDESTRUCT</code> opcode has been considered in the past, and there are currently no strong reasons to use it. Disabling it will be a requirement for statelessness.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork, since it modifies consensus rules.</p> <p>Few applications are affected by this change. The only use that breaks is where a contract is re-created at the same address using <code>CREATE2</code> (after a <code>SELFDESTRUCT</code>).</p> <h2 id="security-considerations">Security Considerations</h2> <p>The following applications of <code>SELFDESTRUCT</code> will be broken and applications that use it in this way are not safe anymore:</p> <ol> <li>Any use where <code>SELFDESTRUCT</code> is used to burn non-ETH token balances, such as <a href="https://wg-eips.ritovision.com/20/">EIP-20</a>), inside a contract. We do not know of any such use (since it can easily be done by sending to a burn address this seems an unlikely way to use <code>SELFDESTRUCT</code>)</li> <li>Where <code>CREATE2</code> is used to redeploy a contract in the same place. There are two ways in which this can fail: <ul> <li>The destruction prevents the contract from being used outside of a certain context. For example, the contract allows anyone to withdraw funds, but <code>SELFDESTRUCT</code> is used at the end of an operation to prevent others from doing this. This type of operation can easily be modified to not depend on <code>SELFDESTRUCT</code>.</li> <li>The <code>SELFDESTRUCT</code> operation is used in order to make a contract upgradable. This is not supported anymore and delegates should be used.</li> </ul> </li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-02-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Guillaume Ballethttps://github.com/gballet Vitalik Buterinhttps://github.com/vbuterin Dankrad Feisthttps://github.com/dankrad https://wg-eips.ritovision.com/4760/

Deactivate SELFDESTRUCT by changing it to SENDALL and stage this via a stage of exponential gas cost increases.

<h2 id="abstract">Abstract</h2> <p>This EIP renames the <code>SELFDESTRUCT</code> opcode to <code>SENDALL</code>, and replaces its functionality. The new functionality will be only to send all Ether in the account to the caller.</p> <p>In order to give apps more warning even if their developers are completely unaware of the EIP process, this version will exponentially increase the gas costs of the opcode, so any developer has time to see this change and react by implementing a version of their contract that does not rely on <code>SELFDESTRUCT</code> .</p> <h2 id="motivation">Motivation</h2> <p>The <code>SELFDESTRUCT</code> opcode requires large changes to the state of an account, in particular removing all code and storage. This will not be possible in the future with Verkle trees: Each account will be stored in many different account keys, which will not be obviously connected to the root account.</p> <p>This EIP implements this change. Applications that only use <code>SELFDESTRUCT</code> to retrieve funds will still work.</p> <h2 id="specification">Specification</h2> <h3 id="constants">Constants</h3> <table><thead><tr><th>Name</th><th>Value</th><th>Comment</th></tr></thead><tbody> <tr><td><code>OLD_SELFDESTRUCT_COST</code></td><td>5000</td><td>Current gas cost of <code>SELFDESTRUCT</code> opcode</td></tr> <tr><td><code>HARD_FORK_BLOCK</code></td><td>TBD</td><td>(Shanghai HF block height)</td></tr> <tr><td><code>DOUBLING_SLOTS</code></td><td><code>2**16</code></td><td>(Time for gas price to double, ca. 9 days)</td></tr> <tr><td><code>DOUBLINGS_BEFORE_SENDALL</code></td><td><code>13</code></td><td><code>SELFDESTRUCT</code> will be converted to <code>SENDALL</code> at <code>HARD_FORK_BLOCK + DOUBLING_SLOTS * DOUBLINGS_BEFORE_SENDALL</code></td></tr> </tbody></table> <ul> <li>If <code>HARD_FORK_BLOCK &lt;= slot &lt; HARD_FORK_BLOCK + DOUBLING_SLOTS * DOUBLINGS_BEFORE_SENDALL</code> <ul> <li><code>SELFDESTRUCT</code> functionality remains unchanged</li> <li><code>SELFDESTRUCT</code> gas cost is now <code>OLD_SELFDESTRUCT_COST * 2 ** ((slot - HARD_FORK_BLOCK) // DOUBLING_SLOTS)</code></li> </ul> </li> <li>For <code>slot &gt;= HARD_FORK_BLOCK + DOUBLING_SLOTS * DOUBLINGS_BEFORE_SENDALL</code> <ul> <li>The cost reverts back to <code>OLD_SELFDESTRUCT_COST</code></li> <li>The <code>SELFDESTRUCT</code> opcode is renamed to <code>SENDALL</code>, and now only immediately moves all ETH in the account to the target; it no longer destroys code or storage or alters the nonce</li> <li>All refunds related to <code>SELFDESTRUCT</code> are removed</li> </ul> </li> </ul> <h2 id="rationale">Rationale</h2> <p>The idea behind this EIP is to disable <code>SELFDESTRUCT</code> in a way that gives ample warning to Dapp developers. Many developers do not watch the EIP process closely and can therefore be caught by surprise when an opcode is deactivated and does not fulfill its original purpose anymore. However, at least if the smart contract has regular use, then users will notice the price of the operation going up tremendously. The period over which this is happening (<code>HARD_FORK_BLOCK + DOUBLING_SLOTS * DOUBLINGS_BEFORE_SENDALL</code>) is chosen to be long enough (ca. 4 months) such that it gives developers time to react to this change and prepare their application.</p> <h2 id="backward-compatibility">Backward Compatibility</h2> <p>This EIP requires a hard fork, since it modifies consensus rules.</p> <p>Few applications are affected by this change. The only use that breaks is where a contract is re-created at the same address using <code>CREATE2</code> (after a <code>SELFDESTRUCT</code>). The only application that is significantly affected (and where code can be analyzed) is able to switch to a different model, and should have ample time to do so.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The following applications of <code>SELFDESTRUCT</code> will be broken and applications that use it in this way are not safe anymore:</p> <ol> <li> <p>Any use where <code>SELFDESTRUCT</code> is used to burn non-ETH token balances, such as ERC20, inside a contract. We do not know of any such use (since it can easily be done by sending to a burn address this seems an unlikely way to use <code>SELFDESTRUCT</code>)</p> </li> <li> <p>Where <code>CREATE2</code> is used to redeploy a contract in the same place. There are two ways in which this can fail:</p> <ul> <li>The destruction prevents the contract from being used outside of a certain context. For example, the contract allows anyone to withdraw funds, but <code>SELFDESTRUCT</code> is used at the end of an operation to prevent others from doing this. This type of operation can easily be modified to not depend on <code>SELFDESTRUCT</code>.</li> <li>The <code>SELFDESTRUCT</code> operation is used in order to make a contract upgradable. This is not supported anymore and delegates should be used.</li> </ul> </li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-02-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 Peter Davieshttps://github.com/petertdavies https://wg-eips.ritovision.com/4747/

Simplify EIP-161 and retroactively deprecate unused aspects of it

<h2 id="abstract">Abstract</h2> <p>Simplify the definition of <a href="https://wg-eips.ritovision.com/161/">EIP-161</a>, removing the requirement for implementors to support edge cases that are impossible on Ethereum Mainnet.</p> <h2 id="motivation">Motivation</h2> <p>EIP-161 is overly complex and has a number of edge cases that are poorly documented and tested. This EIP takes advantage of the complete removal of all remaining empty accounts in block 14049881 (tx <code>0xf955834bfa097458a9cf6b719705a443d32e7f43f20b9b0294098c205b4bcc3d</code>) to clarify it, and allows implementors to not implement various edge cases that never occurred and are not possible in the future.</p> <p>In particular, this EIP permits implementors who do not wish to support historical blocks to not implement state clearing at all.</p> <h2 id="specification">Specification</h2> <p>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> <p>Retroactively replace EIP-161, starting from its introduction in block 2675000, with the following rules:</p> <p>a. When creating an account, set it's nonce to <code>1</code> prior to executing initcode.</p> <p>b. When performing EVM execution treat all empty accounts as if they do not exist. Any operation that would create an empty account instead leaves it non-existent.</p> <p>c. If one of the following events happens to an empty account <code>X</code>, it is deleted:</p> <ol> <li><code>X</code> receives a zero value <code>CALL</code>.</li> <li><code>X</code> is the recipient of a zero value transaction.</li> <li><code>X</code> is the beneficiary of a <code>SELFDESTRUCT</code> with zero value.</li> </ol> <p>If the transaction, <code>CALL</code> or <code>SELFDESTRUCT</code> is reverted, then the state clearing is also reverted. As a special case on Ethereum Mainnet, in block 2675119 (tx <code>0xcf416c536ec1a19ed1fb89e4ec7ffb3cf73aa413b3aa9b77d60e4fd81a4296ba</code>), an empty call is made to an empty account at <code>RIPEMD160</code> (precompile <code>0x3</code>), the call fails out of gas, but the empty account is removed anyway.</p> <p>The deletion MAY happen immediately or be processed at the end of the transaction. A client may assume that <code>STATICCALL</code>s to empty accounts never occur and that <code>CALL</code>s to empty accounts in <code>STATICCALL</code> contexts never occur.</p> <p>On Ethereum Mainnet, the only state clearing events after the start of Byzantium are the two listed below. Clients MAY implement post Byzantium state clearing by hardcoding those events.</p> <ul> <li> <p>In block 4457731 (tx <code>0x63791f962e13e6b01ec13d38a8ab66c87c2f5a1768276f866300d900cca808fe</code>), <code>0xd29DFe5aE95B5C067a91F472Dac0d9be6700A4A9</code> receives a zero value <code>SELFDESTRUCT</code> and is cleared.</p> </li> <li> <p>In block 14049881 (tx <code>0xf955834bfa097458a9cf6b719705a443d32e7f43f20b9b0294098c205b4bcc3d</code>), the following accounts receive zero value calls and are cleared.</p> <details> <summary>Accounts cleared</summary> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x01a3dd7d158e3b4c9d8d2af0ddcf3df0f5e14463</span></span> <span class="giallo-l"><span>0x0366c731dd7c095dc08896806765a649c6c0885a</span></span> <span class="giallo-l"><span>0x056c68da52395f1d42c5ba15c4fb956146a4f2c1</span></span> <span class="giallo-l"><span>0x070ba92497cd4b88a8a9a60795ca7d7f7de0faa3</span></span> <span class="giallo-l"><span>0x07a1648ce2bed6721a5d25de3c228a296d03fd52</span></span> <span class="giallo-l"><span>0x07b14ba68f474529cc0bd6a9bffee2bc4090d185</span></span> <span class="giallo-l"><span>0x07ea32232e37d44134a3071319d228bdab249a60</span></span> <span class="giallo-l"><span>0x096b7382500fa11c22c54c0422c5e38899a2e933</span></span> <span class="giallo-l"><span>0x09f3200441bd60522bcf28f3666f8e8dbd19fb62</span></span> <span class="giallo-l"><span>0x0ad0f3c60696adece09367a9a11c968fb88560bb</span></span> <span class="giallo-l"><span>0x0af6181e1db22071f38fc162e1610e29d288de04</span></span> <span class="giallo-l"><span>0x0cdc7fef8f8d0ee77360060930aada1263b26ff7</span></span> <span class="giallo-l"><span>0x0dac3d571eb5b884a2550db2791d5ac1efca306b</span></span> <span class="giallo-l"><span>0x0ec857faba49392080b68dd5074d85f34724d04a</span></span> <span class="giallo-l"><span>0x0f5054f9c674b37d15915ca8925f231edb3afa8c</span></span> <span class="giallo-l"><span>0x0f78d535e1faad9a982dca2a76d16da4649f7021</span></span> <span class="giallo-l"><span>0x104c5b235166f26df54f52666d5e77d9e03e353e</span></span> <span class="giallo-l"><span>0x106b47175965b6d607008544267c91490672a54f</span></span> <span class="giallo-l"><span>0x1223d5c03b4d52ebed43f781251098c9138c3dd7</span></span> <span class="giallo-l"><span>0x1251d13cde439378349f039379e83c2641b6269f</span></span> <span class="giallo-l"><span>0x12c814cebee6bb08a5d1b9d009332bf8b536d645</span></span> <span class="giallo-l"><span>0x150c63df3da35e590a6d2f7accf2e6f241ea5f1a</span></span> <span class="giallo-l"><span>0x15ddf20e4eb8b53b823bc45c9bad2670aad907dd</span></span> <span class="giallo-l"><span>0x1712b1c428f89bc695b1871abfff6b5097350150</span></span> <span class="giallo-l"><span>0x178df2e27b781f024e90ab0abe9cff7e2f66a5fc</span></span> <span class="giallo-l"><span>0x1c2bd83dc29095173c4bcc14927811f5141c1373</span></span> <span class="giallo-l"><span>0x1d12f2fad3603ea871fcb13ac3e30674f9ad903f</span></span> <span class="giallo-l"><span>0x1f7391b6881b6f025aef25cff737ff3fcb9d7660</span></span> <span class="giallo-l"><span>0x219a3d724f596a4b75656e9b1569289c71782804</span></span> <span class="giallo-l"><span>0x21a7fd9228c46ec72f926978f791fc8bfcd277fa</span></span> <span class="giallo-l"><span>0x23acb760cebd01fe7c92361274a4077d37b59f4c</span></span> <span class="giallo-l"><span>0x23b249eeeeedd86bc40349f8bb8e2df34bd28f78</span></span> <span class="giallo-l"><span>0x28d006b1a2309e957005ee575f422af8034f93df</span></span> <span class="giallo-l"><span>0x28ef72d5614b2833d645aecf8ef7add075eb21e2</span></span> <span class="giallo-l"><span>0x292966802ffedb6f34f2c8c59df35c9d8f612c24</span></span> <span class="giallo-l"><span>0x2c2661ddd320017138075aba06999440a902695f</span></span> <span class="giallo-l"><span>0x2c632be2dc2f47affd07bfce91bd4a27c02f4563</span></span> <span class="giallo-l"><span>0x2f86de22ced85a7dd0d680fc4266929a72775e27</span></span> <span class="giallo-l"><span>0x2fa04f15123025ab487dce71668f5265649d0598</span></span> <span class="giallo-l"><span>0x30f78fd12c17855453e0db166fecf684bb239b8c</span></span> <span class="giallo-l"><span>0x31534e95353323209cd18ad35c22c2528db6d164</span></span> <span class="giallo-l"><span>0x336e0e1a14e0136c02bf8dcf0a9a3fe408548262</span></span> <span class="giallo-l"><span>0x340399588bba5b843883d1ad7afd771a3651447a</span></span> <span class="giallo-l"><span>0x341d2b82d0924ef42d75ce053654295d34839459</span></span> <span class="giallo-l"><span>0x34c2b8975b47e13818f496cf80b40566798cf968</span></span> <span class="giallo-l"><span>0x370e67f45db9c18d6551000e6c0918bc8d346ebf</span></span> <span class="giallo-l"><span>0x37149dae898296173d309f1de6981922ec1dc495</span></span> <span class="giallo-l"><span>0x377cb0d3427af7f06df47d2ab420458834bed1fc</span></span> <span class="giallo-l"><span>0x3d473af3e6ce45183c781b414e8a9edcb8b26f72</span></span> <span class="giallo-l"><span>0x42794c1d807079e16735e47e193825cec80ee28c</span></span> <span class="giallo-l"><span>0x45603aa97b67965b42b38ddc8884373edbcf2d56</span></span> <span class="giallo-l"><span>0x465cb9df2f6d3c8a1c1ce3f2338823f0638fefa5</span></span> <span class="giallo-l"><span>0x49fbe69c2897bce0340b5983a0f719213a8c6e6f</span></span> <span class="giallo-l"><span>0x4a84cbd3ef642e301aa59bedf4fa4d28e24e6204</span></span> <span class="giallo-l"><span>0x4d4d551bd6244b854e732572902f19f4ccaa6996</span></span> <span class="giallo-l"><span>0x4f62af4ec150ea121859b3368e6a61fb7bcf9002</span></span> <span class="giallo-l"><span>0x4fd1c530f73ddfff5c609a4a8b25af6ca489d1fd</span></span> <span class="giallo-l"><span>0x50010a4f0e429b398c66876dea7694d5f8b1a639</span></span> <span class="giallo-l"><span>0x522c9f65bc77ad9eed6bcdc3ec220236451c9583</span></span> <span class="giallo-l"><span>0x52b30ca3c2f8656e2c022e896bef7fad9a0449ca</span></span> <span class="giallo-l"><span>0x537a7030ecd9d159e8231ce31b0c2e83b4f9ed75</span></span> <span class="giallo-l"><span>0x5483a4c5583d5ba3db23676a3db346f47ba357e1</span></span> <span class="giallo-l"><span>0x55ec1a78a1187428dc0c67cbb77ae9fbdd61cc2a</span></span> <span class="giallo-l"><span>0x56cc1c0aadc2b8beb71f1ac61f03645483abe165</span></span> <span class="giallo-l"><span>0x58bea8cea61fad5c453731aaeed377f3d77a04cc</span></span> <span class="giallo-l"><span>0x58f632327fbc4f449bda3bd51e13f590e67a8627</span></span> <span class="giallo-l"><span>0x59d122afcbd68c731de85c2597004c6ddafbc7ed</span></span> <span class="giallo-l"><span>0x5da0228024cc084b9475470a7b7ae1d478d51bb7</span></span> <span class="giallo-l"><span>0x5e51d6621883afcbd4e999b93180a96909bdc766</span></span> <span class="giallo-l"><span>0x5e9a0a1bdfdd868706f4554aae21bb2c46da32c2</span></span> <span class="giallo-l"><span>0x5f3f0d3215db85faa693d99acfb03cca66556671</span></span> <span class="giallo-l"><span>0x5f6aa25f22edb2347b464312e2508cbc4c6e0162</span></span> <span class="giallo-l"><span>0x6006f79e4104850ab7c9b0f75918c1e2cf6311df</span></span> <span class="giallo-l"><span>0x60f5da58bccb716f58b5759a06fc2167fe237c26</span></span> <span class="giallo-l"><span>0x62d3a444d0af59f9de79f8abeb5c942fcfbfbef5</span></span> <span class="giallo-l"><span>0x630ea66c8c5dc205d45a978573fa86df5af1fe7a</span></span> <span class="giallo-l"><span>0x6464f0f96a29934087a955c67a6b53d5ed852e49</span></span> <span class="giallo-l"><span>0x6653cedb0b7f51c4b0c44079eb45c514df24ecfd</span></span> <span class="giallo-l"><span>0x66d69ac12b573299f36b108792be75a1e2ccdfdc</span></span> <span class="giallo-l"><span>0x690ed837d25b46dbf46727fcda7392d997c2bc97</span></span> <span class="giallo-l"><span>0x696eecbc97189c5b2a8245a8e32517db9960c171</span></span> <span class="giallo-l"><span>0x69aaff0b7babe85e0a95adfc540e689399db7f24</span></span> <span class="giallo-l"><span>0x6b71d2ceab5678b607aa1e69b6781f5c7abc9aaf</span></span> <span class="giallo-l"><span>0x6e03d9cce9d60f3e9f2597e13cd4c54c55330cfd</span></span> <span class="giallo-l"><span>0x6e278cfecfe96fa5e6d5411ba6eeb765dff4f118</span></span> <span class="giallo-l"><span>0x6e557f01c9dcb573b03909c9a5b3528aec263472</span></span> <span class="giallo-l"><span>0x6ec268f8bef9c685d7e04d5cdb61fbb544869a9f</span></span> <span class="giallo-l"><span>0x6f2ba051b3ce06a90705c22e0241c2b7e32c1af0</span></span> <span class="giallo-l"><span>0x7063732ced55cfa08aea520f3fe200c39b3df0f5</span></span> <span class="giallo-l"><span>0x7073a17a0172dfb1e46a62f054d11a775aeac32e</span></span> <span class="giallo-l"><span>0x71d3718cfa0f9ee8173688fe52bb499e1f36534b</span></span> <span class="giallo-l"><span>0x74e20aec156674945894d404f8dea602570e62f5</span></span> <span class="giallo-l"><span>0x783e45c2989e675ffc9d067914d7de3ff68aee58</span></span> <span class="giallo-l"><span>0x7a5f843f884bb15d070806e1ff59b6c6f74bbe2d</span></span> <span class="giallo-l"><span>0x7c6b1706c86ea76a0e232324f249e1508ca2dfda</span></span> <span class="giallo-l"><span>0x7d23a23584c83c1f6636124255cfd8e9cfc0e529</span></span> <span class="giallo-l"><span>0x7e8b5df0dec9168741c93d52d7045aca7ea632d3</span></span> <span class="giallo-l"><span>0x7ec5da0f1036750688084252b802befe41551205</span></span> <span class="giallo-l"><span>0x82c9fcef4dd2d374b000063d4899a38a7219cdc7</span></span> <span class="giallo-l"><span>0x82fa2ab30a566ceeac987eb5510485be9382f130</span></span> <span class="giallo-l"><span>0x83d927aca3266f94e8163eaa32700c70e9b76e6e</span></span> <span class="giallo-l"><span>0x8476f7e193c930f21e88dae84888e0d8bfaf3ed8</span></span> <span class="giallo-l"><span>0x85ec166cb81f5010b4a8d365821473dac0c0aa88</span></span> <span class="giallo-l"><span>0x8883c55943d5caf06b6484de9c1d73da8307cd82</span></span> <span class="giallo-l"><span>0x8c07456cffd4254c89aaaa9d4e95c8b3e36c2a3b</span></span> <span class="giallo-l"><span>0x8fef965e5db6f7f1a165008499e8b7901cd766b2</span></span> <span class="giallo-l"><span>0x9018e2967c15e1faed9b5d6439522f075535a683</span></span> <span class="giallo-l"><span>0x903f1d8a086c6af1afe24648b6409aade83c4340</span></span> <span class="giallo-l"><span>0x9127c398827d8db6b6d5f17b71f5db69d06e8b74</span></span> <span class="giallo-l"><span>0x917b5be6e3acd96d40a33c13e6748e4a88576c6d</span></span> <span class="giallo-l"><span>0x91edfd05112f0bc9d6cd43b65361713a50e9eb7f</span></span> <span class="giallo-l"><span>0x93026a2c4a0bc69de31515070bf086e0c1f789e5</span></span> <span class="giallo-l"><span>0x94863bbbc12ec5be148f60a7020fd49236fc1937</span></span> <span class="giallo-l"><span>0x94befc001e203f141462f16bde60873bcefae401</span></span> <span class="giallo-l"><span>0x94c408cf5934f241d4fdd55ff3825131635c6af2</span></span> <span class="giallo-l"><span>0x94cfdec548de92301735dc0b82d8e1f79404ff94</span></span> <span class="giallo-l"><span>0x96527f3311f44340887c926acc16f0997eb3b955</span></span> <span class="giallo-l"><span>0x974117faf194885c01513e8d87b38a2291083ed5</span></span> <span class="giallo-l"><span>0x993424827a5fb2fa97818814ea4027e28150f187</span></span> <span class="giallo-l"><span>0x9a6f30a5cb46840076edd780da2dbb4bc7c39f24</span></span> <span class="giallo-l"><span>0x9a74a096b0bb82adfd28494107f2c07f4545723e</span></span> <span class="giallo-l"><span>0x9af82ec46185641c0ea44679aac8a7e7570be202</span></span> <span class="giallo-l"><span>0x9e2287a60ed85f6bd80c62c1b7b4130ea1b521dd</span></span> <span class="giallo-l"><span>0x9fee5b81ee0cbf34c18c52061f1b257d4ccb2702</span></span> <span class="giallo-l"><span>0xa017226377e775af8e56450301cc035ae72267f8</span></span> <span class="giallo-l"><span>0xa1b423e024daf925f25296ea2efcf009cc328873</span></span> <span class="giallo-l"><span>0xa23c0cbfe59e8650277ffa635c59f287cece9087</span></span> <span class="giallo-l"><span>0xa340b7625eec76b372f2c317fe08a7733f05d09c</span></span> <span class="giallo-l"><span>0xa4cb6be13c2eace6c0f1157553e3c446f7b38b10</span></span> <span class="giallo-l"><span>0xa54326267784fae3ffd6800af38099753bb7f470</span></span> <span class="giallo-l"><span>0xa580086125d040fddd3af9d563285bd0ec4d13e3</span></span> <span class="giallo-l"><span>0xa88fc7a34ca36b952aa45d94c1e13155042b5e7d</span></span> <span class="giallo-l"><span>0xac8f4ce2e4eff39c738bf1941350b3b57e8eec4f</span></span> <span class="giallo-l"><span>0xacb17dca110db022b1aceb5399acba1e9bf577e3</span></span> <span class="giallo-l"><span>0xae0b03c8d8bf9cf71eda758e9e8b59c70a3b4580</span></span> <span class="giallo-l"><span>0xae365ff4b0c64413baf6f7dfdb5cd3fb65ad1376</span></span> <span class="giallo-l"><span>0xaf7e60d02b425b54730b7281a97d1640233704b0</span></span> <span class="giallo-l"><span>0xaf9846f8098656e7c2f0e53e9ff7d38ec7b7f679</span></span> <span class="giallo-l"><span>0xb2784c0a95e9b6b865aca13556fb32e2f37cb775</span></span> <span class="giallo-l"><span>0xb385fa211cd08326ff84b0d4f37cc8c3735aa3aa</span></span> <span class="giallo-l"><span>0xb3fb883cbbccb0551daf1507f87426fd38da087e</span></span> <span class="giallo-l"><span>0xb6515cfb82fa877fbadae5a87006a8d3deeeb7c9</span></span> <span class="giallo-l"><span>0xb78c4f0b8c9ec0b3058724eca65292d0d65586b9</span></span> <span class="giallo-l"><span>0xba25f341e16ee81ab80ea246d45bdead7cc339e5</span></span> <span class="giallo-l"><span>0xbab14024437285c2e3b3c521abff96b0ef2e919f</span></span> <span class="giallo-l"><span>0xbaf0996297cc70fca1bee30162eabcd892f0574a</span></span> <span class="giallo-l"><span>0xbb01ea95321a94242c89479995b7e3f264cb46a0</span></span> <span class="giallo-l"><span>0xc1b37a3b7f76947e24cc2470e0e948aab0181346</span></span> <span class="giallo-l"><span>0xc24431c1a1147456414355b1f1769de450e524da</span></span> <span class="giallo-l"><span>0xc467b893e29277f9b62b4ed6c9ba054bd8225bff</span></span> <span class="giallo-l"><span>0xc4bc101a168ea2228973a65564a7d40a68528dd2</span></span> <span class="giallo-l"><span>0xc784626571c2c25cd2cfe24192a149cad86d40d8</span></span> <span class="giallo-l"><span>0xc7acf90a9f442855b8f291288bb5fb612536ed9b</span></span> <span class="giallo-l"><span>0xc9956593dbfb46cfd24686a365b34051a55abce6</span></span> <span class="giallo-l"><span>0xca2eb2af7dd7a90777c8c6456efcc00fe56dbd6f</span></span> <span class="giallo-l"><span>0xcb4bb078edaae9393c8da27b809aa9c0f4c920b7</span></span> <span class="giallo-l"><span>0xcc8f68e8e2d8196e2ecd0caf2f35b1611739a21f</span></span> <span class="giallo-l"><span>0xcd67903318a805d63fe79bf9b8401c1b79c6babf</span></span> <span class="giallo-l"><span>0xcd7a2fe9cb80c95b03950daf5b6d476bec9ac24d</span></span> <span class="giallo-l"><span>0xd09476f5ee7979becca8ffe6dc22a72565fc3cea</span></span> <span class="giallo-l"><span>0xd1c4bd2b583f445354d1b644ea4b8353f2d23048</span></span> <span class="giallo-l"><span>0xd32bb8bceafc89ff59ba43ce8b6cd65bb06dd7b0</span></span> <span class="giallo-l"><span>0xd49e9fa792db9d9398c57eabf94ba1b2c709ace7</span></span> <span class="giallo-l"><span>0xd6b862cf0d009bde0f020ab9d8f96e475069c5c6</span></span> <span class="giallo-l"><span>0xd747c05d9c8057db608ef7aedabf07e4db0bbe97</span></span> <span class="giallo-l"><span>0xdb9b40d1b691ced3680e539261b6bc195388b3c0</span></span> <span class="giallo-l"><span>0xdbcc502093cadd0feb709708c633e2427aeb9c2d</span></span> <span class="giallo-l"><span>0xdc53001181ddc6a279deea6419443ea0ac0aec9c</span></span> <span class="giallo-l"><span>0xde3b38cb1050e7b5db39b4cbb2b2b63a1e32cbf6</span></span> <span class="giallo-l"><span>0xdf1b687a99216ad4ebf9176983bf165be7b25bbe</span></span> <span class="giallo-l"><span>0xe000662c02a02d8b40aabfcd661594312992311d</span></span> <span class="giallo-l"><span>0xe30c59e4dc19d7c9ed6eb10d734d4d7ef28403ac</span></span> <span class="giallo-l"><span>0xe415114089b4b4933e542a5c79af4b6e6cd7abc9</span></span> <span class="giallo-l"><span>0xe47f0a0e93241d390fe9b99de852682522e847bc</span></span> <span class="giallo-l"><span>0xe54abbd51e324bf8cf349b6b31c01b043d1ee0e4</span></span> <span class="giallo-l"><span>0xe57838f777b11fdc428d9e7e67f1187d6251ba1f</span></span> <span class="giallo-l"><span>0xe5e4b26325d0fbf551367f2cf3b5d01caed6abcf</span></span> <span class="giallo-l"><span>0xe6655208bd812d833238b560e847014b0aab3b51</span></span> <span class="giallo-l"><span>0xe6e16a1023af4a8fe54669f3fce7c406801bb333</span></span> <span class="giallo-l"><span>0xe727bba699fbe82a731dad9476b5234d0038cfa1</span></span> <span class="giallo-l"><span>0xec361d34a55e24e2f77de7121ae2b7bf11ed0d65</span></span> <span class="giallo-l"><span>0xed3bf94976eb11d55b955d1369a478620872b57c</span></span> <span class="giallo-l"><span>0xee93ad447fe6a0e2bbac4952e651b21c0175acad</span></span> <span class="giallo-l"><span>0xefc5d9cabc0bda8124e1b821e8c86c7e7bf1e4bc</span></span> <span class="giallo-l"><span>0xf272f72a00f166f491d994642c8243099b72d2cd</span></span> <span class="giallo-l"><span>0xf45f642034bbce869e31b05d1da919125c7331ee</span></span> <span class="giallo-l"><span>0xf4883b21724405b19e240f3309a64d16dd89adc7</span></span> <span class="giallo-l"><span>0xf5cb2a87ff1095f6d93e7b4bfc1bc47542380550</span></span> <span class="giallo-l"><span>0xf6ddd386c4f7f0b460032c8055d7f9c3503d7140</span></span> <span class="giallo-l"><span>0xf72093096c81b3e9e991f5b737baec9570a56927</span></span> <span class="giallo-l"><span>0xf7412232a7a731bca2e5554c8ee051274373c17c</span></span> <span class="giallo-l"><span>0xfc2321dc32c2e6e96a0e41c911fb73a7b278d5c8</span></span> <span class="giallo-l"><span>0xfc4dc782bf7e81a2ed5cc0519f80de36e7931bd9</span></span> <span class="giallo-l"><span>0xfcde1c261eb257e14491b4e7cb1949a7623c00c5</span></span> <span class="giallo-l"><span>0xfd17a22fd80075f2716e93268aa01bcdd7d70b22</span></span></code></pre> </details> </li> </ul> <h2 id="rationale">Rationale</h2> <p>EIP-161 provides that empty accounts (accounts that have zero nonce, zero balance and no code, but that might have storage) can no longer be created and provides mechanism to remove old empty accounts. The last empty accounts were removed in block 14049881 (tx <code>0xf955834bfa097458a9cf6b719705a443d32e7f43f20b9b0294098c205b4bcc3d</code>).</p> <p>The complete removal of all empty accounts ensures that certain edgecases of EIP-161 can never occur on Ethereum Mainnet. Continuing to define and test those cases as part of the Ethereum Specification burdens future client implementors with unnecessary technical debt. This EIP declares those cases undefined and leaves clients free to assume they will not occur.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is identical to EIP-161 except for the following differences, none of which affect Ethereum Mainnet. The differences are:</p> <h3 id="potentially-state-changing-operations">"Potentially state-changing operations"</h3> <p>EIP-161 specifies 11 "potentially state-changing operations" that trigger state clearing. All but the 3 listed in this EIP are irrelevant, for the following reasons:</p> <h4 id="impossible">Impossible</h4> <ul> <li>Receiving zero value mining reward/fees (this would become possible after the merge).</li> </ul> <h4 id="cannot-happen-to-an-empty-account">Cannot happen to an empty account</h4> <ul> <li>Being the source of a <code>CREATE</code>.</li> <li>Being the source of a <code>CALL</code>.</li> <li>Being refunded by a <code>SELFDESTRUCT</code></li> </ul> <h4 id="causes-the-account-to-become-non-empty">Causes the account to become non-empty</h4> <ul> <li>Being the sender of a message call transaction.</li> <li>Being the sender of a contract creation transaction.</li> <li>Being created by a <code>CREATE</code>.</li> <li>Being created by a contract creation transaction.</li> </ul> <h3 id="interaction-with-staticcall">Interaction with <code>STATICCALL</code></h3> <p>The interaction between <code>STATICCALL</code> and account clearing has never been specified in an EIP. The Ethereum currently testsuite requires that <code>STATICCALL</code> triggers state clearing.</p> <p>This EIP formally undefines all interactions between <code>STATICCALL</code> and state clearing as it has never happened on Ethereum Mainnet and cannot happen in future.</p> <h3 id="at-the-end-of-the-transaction">"At the end of the transaction"</h3> <p>This only makes a difference if an account is deleted and later recreated in the same transaction. This never happens on Ethereum Mainnet.</p> <h3 id="test-cases">Test Cases</h3> <p>All test cases involving empty accounts in the Ethereum execution layer test suite shall be removed unless they relate to the Spurious Dragon Hardfork. If a Spurious Dragon test relates involved deprecated edgecase the test must be removed or reworked.</p> <h3 id="other-networks">Other networks</h3> <p>Ropsten had empty accounts seeded at genesis. They appear to have been cleared early in Ropsten's history before the Byzantium hardfork. Ropsten has never been checked for edgecases occurring. All other Ethereum testnets have had EIP-161 from genesis.</p> <p>As a security precaution all empty accounts on Ethereum Classic have been cleared, but no checks for edgecases occurring have been done. Due to EIP-161's age the vast majority of EVM compatible networks have supported it from genesis.</p> <h2 id="security-considerations">Security considerations</h2> <p>This EIP is only equivalent to EIP-161 on Ethereum Mainnet if the following facts are true:</p> <ol> <li>No empty accounts are ever touched and then reinstated in the same transaction.</li> <li>The transactions in the Appendix are the only state clearing transactions on Ethereum Mainnet after block 4370000 (start of Byzantium).</li> <li>All empty accounts have been removed on Ethereum Mainnet.</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-02-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/4803/

Valid transactions must have a reasonable gas limit

<h2 id="abstract">Abstract</h2> <p>Limit transaction gas to be between <code>0</code> and <code>2^63-1</code>.</p> <h2 id="motivation">Motivation</h2> <p>The gas limit field in the transaction is specified to be an arbitrary long unsigned integer, but various clients put limits on this value. This EIP brings a reasonable limit into consensus.</p> <h2 id="specification">Specification</h2> <p>Introduce one new restriction retroactively from genesis: any transaction is invalid and not includeable in a block, where the gas limit exceeds <code>2^63-1</code>.</p> <h2 id="rationale">Rationale</h2> <h3 id="2-63-1-vs-2-64-1"><code>2^63-1</code> vs <code>2^64-1</code></h3> <p><code>2^63-1</code> is chosen because it allows representing the gas value as a signed integer, and so the out of gas check can be done as a simple "less than zero" check after subtraction.</p> <h3 id="consider-2-31-1">Consider <code>2^31-1</code></h3> <p>An alternative is considering a lower limit, because this can be handled easily in Javascript, since it handles numbers as floating point (the actual upper bound is <code>2^53-1</code>).</p> <h3 id="current-limit">Current limit</h3> <p>Due to the nature of RLP encoding, there is no fixed upper bound for the value, but most implementations limit it to 256-bits. Furthermore, most client implementations (such as geth) internally handle gas as a 64-bit value.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>While this is a breaking change, no actual effect should be visible.</p> <p>Before <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> it was possible to include transactions with <code>gasPrice = 0</code> and thus the <code>gasLimit * gasPrice &lt;= accountBalance</code> calculation could have allowed for arbitrarily large values of <code>gasLimit</code>. However, the rule that the transaction list cannot exceed the block gas limit, and the strict rules about how the block gas limit can change, prevented arbitrarily large values of <code>gasLimit</code> to be in the historical state.</p> <h2 id="security-considerations">Security Considerations</h2> <p>None.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-01-13T00:00:00+00:00 2026-02-11T14:48:26+00:00 Omar Aflakhttps://github.com/omaraflak Pol-Malo Le Bris Marvin Martinhttps://github.com/MarvinMartin24 https://wg-eips.ritovision.com/4671/

A standard interface for non-tradable tokens, aka badges or souldbound NFTs.

<h2 id="abstract">Abstract</h2> <p>A non-tradable token, or NTT, represents inherently personal possessions (material or immaterial), such as university diplomas, online training certificates, government issued documents (national id, driving license, visa, wedding, etc.), labels, and so on.</p> <p>As the name implies, non-tradable tokens are made to not be traded or transferred, they are "soulbound". They don't have monetary value, they are personally delivered to <strong>you</strong>, and they only serve as a <strong>proof of possession/achievement</strong>.</p> <p>In other words, the possession of a token carries a strong meaning in itself depending on <strong>why</strong> it was delivered.</p> <h2 id="motivation">Motivation</h2> <p>We have seen in the past smart contracts being used to deliver university diplomas or driving licenses, for food labeling or attendance to events, and much more. All of these implementations are different, but they have a common ground: the tokens are <strong>non-tradable</strong>.</p> <p>The blockchain has been used for too long as a means of speculation, and non-tradable tokens want to be part of the general effort aiming to provide usefulness through the blockchain.</p> <p>By providing a common interface for non-tradable tokens, we allow more applications to be developed and we position blockchain technology as a standard gateway for verification of personal possessions and achievements.</p> <h2 id="specification">Specification</h2> <h3 id="non-tradable-token">Non-Tradable Token</h3> <p>A NTT contract is seen as representing <strong>one type of certificate</strong> delivered by <strong>one authority</strong>. For instance, one NTT contract for the French National Id, another for Ethereum EIP creators, and so on...</p> <ul> <li>An address might possess multiple tokens. Each token has a unique identifier: <code>tokenId</code>.</li> <li>An authority who delivers a certificate should be in position to revoke it. Think of driving licenses or weddings. However, it cannot delete your token, i.e. the record will show that you once owned a token from that contract.</li> <li>The most typical usage for third-parties will be to verify if a user has a valid token in a given contract.</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4671</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Event emitted when a token `tokenId` is minted for `owner`</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Minted</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Event emitted when token `tokenId` of `owner` is revoked</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Revoked</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Count all tokens assigned to an owner</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> Address for whom to query the balance</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Number</span><span class="z-comment"> of tokens owned by `owner`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get owner of a token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Address</span><span class="z-comment"> of the owner of `tokenId`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Check if a token hasn&#39;t been revoked</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if the token is valid, false otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValid</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Check if an address owns a valid token in the contract</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> Address for whom to check the ownership</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if `owner` has a valid token, false otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasValid</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="extensions">Extensions</h4> <h5 id="metadata">Metadata</h5> <p>An interface allowing to add metadata linked to each token.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4671.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4671Metadata</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC4671</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Descriptive</span><span class="z-comment"> name of the tokens in this contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> name</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> An</span><span class="z-comment"> abbreviated name of the tokens in this contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> symbol</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> URI to query to get the token&#39;s metadata</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> URI</span><span class="z-comment"> for the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenURI</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="enumerable">Enumerable</h5> <p>An interface allowing to enumerate the tokens of an owner.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4671.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4671Enumerable</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC4671</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> emittedCount</span><span class="z-comment"> Number of tokens emitted</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> emittedCount</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> holdersCount</span><span class="z-comment"> Number of token holders </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> holdersCount</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the tokenId of a token using its position in the owner&#39;s list</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> Address for whom to get the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> index</span><span class="z-comment"> Index of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> of the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenOfOwnerByIndex</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> index</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get a tokenId by it&#39;s index, where 0 &lt;= index &lt; total()</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> index</span><span class="z-comment"> Index of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> of the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenByIndex</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> index</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="delegation">Delegation</h5> <p>An interface allowing delegation rights of token minting.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4671.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4671Delegate</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC4671</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Grant one-time minting right to `operator` for `owner`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> An allowed operator can call the function to transfer rights.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> operator</span><span class="z-comment"> Address allowed to mint a token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> Address for whom `operator` is allowed to mint a token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Grant one-time minting right to a list of `operators` for a corresponding list of `owners`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> An allowed operator can call the function to transfer rights.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> operators</span><span class="z-comment"> Addresses allowed to mint</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owners</span><span class="z-comment"> Addresses for whom `operators` are allowed to mint a token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegateBatch</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> operators</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> owners</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Mint a token. Caller must have the right to mint for the owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> Address for whom the token is minted</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mint</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Mint tokens to multiple addresses. Caller must have the right to mint for all owners.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owners</span><span class="z-comment"> Addresses for whom the tokens are minted</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintBatch</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> owners</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the issuer of a token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier of the token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Address</span><span class="z-comment"> who minted `tokenId`</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> issuerOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="consensus">Consensus</h5> <p>An interface allowing minting/revocation of tokens based on a consensus of a predefined set of addresses.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4671.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4671Consensus</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC4671</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get voters addresses for this consensus contract</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Addresses</span><span class="z-comment"> of the voters</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> voters</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Cast a vote to mint a token for a specific address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> Address for whom to mint the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approveMint</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Cast a vote to revoke a specific token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier of the token to revoke</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approveRevoke</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="pull">Pull</h5> <p>An interface allowing a token owner to pull his token to a another of his wallets (here <code>recipient</code>). The caller must provide a signature of the tuple <code>(tokenId, owner, recipient)</code> using the <code>owner</code> wallet.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC4671.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4671Pull</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC4671</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Pull a token from the owner wallet to the caller&#39;s wallet</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier of the token to transfer</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> Address that owns tokenId</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> signature</span><span class="z-comment"> Signed data (tokenId, owner, recipient) by the owner of the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pull</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="ntt-store">NTT Store</h3> <p>Non-tradable tokens are meant to be fetched by third-parties, which is why there needs to be a convenient way for users to expose some or all of their tokens. We achieve this result using a store which must implement the following interface.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4671Store</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Event emitted when a IERC4671Enumerable contract is added to the owner&#39;s records</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Added</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">address</span><span class="z-variable"> token</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Event emitted when a IERC4671Enumerable contract is removed from the owner&#39;s records</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Removed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">address</span><span class="z-variable"> token</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Add a IERC4671Enumerable contract address to the caller&#39;s record</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> token</span><span class="z-comment"> Address of the IERC4671Enumerable contract to add</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> add</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Remove a IERC4671Enumerable contract from the caller&#39;s record</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> token</span><span class="z-comment"> Address of the IERC4671Enumerable contract to remove</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> remove</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get all the IERC4671Enumerable contracts for a given owner</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> Address for which to retrieve the IERC4671Enumerable contracts</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> get</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="on-chain-vs-off-chain">On-chain vs Off-chain</h3> <p>A decision was made to keep the data off-chain (via <code>tokenURI()</code>) for two main reasons:</p> <ul> <li>Non-tradable tokens represent personal possessions. Therefore, there might be cases where the data should be encrypted. The standard should not outline decisions about encryption because there are just so many ways this could be done, and every possibility is specific to the use-case.</li> <li>Non-tradable tokens must stay generic. There could have been a possibility to make a <code>MetadataStore</code> holding the data of tokens in an elegant way, unfortunately we would have needed a support for generics in solidity (or struct inheritance), which is not available today.</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>You can find an implementation of this standard <a href="https://wg-eips.ritovision.com/4671/assets/index/">here</a>.</p> <p>Using this implementation, this is how you would create a token:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ERC4671.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> EIPCreatorBadge</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC4671</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span class="z-entity z-name"> ERC4671</span><span>(</span><span>&quot;EIP Creator Badge&quot;, &quot;EIP&quot;) </span><span>{</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> giveThatManABadge</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_isCreator</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &quot;You must be the contract creator&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _mint</span><span>(</span><span>owner</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _baseURI</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> override</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-string"> &quot;https://eips.ethereum.org/ntt/&quot;</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This could be a contract managed by the Ethereum foundation and which allows them to deliver tokens to EIP creators.</p> <h2 id="security-considerations">Security Considerations</h2> <p>One security aspect is related to the <code>tokenURI</code> method which returns the metadata linked to a token. Since the standard represents inherently personal possessions, users might want to encrypt the data in some cases e.g. national id cards. Moreover, it is the responsibility of the contract creator to make sure the URI returned by this method is available at all times.</p> <p>The standard does not define any way to transfer a token from one wallet to another. Therefore, users must be very cautious with the wallet they use to receive these tokens. If a wallet is lost, the only way to get the tokens back is for the issuing authorities to deliver the tokens again, akin real life.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-01-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 David Kimhttps://github.com/powerstream3604 https://wg-eips.ritovision.com/4675/

Fractionalize multiple NFTs using a single contract

<h2 id="abstract">Abstract</h2> <p>This standard outlines a smart contract interface eligible to represent any number of fractionalized non-fungible tokens. Existing projects utilizing standards like <a href="https://wg-eips.ritovision.com/1633/">EIP-1633</a> conventionally deploy separate <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> compatible token contracts to fractionalize the non-fungible token into EIP-20 tokens. In contrast, this ERC allows each token ID to represent a token type representing(fractionalizing) the non-fungible token.</p> <p>This standard is approximate in terms of using <code>_id</code> for distinguishing token types. However, this ERC has a clear difference with <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> as each <code>_id</code> represents a distinct NFT.</p> <h2 id="motivation">Motivation</h2> <p>The conventional fractionalization process of fractionalizing a NFT to FT requires deployment of a FT token contract representing the ownership of NFT. This leads to inefficient bytecode usage on Ethereum Blockchain and limits functionalities since each token contract is separated into its own permissioned address. With the rise of multiple NFT projects needing to fractionalize NFT to FT, new type of token standard is needed to back up them.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @title</span><span class="z-comment"> Multi-Fractional Non-Fungible Token Standard</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-keyword"> Note</span><span class="z-comment"> : The ERC-165 identifier for this interface is 0x83f5d35f.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IMFNFT</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when ownership of any token changes by any mechanism.</span></span> <span class="giallo-l"><span class="z-comment"> The `_from` argument MUST be the address of an account/contract sending the token.</span></span> <span class="giallo-l"><span class="z-comment"> The `_to` argument MUST be the address of an account/contract receiving the token.</span></span> <span class="giallo-l"><span class="z-comment"> The `_id` argument MUST be the token type being transferred. (represents NFT)</span></span> <span class="giallo-l"><span class="z-comment"> The `_value` argument MUST be the number of tokens the holder balance is decrease by and match the recipient balance is increased by.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _id</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when the approved address for token is </span><span class="z-keyword">changed</span><span class="z-comment"> or reaffirmed.</span></span> <span class="giallo-l"><span class="z-comment"> The `_owner` argument MUST be the address of account/contract approving to withdraw.</span></span> <span class="giallo-l"><span class="z-comment"> The `_spender` argument MUST be the address of account/contract approved to withdraw from the `_owner` balance.</span></span> <span class="giallo-l"><span class="z-comment"> The `_id` argument MUST be the token type being transferred. (represents NFT)</span></span> <span class="giallo-l"><span class="z-comment"> The `_value` argument MUST be the number of tokens the `_approved` is able to withdraw from `_owner` balance.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _spender</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _id</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when new token type is added which represents the share of the Non-Fungible Token.</span></span> <span class="giallo-l"><span class="z-comment"> The `_parentToken` argument MUST be the address of the Non-Fungible Token contract.</span></span> <span class="giallo-l"><span class="z-comment"> The `_parentTokenId` argument MUST be the token ID of the Non-Fungible Token.</span></span> <span class="giallo-l"><span class="z-comment"> The `_id` argument MUST be the token type being added. (represents NFT)</span></span> <span class="giallo-l"><span class="z-comment"> The `_totalSupply` argument MUST be the number of total token supply of the token type.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenAddition</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _parentToken</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _parentTokenId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _id</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _totalSupply</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfers `_value` amount of an `_id` from the msg.sender address to the `_to` address specified</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> msg.sender must have sufficient balance to handle the tokens being transferred out of the account.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if `_to` is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if balance of msg.sender for token `_id` is lower than the `_value` being transferred.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert on any other error.</span></span> <span class="giallo-l"><span class="z-comment"> MUST emit the `Transfer` event to reflect the balance change.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Source address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> ID of the token type</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _value</span><span class="z-comment"> Transfer amount</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if transfer was successful, false if not</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Approves `_value` amount of an `_id` from the msg.sender to the `_spender` address specified.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> msg.sender must have sufficient balance to handle the tokens when the `_spender` wants to transfer the token on behalf.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if `_spender` is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert on any other error.</span></span> <span class="giallo-l"><span class="z-comment"> MUST emit the `Approval` event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _spender</span><span class="z-comment"> Spender address(account/contract which can withdraw token on behalf of msg.sender)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> ID of the token type</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _value</span><span class="z-comment"> Approval amount</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if approval was successful, false if not</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transfers `_value` amount of an `_id` from the `_from` address to the `_to` address specified.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Caller must be approved to manage the tokens being transferred out of the `_from` account.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if `_to` is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if balance of holder for token `_id` is lower than the `_value` sent.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert on any other error.</span></span> <span class="giallo-l"><span class="z-comment"> MUST emit `Transfer` event to reflect the balance change.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> Source address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Target Address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> ID of the token type</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _value</span><span class="z-comment"> Transfer amount</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if transfer was successful, false if not</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Sets the NFT as a new type token</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> The contract itself should verify if the ownership of NFT is belongs to this contract itself with the `_parentNFTContractAddress` &amp; `_parentNFTTokenId` before adding the token.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if the same NFT is already registered.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if `_parentNFTContractAddress` is address zero.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if `_parentNFTContractAddress` is not ERC-721 compatible.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if this contract itself is not the owner of the NFT.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert on any other error.</span></span> <span class="giallo-l"><span class="z-comment"> MUST emit `TokenAddition` event to reflect the token type addition.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _parentNFTContractAddress</span><span class="z-comment"> NFT contract address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _parentNFTTokenId</span><span class="z-comment"> NFT tokenID</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _totalSupply</span><span class="z-comment"> Total token supply</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setParentNFT</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _parentNFTContractAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _parentNFTTokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _totalSupply</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the token ID&#39;s total token supply.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> ID of the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> total token supply of the specified token type</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the balance of an account&#39;s tokens.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> The address of the token holder</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> ID of the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> _owner&#39;s balance of the token type requested</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the amount which `_spender` is still allowed to withdraw from `_owner`</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> The address of the token holder</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _spender</span><span class="z-comment"> The address approved to withdraw token on behalf of `_owner`</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> ID of the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> amount which `_spender` is still allowed to withdraw from `_owner`</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the bool value which represents whether the NFT is already registered and fractionalized by this contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _parentNFTContractAddress</span><span class="z-comment"> NFT contract address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _parentNFTTokenId</span><span class="z-comment"> NFT tokenID</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> bool value representing the whether the NFT is already registered.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRegistered</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _parentNFTContractAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _parentNFTTokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Query if a contract implements an interface</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> interfaceID</span><span class="z-comment"> The interface identifier, as specified in ERC-165</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface identification is specified in ERC-165. This function</span></span> <span class="giallo-l"><span class="z-comment"> uses less than 30,000 gas.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-comment"> `true` if the contract implements `interfaceID` and</span></span> <span class="giallo-l"><span class="z-comment"> `interfaceID` is not 0xffffffff, `false` otherwise</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>To receive Non-Fungible Token on <code>safe Transfer</code> the contract should include <code>onERC721Received()</code>. Including <code>onERC721Received()</code> is needed to be compatible with Safe Transfer Rules.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Handle the receipt of an NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> The address which called `safeTransferFrom` function</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> The address which previously owned the token</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> The NFT identifier which is being transferred</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _data</span><span class="z-comment"> Additional data with no specified format</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-comment"> `bytes4(keccak256(&quot;onERC721Received(address,address,uint256,bytes)&quot;))`</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> onERC721Received</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _data</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes4</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p><strong>Metadata</strong></p> <p>The <code>symbol()</code> &amp; <code>name()</code> functions were not included since the majority of users can just fetch it from the originating NFT contract. Also, copying the name &amp; symbol every time when token gets added might place a lot of redundant bytecode on the Ethereum blockchain. However, according to the need and design of the project it could also be added to each token type by fetching the metadata from the NFT contract.</p> <p><strong>Design</strong></p> <p>Most of the decisions made around the design of this ERC were done to keep it as flexible for diverse token design &amp; architecture. These minimum requirement for this standard allows for each project to determine their own system for minting, governing, burning their MFNFT tokens depending on their programmable architecture.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>To make this standard compatible with existing standards, this standard <code>event</code> &amp; <code>function</code> names are identical with ERC-20 token standard with some more <code>events</code> &amp; <code>functions</code> to add token type dynamically.</p> <p>Also, the sequence of parameter in use of <code>_id</code> for distinguishing token types in <code>functions</code> and <code>events</code> are very much similar to ERC-1155 Multi-Token Standard.</p> <p>Since this standard is intended to interact with the EIP-721 Non-Fungible Token Standard, it is kept purposefully agnostic to extensions beyond the standard in order to allow specific projects to design their own token usage and scenario.</p> <h2 id="test-cases">Test Cases</h2> <p>Reference Implementation of MFNFT Token includes test cases written using hardhat. (Test coverage : 100%)</p> <h2 id="reference-implementation">Reference Implementation</h2> <p><a href="https://wg-eips.ritovision.com/4675/assets/README/">MFNFT - Implementation</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>To fractionalize an already minted NFT, it is evident that ownership of NFT should be given to token contracts before fractionalization. In the case of fractionalizing NFT, the token contract should thoroughly verify the ownership of NFT before fractionalizing it to prevent tokens from being a separate tokens with the NFT.</p> <p>If an arbitrary account has the right to call <code>setParentNFT()</code> there might be a front-running issue. The caller of <code>setParentNFT()</code> might be different from the real NFT sender. To prevent this issue, implementors should just allow <strong>admin</strong> to call, or fractionalize and receive NFT in an atomic transaction similar to flash loan(swap).</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-01-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Andrei Maiborodahttps://github.com/gumb0 Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast https://wg-eips.ritovision.com/4750/

Individual sections for functions with `CALLF` and `RETF` instructions

<h2 id="abstract">Abstract</h2> <p>Introduce the ability to have several code sections in EOF-formatted (<a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>) bytecode, each one representing a separate subroutine/function. Two new opcodes,<code>CALLF</code> and <code>RETF</code>, are introduced to call and return from such a function. Dynamic jump instructions are disallowed.</p> <h2 id="motivation">Motivation</h2> <p>Currently, in the EVM everything is a dynamic jump. Languages like Solidity generate most jumps in a static manner (i.e. the destination is pushed to the stack right before, <code>PUSHn .. JUMP</code>). Unfortunately however this cannot be used by most EVM interpreters, because of added requirement of validation/analysis. This also restricts them from making optimisations and potentially reducing the cost of jumps.</p> <p><a href="https://wg-eips.ritovision.com/4200/">EIP-4200</a> introduces static jump instructions, which remove the need for <em>most</em> dynamic jump use cases, but not everything can be solved with them.</p> <p>This EIP aims to remove the need and disallow dynamic jumps as it offers the most important feature those are used for: calling into and returning from functions.</p> <p>Furthermore, it aims to improve analysis opportunities by encoding the number of inputs and outputs for each given function, and isolating the stack of each function (i.e. a function cannot read the stack of the caller/callee).</p> <h2 id="specification">Specification</h2> <h3 id="type-section">Type Section</h3> <p>The type section of EOF containers must adhere to following requirements:</p> <ol> <li>The section is a list of metadata where the metadata index in the type section corresponds to a code section index. Therefore, the type section size MUST be <code>n * 4</code> bytes, where <code>n</code> is the number of code sections.</li> <li>Each metadata item has 3 attributes: a uint8 <code>inputs</code>, a uint8 <code>outputs</code>, and a uint16 <code>max_stack_increase</code>. <em>Note:</em> This implies that there is a limit of 255 stack for the input and in the output. This is further restricted to 127 stack items, because the upper bit of both the input and output bytes are reserved for future use (<code>outputs == 0x80</code> is already used in EOF1 to denote non-returning functions, as introduced in a separate EIP). <code>max_stack_increase</code> is further defined in <a href="https://wg-eips.ritovision.com/5450/">EIP-5450</a>.</li> <li>The 0th code section MUST have 0 inputs and be non-returning.</li> </ol> <p>Refer to <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> to see the full structure of a well-formed EOF bytecode.</p> <h3 id="new-execution-state-in-evm">New execution state in EVM</h3> <p>A return stack is introduced, separate from the operand stack. It is a stack of items representing execution state to return to after function execution is finished. Each item is comprised of code section index and offset in the code section (PC value).</p> <p>Note: Implementations are free to choose particular encoding for a stack item. In the specification below we assume that representation is two unsigned integers: <code>code_section_index</code>, <code>offset</code>.</p> <p>The return stack is limited to a maximum of <code>1024</code> items.</p> <p>Additionally, EVM keeps track of the index of currently executing section - <code>current_section_index</code>.</p> <h3 id="new-instructions">New instructions</h3> <p>We introduce two new instructions:</p> <ol> <li><code>CALLF</code> (<code>0xe3</code>) - call a function</li> <li><code>RETF</code> (<code>0xe4</code>) - return from a function</li> </ol> <p>If the code is legacy bytecode, any of these instructions results in an <em>exceptional halt</em>. (<em>Note: This means no change to behaviour.</em>)</p> <p>First we define several helper values:</p> <ul> <li><code>type[i].inputs = type_section_contents[i * 4]</code> - number of inputs of ith code section</li> <li><code>type[i].outputs = type_section_contents[i * 4 + 1]</code> - number of outputs of ith code section</li> <li><code>type[i].max_stack_increase = type_section_contents[i * 4 + 2:i * 4 + 4]</code> - maximum operand stack height increase of ith code section</li> </ul> <p>If the code is valid EOF1, the following execution rules apply:</p> <h4 id="callf"><code>CALLF</code></h4> <ol> <li> <p>Has one immediate argument,<code>target_section_index</code>, encoded as a 16-bit unsigned big-endian value.</p> </li> <li> <p><em>Note:</em> EOF validation <a href="https://wg-eips.ritovision.com/5450/">EIP-5450</a> guarantees that operand stack has enough items to use as callee's inputs.</p> </li> <li> <p>If operand stack size exceeds <code>1024 - type[target_section_index].max_stack_increase</code> (i.e. if the called function may exceed the global stack height limit), execution results in exceptional halt. This also guarantees that the stack height after the call is within the limits.</p> </li> <li> <p>If return stack already has <code>1024</code> items, execution results in exceptional halt.</p> </li> <li> <p>Charges <code>5</code> gas.</p> </li> <li> <p>Pops nothing and pushes nothing to operand stack.</p> </li> <li> <p>Pushes to return stack an item:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(code_section_index = current_section_index, </span></span> <span class="giallo-l"><span>offset = PC_post_instruction)</span></span></code></pre> <p>Under <code>PC_post_instruction</code> we mean the PC position after the entire immediate argument of <code>CALLF</code>.</p> <p><em>Note:</em> EOF validation <a href="https://wg-eips.ritovision.com/5450/">EIP-5450</a> guarantees there is always an instruction following <code>CALLF</code> (since terminating instruction or unconditional jump is required to be final one in the section), therefore <code>PC_post_instruction</code> always points to an instruction inside section bounds.</p> </li> <li> <p>Sets <code>current_section_index</code> to <code>target_section_index</code> and <code>PC</code> to <code>0</code>, and execution continues in the called section.</p> </li> </ol> <h4 id="retf"><code>RETF</code></h4> <ol> <li>Does not have immediate arguments.</li> <li><em>Note:</em> EOF validation <a href="https://wg-eips.ritovision.com/5450/">EIP-5450</a> guarantees that operand stack has exact number of items to use as outputs.</li> <li>Charges <code>3</code> gas.</li> <li>Pops nothing and pushes nothing to operand stack.</li> <li>Pops an item from return stack and sets <code>current_section_index</code> and <code>PC</code> to values from this item.</li> </ol> <p><em>Note:</em> EOF validation requirement for 0th code section to be non-returning (non-returning sections introduced in a separate EIP) guarantees that return stack cannot be empty before <code>RETF</code>.</p> <h3 id="code-validation">Code Validation</h3> <p>In addition to container format validation rules above, we extend code section validation rules (as defined in <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a>).</p> <ol> <li>Code validation rules of <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a> are applied to every code section.</li> <li>Code section is invalid in case an immediate argument of any <code>CALLF</code> is greater than or equal to the total number of code sections.</li> <li><code>RJUMP</code>, <code>RJUMPI</code> and <code>RJUMPV</code> immediate argument value (jump destination relative offset) validation: <ol> <li>Code section is invalid in case offset points to a position outside of section bounds.</li> <li>Code section is invalid in case offset points to one of two bytes directly following <code>CALLF</code> instruction.</li> </ol> </li> <li>No unreachable code sections are allowed, i.e. every code section can be reached from the 0th code section with a series of <code>CALLF</code> / <code>JUMPF</code> (<code>JUMPF</code> introduced in a separate EIP) instructions (0th code section is always reachable).</li> </ol> <h3 id="disallowed-instructions">Disallowed instructions</h3> <p>Dynamic jump instructions <code>JUMP</code> (<code>0x56</code>) and <code>JUMPI</code> (<code>0x57</code>) are invalid and their opcodes are undefined.</p> <p><code>JUMPDEST</code> (<code>0x5b</code>) instruction is renamed to <code>NOP</code> ("no operation") without the change in behaviour: it pops nothing and pushes nothing to operand stack and has no other effects except for <code>PC</code> increment and charging 1 gas.</p> <p><code>PC</code> (0x58) instruction becomes invalid and its opcode is undefined.</p> <p><em>Note:</em> This change implies that JUMPDEST analysis is no longer required for EOF code.</p> <h3 id="execution">Execution</h3> <ol> <li>Execution starts at the first byte of the 0th code section, and <code>PC</code> is set to <code>0</code>.</li> <li>Return stack is initialized empty.</li> <li>Stack underflow check is not performed anymore. <em>Note:</em> EOF validation <a href="https://wg-eips.ritovision.com/5450/">EIP-5450</a> guarantees that it cannot happen at run-time.</li> <li>Stack overflow check is not performed anymore, except during <code>CALLF</code> as specified above.</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="retf-in-the-top-frame-ends-execution-vs-exceptionally-halts-vs-is-not-allowed-during-validation"><code>RETF</code> in the top frame ends execution vs exceptionally halts vs is not allowed during validation</h3> <p>Alternative logic for <code>RETF</code> in the top frame could be to allow it during code validation and make it either:</p> <ul> <li>end execution if the return stack is emptied by the <code>RETF</code> or</li> <li>exceptionally halt if the return stack is empty before the <code>RETF</code>.</li> </ul> <p>This has been superseded with the validation rule of top frame (0th code section) being non-returning (non-returning sections introduced in a separate EIP), because validating non-returning status of functions is valuable by itself for other reasons. Therefore all considerations of runtime behavior of <code>RETF</code> in the top frame were obsoleted.</p> <h3 id="minimal-function-type">"Minimal" function type</h3> <p>Let's consider a trivial function with single instruction <code>RETF</code>. Such function have the "minimal" type of <code>inputs = 0, outputs = 0</code>. However, any other type like <code>inputs = k, outputs = k</code> is also valid for such function. It has been considered to enforce usage of the "minimal" type for all functions. This requires additional validation rule that checks if any instruction in the function accesses the bottom stack operand. This rule can be obeyed by compilers, but causes quite significant annoyance. On the other hand, it provides close to zero benefits for the EVM implementations. In the end, it has been decided that this is not enforced.</p> <h3 id="code-section-limit-and-instruction-size">Code section limit and instruction size</h3> <p>The number of code sections is limited to 1024. This requires 2-byte immediate for <code>CALLF</code> and leaves room for increasing the limit in the future. The 256 limit (1-byte immediate) was discussed and concerns were raised that it might not be sufficient.</p> <h3 id="nop-instruction"><code>NOP</code> instruction</h3> <p>Instead of deprecating <code>JUMPDEST</code> we repurpose it as <code>NOP</code> instruction, because <code>JUMPDEST</code> effectively was a "no-operation" instruction and was already used as such in various contexts. It can be useful for some off-chain tooling, e.g. benchmarking EVM implementations (performance of <code>NOP</code> instruction is performance of EVM interpreter loop), as a padding to force code alignment, as a placeholder in dynamic code composition.</p> <h3 id="deprecating-jumpdest-analysis">Deprecating <code>JUMPDEST</code> analysis</h3> <p>The purpose of <code>JUMPDEST</code> analysis was to find in code the valid <code>JUMPDEST</code> bytes that do not happen to be inside <code>PUSH</code> immediate data. Only dynamic jump instructions (<code>JUMP</code>, <code>JUMPI</code>) required destination to be <code>JUMPDEST</code> instruction. Relative static jumps (<code>RJUMP</code>, <code>RJUMPI</code> and <code>RJUMPV</code>) do not have this requirement and are validated once at deploy-time during EOF instructions validation. Therefore, without dynamic jump instructions, <code>JUMPDEST</code> analysis is not required.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change poses no risk to backwards compatibility, as it is introduced only for EOF1 contracts, for which deploying undefined instructions is not allowed, therefore there are no existing contracts using these instructions. The new instructions are not introduced for legacy bytecode (code which is not EOF formatted).</p> <p>The new execution state and multi-section control flow pose no risk to backwards compatibility, because it is a generalization of executing a single code section. Executing existing contracts (both legacy and EOF1) has no user-observable changes.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The gas cost of introduced instructions reflects the need to manipulate return stack entries and jumping to proper code section offset in memory when interpreting the bytecode.</p> <p>These new instructions need to be carefully considered during implementation of the EOF container validation algorithm.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2022-01-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yuki Aokihttps://github.com/yuki-js https://wg-eips.ritovision.com/6268/

An extension of EIP-1155 for indicating the transferability of the token.

<h2 id="abstract">Abstract</h2> <p>This EIP standardizes an interface indicating <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>-compatible token non-transferability using <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> feature detection.</p> <h2 id="motivation">Motivation</h2> <p>Soulbound Tokens (SBT) are non-transferable tokens. While <a href="https://wg-eips.ritovision.com/5192/">EIP-5192</a> standardizes non-fungible SBTs, a standard for Soulbound semi-fungible or fungible tokens does not yet exist. The introduction of a standard non-transferability indicator that is agnostic to fungibility promotes the usage of Souldbound semi-fungible or fungible tokens.</p> <h2 id="specification">Specification</h2> <p>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>Smart contracts implementing this standard MUST comform to the <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> specification.</p> <p>Smart contracts implementing this standard MUST implement all of the functions in the <code>IERC6268</code> interface.</p> <p>Smart contracts implementing this standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> supportsInterface function and MUST return the constant value true if <code>0xd87116f3</code> is passed through the interfaceID argument.</p> <p>For the token identifier <code>_id</code> that is marked as <code>locked</code>, <code>locked(_id)</code> MUST return the constant value true and any functions that try transferring the token, including <code>safeTransferFrom</code> and <code>safeBatchTransferFrom</code> function MUST throw.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC6268</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Either `LockedSingle` or `LockedBatch` MUST emit when the locking status is </span><span class="z-keyword">changed</span><span class="z-comment"> to locked.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If a token is minted and the status is locked, this event should be emitted.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> The identifier for a token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LockedSingle</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _id</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Either `LockedSingle` or `LockedBatch` MUST emit when the locking status is </span><span class="z-keyword">changed</span><span class="z-comment"> to locked.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If a token is minted and the status is locked, this event should be emitted.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ids</span><span class="z-comment"> The list of identifiers for tokens.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LockedBatch</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> _ids</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Either `UnlockedSingle` or `UnlockedBatch` MUST emit when the locking status is </span><span class="z-keyword">changed</span><span class="z-comment"> to unlocked.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If a token is minted and the status is unlocked, this event should be emitted.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> The identifier for a token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UnlockedSingle</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> _id</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Either `UnlockedSingle` or `UnlockedBatch` MUST emit when the locking status is </span><span class="z-keyword">changed</span><span class="z-comment"> to unlocked.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> If a token is minted and the status is unlocked, this event should be emitted.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ids</span><span class="z-comment"> The list of identifiers for tokens.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> UnlockedBatch</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> _ids</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the locking status of the token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> SBTs assigned to zero address are considered invalid, and queries</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> about them do throw.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> The identifier for a token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> locked</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the locking statuses of the multiple tokens.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> SBTs assigned to zero address are considered invalid, and queries</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> about them do throw.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ids</span><span class="z-comment"> The list of identifiers for tokens</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lockedBatch</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable z-parameter z-function"> _ids</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Needs discussion.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal is fully backward compatible with <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-12-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Greg Colvinhttps://github.com/gcolvin Greg Colvingreg@colvin.org https://wg-eips.ritovision.com/4573/

Introduces support for EVM Procedures.

<h2 id="abstract">Abstract</h2> <p>Five EVM instructions are introduced to define, call, and return from named EVM <em>procedures</em> and access their <em>call frames</em> in memory - <code>ENTERPROC</code>, <code>LEAVEPROC</code>, <code>CALLPROC</code>, <code>RETURNPROC</code>, and <code>FRAMEADDRESS</code>.</p> <h2 id="motivation">Motivation</h2> <p>Currently, Ethereum bytecode has no syntactic structure, and <em>subroutines</em> have no defined interfaces.</p> <p>We propose to add <em>procedures</em> -- delimited blocks of code that can be entered only by calling into them via defined interfaces.</p> <p>Also, the EVM currently has no automatic management of memory for <em>procedures</em>. So we also propose to automatically reserve call frames on an in-memory stack.</p> <p>Constraints on the use of <em>procedures</em> must be validated at contract initialization time to maintain the safety properties of <a href="https://wg-eips.ritovision.com/3779/">EIP-3779</a>: Valid programs will not halt with an exception unless they run out of gas or recursively overflow stack.</p> <h3 id="prior-art">Prior Art</h3> <p>The terminology is not well-defined, but we will follow Intel in calling the low-level concept <em>subroutines</em> and the higher level concept <em>procedures</em>. The distinction is that <em>subroutines</em> are little more than a jump that knows where it came from, whereas procedures have a defined interface and manage memory as a stack. <a href="https://wg-eips.ritovision.com/2315/">EIP-2315</a> introduces <em>subroutines</em>, and this EIP introduces <em>procedures</em>.</p> <h2 id="specification">Specification</h2> <h3 id="instructions">Instructions</h3> <h4 id="enterproc-0x-dest-section-uint8-dest-offset-uint8-n-inputs-uint16-n-outputs-uint16-n-locals-uint16">ENTERPROC (0x??) dest_section: uint8, dest_offset: uint8, n_inputs: uint16, n_outputs: uint16, n_locals: uint16</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>frame_stack.push(FP)</span></span> <span class="giallo-l"><span>FP -= n_locals * 32</span></span> <span class="giallo-l"><span>PC +- &lt;length of immediates&gt;</span></span></code></pre> <p>Marks the entry point to a procedure</p> <ul> <li>at offset <code>dest_offset</code> from the beginning of the <code>dest_section</code>.</li> <li>taking <code>n_inputs</code> arguments from the data stack,</li> <li>returning <code>n_outputs</code> values on the <code>data stack</code>, and</li> <li>reserving <code>n_locals</code> words of data in memory on the <code>frame stack</code>.</li> </ul> <p>Procedures can only be entered via a <code>CALLPROC</code> to their entry point.</p> <h4 id="leaveproc-0x">LEAVEPROC (0x??)</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> FP = frame_stack.pop()</span></span> <span class="giallo-l"><span> asm RETURNSUB</span></span></code></pre> <blockquote> <p>Pop the <code>frame stack</code> and return to the calling procedure using <code>RETURNSUB</code>.</p> </blockquote> <p>Marks the end of a procedure. Each <code>ENTERPROC</code> requires a closing <code>LEAVEPROC</code>.</p> <p><em>Note: Attempts to jump into a procedure (including its <code>LEAVEPROC</code>) from outside of the procedure or to jump or step to <code>ENTERPROC</code> at all must be prevented at validation time. <code>CALLPROC</code> is the only valid way to enter a procedure.</em></p> <h4 id="callproc-0x-dest-section-uint16-dest-proc-uint16">CALLPROC (0x??) dest_section: uint16, dest_proc: uint16</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> FP -= n_locals</span></span> <span class="giallo-l"><span> asm JUMPSUB &lt;offset of section&gt; + &lt;offset of procedure&gt;</span></span></code></pre> <blockquote> <p>Allocate a <em>stack frame</em> and transfer control and <code>JUMPSUB</code> to the Nth (N=<em>dest_proc</em>) <em>procedure</em> in the Mth(M=<em>dest_section</em>) <em>section</em> of the code. <em>Section 0</em> is the current code section, any other code sections are indexed starting at <em>1</em>.</p> </blockquote> <p><em>Note: That the procedure is defined and the required <code>n_inputs</code> words are available on the <code>data stack</code> must be shown at validation time.</em></p> <h4 id="returnproc-0x">RETURNPROC (0x??)</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> FP += n_locals</span></span> <span class="giallo-l"><span> asm RETURNSUB</span></span></code></pre> <blockquote> <p>Pop the <code>frame stack</code> and return control to the calling procedure using <code>RETURNSUB</code>.</p> </blockquote> <p><em>Note: That the promised <code>n_outputs</code> words are available on the <code>data stack</code> must be shown at validation time.</em></p> <h4 id="frameaddress-0x-offset-int16">FRAMEADDRESS (0x??) offset: int16</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>asm PUSH2 FP + offset</span></span></code></pre> <blockquote> <p>Push the address <code>FP + offset</code> onto the data stack.</p> </blockquote> <p>Call frame data is addressed at an immediate <code>offset</code> relative to <code>FP</code>.</p> <p>Typical usage includes storing data on a call frame</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 0xdada</span></span> <span class="giallo-l"><span>FRAMEADDRESS 32</span></span> <span class="giallo-l"><span>MSTORE</span></span></code></pre> <p>and loading data from a call frame</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>FRAMEADDRESS 32</span></span> <span class="giallo-l"><span>MLOAD</span></span></code></pre><h3 id="memory-costs">Memory Costs</h3> <p>Presently,<code>MSTORE</code> is defined as</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> memory[stack[0]...stack[0]+31] = stack[1]</span></span> <span class="giallo-l"><span> memory_size = max(memory_size,floor((stack[0]+32)÷32)</span></span></code></pre> <ul> <li>where <code>memory_size</code> is the number of active words of memory above <em>0</em>.</li> </ul> <p>We propose to treat memory addresses as signed, so the formula needs to be</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> memory[stack[0]...stack[0]+31] = stack[1]</span></span> <span class="giallo-l"><span> if (stack[0])+32)÷32) &lt; 0</span></span> <span class="giallo-l"><span> negative_memory_size = max(negative_memory_size,floor((stack[0]+32)÷32))</span></span> <span class="giallo-l"><span> else</span></span> <span class="giallo-l"><span> positive_memory_size = max(positive_memory_size,floor((stack[0]+32)÷32))</span></span> <span class="giallo-l"><span> memory_size = positive_memory_size + negative_memory_size</span></span></code></pre> <ul> <li>where <code>negative_memory_size</code> is the number of active words of memory below <em>0</em> and</li> <li>where <code>positive_memory_size</code> is the number of active words of memory at or above <em>0</em>.</li> </ul> <h3 id="call-frame-stack">Call Frame Stack</h3> <p>These instructions make use of a <code>frame stack</code> to allocate and free frames of local data for <em>procedures</em> in memory. Frame memory begins at address 0 in memory and grows downwards, towards more negative addresses. A frame is allocated for each procedure when it is called, and freed when it returns.</p> <p>Memory can be addressed relative to the frame pointer <code>FP</code> or by absolute address. <code>FP</code> starts at 0, and moves downward towards more negative addresses to point to the frame for each <code>CALLPROC</code> and moving upward towards less negative addresses to point to the previous frame for the corresponding <code>RETURNPROC</code>.</p> <p>Equivalently, in the EVM's twos-complement arithmetic, <code>FP</code> moves from the highest address down, as is common in many calling conventions.</p> <p>For example, after an initial <code>CALLPROC</code> to a procedure needing two words of data the <code>frame stack</code> might look like this</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> 0-&gt; ........</span></span> <span class="giallo-l"><span> ........</span></span> <span class="giallo-l"><span> FP-&gt;</span></span></code></pre> <p>Then, after a further <code>CALLPROC</code> to a procedure needing three words of data the <code>frame stack</code> would like this</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> 0-&gt; ........</span></span> <span class="giallo-l"><span> ........</span></span> <span class="giallo-l"><span> -64-&gt; ........</span></span> <span class="giallo-l"><span> ........</span></span> <span class="giallo-l"><span> ........</span></span> <span class="giallo-l"><span> FP-&gt;</span></span></code></pre> <p>After a <code>RETURNPROC</code> from that procedure the <code>frame stack</code> would look like this</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> 0-&gt; ........</span></span> <span class="giallo-l"><span> ........</span></span> <span class="giallo-l"><span> FP-&gt; ........</span></span> <span class="giallo-l"><span> ........</span></span> <span class="giallo-l"><span> ........</span></span></code></pre> <p>and after a final <code>RETURNPROC</code>, like this</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> FP-&gt; ........</span></span> <span class="giallo-l"><span> ........</span></span> <span class="giallo-l"><span> ........</span></span> <span class="giallo-l"><span> ........</span></span> <span class="giallo-l"><span> ........</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>There is actually not much new here. It amounts to <a href="https://wg-eips.ritovision.com/615/">EIP-615</a>, refined and refactored into bite-sized pieces, along lines common to other machines.</p> <p>This proposal uses the <a href="https://wg-eips.ritovision.com/2315/">EIP-2315</a> return stack to manage calls and returns, and steals ideas from <a href="https://wg-eips.ritovision.com/615/">EIP-615</a>, <a href="https://wg-eips.ritovision.com/3336/">EIP-3336</a>, and <a href="https://wg-eips.ritovision.com/4200/">EIP-4200</a>. <code>ENTERPROC</code> corresponds to <code>BEGINSUB</code> from EIP-615. Like EIP-615 it uses a frame stack to track call-frame addresses with <code>FP</code> as <em>procedures</em> are entered and left, but like EIP-3336 and EIP-3337 it moves call frames from the data stack to memory.</p> <p>Aliasing call frames with ordinary memory supports addressing call-frame data with ordinary stores and loads. This is generally useful, especially for languages like C that provide pointers to variables on the stack.</p> <p>The design model here is the <em>subroutines</em> and <em>procedures</em> of the Intel x86 architecture.</p> <ul> <li><code>JUMPSUB</code> and <code>RETURNSUB</code> (from <a href="https://wg-eips.ritovision.com/2315/">EIP-2315</a> -- like <code>CALL</code> and <code>RET</code> -- jump to and return from <em>subroutines</em>.</li> <li><code>ENTERPROC</code> -- like <code>ENTER</code> -- sets up the stack frame for a <em>procedure</em>.</li> <li><code>CALLPROC</code> amounts to a <code>JUMPSUB</code> to an <code>ENTERPROC</code>.</li> <li><code>RETURNPROC</code> amounts to an early <code>LEAVEPROC</code>.</li> <li><code>LEAVEPROC</code> -- like <code>LEAVE</code> -- takes down the stack frame for a <em>procedure</em>. It then executes a <code>RETURNSUB</code>.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal adds new EVM opcodes. It doesn't remove or change the semantics of any existing opcodes, so there should be no backwards compatibility issues.</p> <h2 id="security">Security</h2> <p>Safe use of these constructs must be checked completely at validation time -- per EIP-3779 -- so there should be no security issues at runtime.</p> <p><code>ENTERPROC</code> and <code>LEAVEPROC</code> must follow the same safety rules as for <code>JUMPSUB</code> and <code>RETURNSUB</code> in EIP-2315. In addition, the following constraints must be validated:</p> <ul> <li>Every<code>ENTERPROC</code> must be followed by a <code>LEAVEPROC</code> to delimit the bodies of <em>procedures</em>.</li> <li>There can be no nested <em>procedures</em>.</li> <li>There can be no jump into the body of a procedure (including its <code>LEAVEPROC</code>) from outside of that body.</li> <li>There can be no jump or step to <code>BEGINPROC</code> at all -- only <code>CALLPROC</code>.</li> <li>The specified <code>n_inputs</code> and <code>n_outputs</code> must be on the stack.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-12-13T00:00:00+00:00 2026-02-11T14:48:26+00:00 Ross Campbellhttps://github.com/z0r0z https://wg-eips.ritovision.com/4521/

Recommends a simple extension to make NFTs compatible with apps and contracts that handle fungibles.

<h2 id="abstract">Abstract</h2> <p>ERC-721, the popular standard for non-fungible tokens (NFTs), includes send functions, such as <code>transferFrom()</code> and <code>safeTransferFrom()</code>, but does not include a backwards-compatible <code>transfer()</code> found in fungible ERC-20 tokens. This standard provides references to add such a <code>transfer()</code>.</p> <h2 id="motivation">Motivation</h2> <p>This standard proposes a simple extension to allow NFTs to work with contracts designed to manage ERC-20s and many consumer wallets which expect to be able to execute a token <code>transfer()</code>. For example, if an NFT is inadvertently sent to a contract that typically handles ERC-20, that NFT will be locked. It should also simplify the task for contract programmers if they can rely on <code>transfer()</code> to both handle ERC-20 and NFTs.</p> <h2 id="specification">Specification</h2> <p>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> <p>The interface for ERC-4521 <code>transfer()</code> MUST conform to ERC-20 and resulting transfers MUST fire the <code>Transfer</code> event as described in ERC-721.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Replicating ERC-20 <code>transfer()</code> with just a minor change to accurately reflect that a unique <code>tokenId</code> rather than fungible sum is being sent is desirable for code simplicity and to make integration easier.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP does not introduce any known backward compatibility issues.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation of an ERC-4521 <code>transfer()</code>:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> ownerOf</span><span>[</span><span>tokenId</span><span>]</span><span>,</span><span class="z-string"> &quot;NOT_OWNER&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> unchecked</span><span> {</span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword">-</span><span class="z-keyword">-</span><span>;</span><span> </span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> balanceOf</span><span>[</span><span>to</span><span>]</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> getApproved</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> ownerOf</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span> to</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> success </span><span class="z-keyword">=</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Implementers must be sure to include the relevant return <code>bool</code> value for an ERC-4521 in order to conform with existing contracts that use ERC-20 interfaces, otherwise, NFTs may be locked unless a <code>safeTransfer</code> is used in such contracts.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-12-11T00:00:00+00:00 2026-02-11T14:48:25+00:00 Justice Hudsonhttps://github.com/jchancehud https://wg-eips.ritovision.com/4546/

A singleton contract for managing asset deposits.

<h2 id="abstract">Abstract</h2> <p>The wrapped deposit contract handles deposits of assets (Ether, <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>) on behalf of a user. A user must only approve a spend limit once and then an asset may be deposited to any number of different applications that support deposits from the contract.</p> <h2 id="motivation">Motivation</h2> <p>The current user flow for depositing assets in dapps is unnecessarily expensive and insecure. To deposit an ERC-20 asset a user must either:</p> <ul> <li>send an approve transaction for the exact amount being sent, before making a deposit, and then repeat this process for every subsequent deposit.</li> <li>send an approve transaction for an infinite spend amount before making deposits.</li> </ul> <p>The first option is inconvenient, and expensive. The second option is insecure. Further, explaining approvals to new or non-technical users is confusing. This has to be done in <em>every</em> dapp that supports ERC20 deposits.</p> <h2 id="specification">Specification</h2> <p>The wrapped deposit contract SHOULD be deployed at an identifiable address (e.g. <code>0x1111119a9e30bceadf9f939390293ffacef93fe9</code>). The contract MUST be non-upgradable with no ability for state variables to be changed.</p> <p>The wrapped deposit contract MUST have the following public functions:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">depositERC20</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> token</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> amount</span><span>)</span><span class="z-variable z-other"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">depositERC721</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> token</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> tokenId</span><span>)</span><span class="z-variable z-other"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">safeDepositERC721</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> token</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> tokenId</span><span>,</span><span class="z-variable z-other"> bytes</span><span class="z-variable z-other"> memory</span><span class="z-variable z-other"> data</span><span>)</span><span class="z-variable z-other"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">safeDepositERC1155</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> token</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> tokenId</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> value</span><span>,</span><span class="z-variable z-other"> bytes</span><span class="z-variable z-other"> calldata</span><span class="z-variable z-other"> data</span><span>)</span><span class="z-variable z-other"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">batchDepositERC1155</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> token</span><span>,</span><span class="z-variable z-other"> uint</span><span>[</span><span>]</span><span class="z-variable z-other"> calldata</span><span class="z-variable z-other"> tokenIds</span><span>,</span><span class="z-variable z-other"> uint</span><span>[</span><span>]</span><span class="z-variable z-other"> calldata</span><span class="z-variable z-other"> values</span><span>,</span><span class="z-variable z-other"> bytes</span><span class="z-variable z-other"> calldata</span><span class="z-variable z-other"> data</span><span>)</span><span class="z-variable z-other"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">depositEther</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> to</span><span>)</span><span class="z-variable z-other"> external</span><span class="z-variable z-other"> payable</span><span>;</span></span></code></pre> <p>Each of these functions MUST revert if <code>to</code> is an address with a zero code size. Each function MUST attempt to call a method on the <code>to</code> address confirming that it is willing and able to accept the deposit. If this function call does not return a true value execution MUST revert. If the asset transfer is not successful execution MUST revert.</p> <p>The following interfaces SHOULD exist for contracts wishing to accept deposits:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC20Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptERC20Deposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> amount</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC721Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptERC721Deposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1155Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptERC1155Deposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> value</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptERC1155BatchDeposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span>[</span><span>]</span><span class="z-variable"> calldata</span><span class="z-variable"> tokenIds</span><span>,</span><span class="z-variable"> uint</span><span>[</span><span>]</span><span class="z-variable"> calldata</span><span class="z-variable"> values</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EtherReceiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptEtherDeposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> amount</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A receiving contract MAY implement any of these functions as desired. If a given function is not implemented deposits MUST not be sent for that asset type.</p> <h2 id="rationale">Rationale</h2> <p>Having a single contract that processes all token transfers allows users to submit a single approval per token to deposit to any number of contracts. The user does not have to trust receiving contracts with token spend approvals and receiving contracts have their complexity reduced by not having to implement token transfers themselves.</p> <p>User experience is improved because a simple global dapp can be implemented with the messaging: "enable token for use in other apps".</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is not backward compatible. Any contract planning to use this deposit system must implement specific functions to accept deposits. Existing contracts that are upgradeable can add support for this EIP retroactively by implementing one or more accept deposit functions.</p> <p>Upgraded contracts can allow deposits using both the old system (approving the contract itself) and the proposed deposit system to preserve existing approvals. New users should be prompted to use the proposed deposit system.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-variable z-other">pragma</span><span class="z-variable z-other"> solidity</span><span class="z-keyword"> ^</span><span class="z-constant">0</span><span class="z-constant">.</span><span class="z-constant">7</span><span>.</span><span class="z-constant">0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC20Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptERC20Deposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> amount</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC721Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptERC721Deposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1155Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptERC1155Deposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> value</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptERC1155BatchDeposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span>[</span><span>]</span><span class="z-variable"> calldata</span><span class="z-variable"> tokenIds</span><span>,</span><span class="z-variable"> uint</span><span>[</span><span>]</span><span class="z-variable"> calldata</span><span class="z-variable"> values</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EtherReceiver</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> acceptEtherDeposit</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> depositor</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> amount</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> sender</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> recipient</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> amount</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC721</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _from</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _to</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _tokenId</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> payable</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeTransferFrom</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _from</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _to</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _tokenId</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> payable</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC1155</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeTransferFrom</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _from</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _to</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> _id</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> _value</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> _data</span><span>)</span><span class="z-entity z-name"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeBatchTransferFrom</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _from</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _to</span><span>,</span><span class="z-variable"> uint256</span><span>[</span><span>]</span><span class="z-variable"> calldata</span><span class="z-variable"> _ids</span><span>,</span><span class="z-variable"> uint256</span><span>[</span><span>]</span><span class="z-variable"> calldata</span><span class="z-variable"> _values</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> _data</span><span>)</span><span class="z-entity z-name"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> WrappedDeposit</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> depositERC20</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> amount</span><span>)</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _assertContract</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">ERC20Receiver</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>.</span><span class="z-entity z-name">acceptERC20Deposit</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> token</span><span>,</span><span class="z-variable z-other"> amount</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> bytes</span><span class="z-variable z-other"> memory</span><span class="z-variable z-other"> data</span><span class="z-keyword"> =</span><span class="z-variable z-other"> abi</span><span>.</span><span class="z-entity z-name">encodeWithSelector</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC20</span><span>(</span><span class="z-variable z-other">token</span><span>)</span><span>.</span><span class="z-variable z-other">transferFrom</span><span>.</span><span class="z-variable z-other">selector</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> amount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-variable z-other">bool</span><span class="z-variable z-other"> success</span><span>,</span><span class="z-variable z-other"> bytes</span><span class="z-variable z-other"> memory</span><span class="z-variable z-other"> returndata</span><span>)</span><span class="z-keyword"> =</span><span class="z-variable z-other"> token</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span class="z-variable z-other">data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">success</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> backward compat for tokens incorrectly implementing the transfer function</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">returndata</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">abi</span><span>.</span><span class="z-entity z-name">decode</span><span>(</span><span class="z-variable z-other">returndata</span><span>,</span><span> (</span><span class="z-variable z-other">bool</span><span>)</span><span>)</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC20 operation did not succeed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> depositERC721</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _assertContract</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">ERC721Receiver</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>.</span><span class="z-entity z-name">acceptERC721Deposit</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> token</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC721</span><span>(</span><span class="z-variable z-other">token</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeDepositERC721</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _assertContract</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">ERC721Receiver</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>.</span><span class="z-entity z-name">acceptERC721Deposit</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> token</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC721</span><span>(</span><span class="z-variable z-other">token</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>,</span><span class="z-variable z-other"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeDepositERC1155</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> value</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _assertContract</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">ERC1155Receiver</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>.</span><span class="z-entity z-name">acceptERC1155Deposit</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>,</span><span class="z-variable z-other"> value</span><span>,</span><span class="z-variable z-other"> data</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC1155</span><span>(</span><span class="z-variable z-other">token</span><span>)</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> tokenId</span><span>,</span><span class="z-variable z-other"> value</span><span>,</span><span class="z-variable z-other"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> batchDepositERC1155</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> uint</span><span>[</span><span>]</span><span class="z-variable"> calldata</span><span class="z-variable"> tokenIds</span><span>,</span><span class="z-variable"> uint</span><span>[</span><span>]</span><span class="z-variable"> calldata</span><span class="z-variable"> values</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _assertContract</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">ERC1155Receiver</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>.</span><span class="z-entity z-name">acceptERC1155BatchDeposit</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> tokenIds</span><span>,</span><span class="z-variable z-other"> values</span><span>,</span><span class="z-variable z-other"> data</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> IERC1155</span><span>(</span><span class="z-variable z-other">token</span><span>)</span><span>.</span><span class="z-entity z-name">safeBatchTransferFrom</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> tokenIds</span><span>,</span><span class="z-variable z-other"> values</span><span>,</span><span class="z-variable z-other"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> depositEther</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _assertContract</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">EtherReceiver</span><span>(</span><span class="z-variable z-other">to</span><span>)</span><span>.</span><span class="z-entity z-name">acceptEtherDeposit</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> msg</span><span>.</span><span class="z-variable z-other">value</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-variable z-other">bool</span><span class="z-variable z-other"> success</span><span>,</span><span> )</span><span class="z-keyword"> =</span><span class="z-variable z-other"> to</span><span>.</span><span class="z-variable z-other">call</span><span>{</span><span class="z-entity z-name">value</span><span>:</span><span class="z-variable z-other"> msg</span><span>.</span><span class="z-variable z-other">value</span><span>}</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">success</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nonpayable</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _assertContract</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> c</span><span>)</span><span class="z-entity z-name"> private</span><span class="z-entity z-name"> view</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> size</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> size</span><span> :</span><span class="z-keyword">=</span><span class="z-entity z-name"> extcodesize</span><span>(</span><span class="z-variable z-other">c</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">size</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">noncontract</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>The wrapped deposit implementation should be as small as possible to reduce the risk of bugs. The contract should be small enough that an engineer can read and understand it in a few minutes.</p> <p>Receiving contracts MUST verify that <code>msg.sender</code> is equal to the wrapped deposit contract. Failing to do so allows anyone to simulate deposits.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-12-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Aaron Chenhttps://github.com/aaronisme Sora Leehttps://github.com/soralit ligihttps://github.com/ligi Dan Millerhttps://github.com/danjm AndreasGassmannhttps://github.com/andreasgassmann xardasshttps://github.com/xardass Lixin Liuhttps://github.com/BitcoinLixin https://wg-eips.ritovision.com/4527/

QR Code data transmission protocol between wallets and offline signers.

<h2 id="abstract">Abstract</h2> <p>The purpose of this EIP is to provide a process and data transmission protocol via QR Code between offline signers and watch-only wallets.</p> <h2 id="motivation">Motivation</h2> <p>There is an increasing number of users whom like to use complete offline signers to manage their private keys, signers like hardware wallets and mobile phones in offline mode. In order to sign transactions or data, these offline signers have to rely on a watch-only wallet since it would prepare the data to be signed. Currently, there are 4 possible data transmission methods between offline signers and watch-only wallets: QR Code, USB, Bluetooth, and file transfer. The QR Code data transmission method have the following advantages when compared to the other three methods mentioned above:</p> <ul> <li>Transparency and Security: Compared to USB or Bluetooth, users can easily decode the data via QR Code (with the help of some tools). It can also help users clearly identify what they are going to sign, which improves transparency and thus better security.</li> <li>Improved Compatibility: Compared to USB and Bluetooth, QR Code data transmissions has a wider range of compatibility. Normally, it wouldn’t be broken by software changes like browser upgrades, system upgrade, and etc.</li> <li>Improved User experience: QR Code data transmissions can provide a better user experience compared to USB, Bluetooth, and file transfer especially when the user is using a mobile device.</li> <li>A smaller attack surface: USB and Bluetooth have a bigger attack surface than QR-Codes.</li> </ul> <p>Due to these advantages, QR Code data transmissions is a better choice. Unfortunately, there is no modern standard for how offline signers should work with watch-only wallets nor how data should be encoded. This EIP presents a standard process and data transmission protocol for offline signers to work with watch-only wallets.</p> <h2 id="specification">Specification</h2> <p><strong>Offline signer</strong>: An offline signer is a device or application which holds the user’s private keys and does not have network access.</p> <p><strong>Watch-only wallet</strong>: A watch-only wallet is a wallet that has network access and can interact with the Ethereum blockchain.</p> <h3 id="process">Process</h3> <p>In order to work with offline signers, the watch-only wallet should follow the following process.</p> <ol> <li>The offline signer provides the public key information to the watch-only wallet to generate addresses, sync balances and etc via QR Codes.</li> <li>The watch-only wallet generates the unsigned data and sends it to an offline signer for signing via QR Code, data that can include transactions, typed data, and etc.</li> <li>The offline signer signs the data and provides a signature back to the watch-only wallet via QR Code.</li> <li>The watch-only wallet receives the signature, constructs the signed data (transaction) and performs the following activities like broadcasting the transaction etc.</li> </ol> <h3 id="data-transmission-protocol">Data Transmission Protocol</h3> <p>Since a single QR Code can only contain a limited amount of data, animated QR Codes should be utilized for data transmission. The <code>BlockchainCommons</code> have published a series of data transmission protocol called Uniform Resources (UR). It provides a basic method to encode data into animated QR Codes. This EIP will use UR and extend its current definition.</p> <p><code>Concise Binary Object Representation(CBOR)</code> will be used for binary data encoding. <code>Concise Data Definition Language(CDDL)</code> will be used for expressing the CBOR.</p> <h3 id="setting-up-the-watch-only-wallet-with-the-offline-signer">Setting up the watch-only wallet with the offline signer</h3> <p>In order to allow a watch-only wallet to collect information from the Ethereum blockchain, the offline signer would need to provide the public keys to the watch-only wallet in which the wallet will use them to query the necessary information from the Ethereum blockchain.</p> <p>In such a case, offline signers should provide the extended public keys and derivation path. The UR Type called <code>crypto-hdkey</code> will be used to encode this data and the derivation path will be encoded as <code>crypto-keypath</code>.</p> <h4 id="cddl-for-key-path">CDDL for Key Path</h4> <p>The <code>crypto-keypath</code> will be used to specify the key path.The following specification is written in Concise Data Definition Language(CDDL) for <code>crypto-key-path</code></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>; Metadata for the derivation path of a key.</span></span> <span class="giallo-l"><span>;</span></span> <span class="giallo-l"><span>; `source-fingerprint`, if present, is the fingerprint of the</span></span> <span class="giallo-l"><span>; ancestor key from which the associated key was derived.</span></span> <span class="giallo-l"><span>;</span></span> <span class="giallo-l"><span>; If `components` is empty, then `source-fingerprint` MUST be a fingerprint of</span></span> <span class="giallo-l"><span>; a master key.</span></span> <span class="giallo-l"><span>;</span></span> <span class="giallo-l"><span>; `depth`, if present, represents the number of derivation steps in</span></span> <span class="giallo-l"><span>; the path of the associated key, even if not present in the `components` element</span></span> <span class="giallo-l"><span>; of this structure.</span></span> <span class="giallo-l"><span> crypto-keypath = {</span></span> <span class="giallo-l"><span> components: [path-component], ; If empty, source-fingerprint MUST be present</span></span> <span class="giallo-l"><span> ? source-fingerprint: uint32 .ne 0 ; fingerprint of ancestor key, or master key if components is empty</span></span> <span class="giallo-l"><span> ? depth: uint8 ; 0 if this is a public key derived directly from a master key</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> path-component = (</span></span> <span class="giallo-l"><span> child-index / child-index-range / child-index-wildcard-range,</span></span> <span class="giallo-l"><span> is-hardened</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> uint32 = uint .size 4</span></span> <span class="giallo-l"><span> uint31 = uint32 .lt 2147483648 ;0x80000000</span></span> <span class="giallo-l"><span> child-index = uint31</span></span> <span class="giallo-l"><span> child-index-range = [child-index, child-index] ; [low, high] where low &lt; high</span></span> <span class="giallo-l"><span> child-index-wildcard = []</span></span> <span class="giallo-l"><span> is-hardened = bool</span></span> <span class="giallo-l"><span> components = 1</span></span> <span class="giallo-l"><span> source-fingerprint = 2</span></span> <span class="giallo-l"><span> depth = 3</span></span></code></pre><h4 id="cddl-for-extended-public-keys">CDDL for Extended Public Keys</h4> <p>Since the purpose is to transfer public key data, the definition of <code>crypto-hdkey</code> will be kept only for public key usage purposes.</p> <p>The following specification is written in Concise Data Definition Language <code>CDDL</code> and includes the crypto-keypath spec above.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>; An hd-key must be a derived key.</span></span> <span class="giallo-l"><span>hd-key = {</span></span> <span class="giallo-l"><span> derived-key</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>; A derived key must be public, has an optional chain code, and</span></span> <span class="giallo-l"><span>; may carry additional metadata about its use and derivation.</span></span> <span class="giallo-l"><span>; To maintain isomorphism with [BIP32] and allow keys to be derived from</span></span> <span class="giallo-l"><span>; this key `chain-code`, `origin`, and `parent-fingerprint` must be present.</span></span> <span class="giallo-l"><span>; If `origin` contains only a single derivation step and also contains `source-fingerprint`,</span></span> <span class="giallo-l"><span>; then `parent-fingerprint` MUST be identical to `source-fingerprint` or may be omitted.</span></span> <span class="giallo-l"><span>derived-key = (</span></span> <span class="giallo-l"><span> key-data: key-data-bytes,</span></span> <span class="giallo-l"><span> ? chain-code: chain-code-bytes ; omit if no further keys may be derived from this key</span></span> <span class="giallo-l"><span> ? origin: #6.304(crypto-keypath), ; How the key was derived</span></span> <span class="giallo-l"><span> ? name: text, ; A short name for this key.</span></span> <span class="giallo-l"><span> ? source: text, ; The device info or any other description for this key</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>key-data = 3</span></span> <span class="giallo-l"><span>chain-code = 4</span></span> <span class="giallo-l"><span>origin = 6</span></span> <span class="giallo-l"><span>name = 9</span></span> <span class="giallo-l"><span>source = 10</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>uint8 = uint .size 1</span></span> <span class="giallo-l"><span>key-data-bytes = bytes .size 33</span></span> <span class="giallo-l"><span>chain-code-bytes = bytes .size 32</span></span></code></pre> <p>If the chain-code is provided, then it can be used to derive child keys but if it isn’t provided, it is simply a solo key and the origin can be provided to indicate the derivation key path.</p> <p>If the signer would like to provide multiple public keys instead of the extended public key for any reason, the signer can use <code>crypto-account</code> for that.</p> <h3 id="sending-the-unsigned-data-from-the-watch-only-wallet-to-the-offline-signer">Sending the unsigned data from the watch-only wallet to the offline signer</h3> <p>To send the unsigned data from a watch-only wallet to an offline signer, the new UR type <code>eth-sign-request</code> will be introduced to encode the signing request.</p> <h4 id="cddl-for-eth-sign-request">CDDL for Eth Sign Request.</h4> <p>The following specification is written in Concise Data Definition Language <code>CDDL</code>. UUIDs in this specification notated UUID are CBOR binary strings tagged with #6.37, per the IANA <code>CBOR Tags Registry</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>; Metadata for the signing request for Ethereum.</span></span> <span class="giallo-l"><span>; </span></span> <span class="giallo-l"><span>sign-data-type = {</span></span> <span class="giallo-l"><span> type: int .default 1 transaction data; the unsigned data type</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>eth-transaction-data = 1; legacy transaction rlp encoding of unsigned transaction data</span></span> <span class="giallo-l"><span>eth-typed-data = 2; EIP-712 typed signing data</span></span> <span class="giallo-l"><span>eth-raw-bytes=3; for signing message usage, like EIP-191 personal_sign data</span></span> <span class="giallo-l"><span>eth-typed-transaction=4; EIP-2718 typed transaction of unsigned transaction data</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>; Metadata for the signing request for Ethereum.</span></span> <span class="giallo-l"><span>; request-id: the identifier for this signing request.</span></span> <span class="giallo-l"><span>; sign-data: the unsigned data</span></span> <span class="giallo-l"><span>; data-type: see sign-data-type definition</span></span> <span class="giallo-l"><span>; chain-id: chain id definition see https://github.com/ethereum-lists/chains for detail</span></span> <span class="giallo-l"><span>; derivation-path: the key path of the private key to sign the data</span></span> <span class="giallo-l"><span>; address: Ethereum address of the signing type for verification purposes which is optional</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>eth-sign-request = (</span></span> <span class="giallo-l"><span> sign-data: sign-data-bytes, ; sign-data is the data to be signed by offline signer, currently it can be unsigned transaction or typed data</span></span> <span class="giallo-l"><span> data-type: #3.401(sign-data-type),</span></span> <span class="giallo-l"><span> chain-id: int .default 1,</span></span> <span class="giallo-l"><span> derivation-path: #5.304(crypto-keypath), ;the key path for signing this request</span></span> <span class="giallo-l"><span> ?request-id: uuid, ; the uuid for this signing request</span></span> <span class="giallo-l"><span> ?address: eth-address-bytes, ;verification purpose for the address of the signing key</span></span> <span class="giallo-l"><span> ?origin: text ;the origin of this sign request, like wallet name</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>request-id = 1</span></span> <span class="giallo-l"><span>sign-data = 2</span></span> <span class="giallo-l"><span>data-type = 3</span></span> <span class="giallo-l"><span>chain-id = 4 ;it will be the chain id of ethereum related blockchain</span></span> <span class="giallo-l"><span>derivation-path = 5</span></span> <span class="giallo-l"><span>address = 6</span></span> <span class="giallo-l"><span>origin = 7</span></span> <span class="giallo-l"><span>eth-address-bytes = bytes .size 20</span></span> <span class="giallo-l"><span>sign-data-bytes = bytes ; for unsigned transactions it will be the rlp encoding for unsigned transaction data and ERC 712 typed data it will be the bytes of json string.</span></span></code></pre><h3 id="the-signature-provided-by-offline-signers-to-watch-only-wallets">The signature provided by offline signers to watch-only wallets</h3> <p>After the data is signed, the offline signer should send the signature back to the watch-only wallet. The new UR type called <code>eth-signature</code> is introduced here to encode this data.</p> <h4 id="cddl-for-eth-signature">CDDL for Eth Signature.</h4> <p>The following specification is written in Concise Data Definition Language <code>CDDL</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>eth-signature = (</span></span> <span class="giallo-l"><span> request-id: uuid,</span></span> <span class="giallo-l"><span> signature: eth-signature-bytes,</span></span> <span class="giallo-l"><span> ? origin: text, ; The device info for providing this signature</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>request-id = 1</span></span> <span class="giallo-l"><span>signature = 2</span></span> <span class="giallo-l"><span>origin = 3</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>eth-signature-bytes = bytes .size 65; the signature of the signing request (r,s,v)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This EIP uses some existing UR types like <code>crypto-keypath</code> and <code>crypto-hdkey</code> and also introduces some new UR types like <code>eth-sign-request</code> and <code>eth-signature</code>. Here are the reasons we choose UR for the QR Code data transmission protocol:</p> <h3 id="ur-provides-a-solid-foundation-for-qr-code-data-transmission">UR provides a solid foundation for QR Code data transmission</h3> <ul> <li>Uses the alphanumeric QR code mode for efficiency.</li> <li>Includes a CRC32 checksum of the entire message in each part to tie the different parts of the QR code together and ensure the transmitted message has been reconstructed.</li> <li>uses <code>Fountain Code</code> for the arbitrary amount of data which can be both a minimal, finite sequence of parts and an indefinite sequence of parts. The Fountain Code can ultimately help the receiver to make the data extraction easier.</li> </ul> <h3 id="ur-provides-existing-helpful-types-and-scalability-for-new-usages">UR provides existing helpful types and scalability for new usages</h3> <p>Currently, UR has provided some existing types like <code>crypto-keypath</code> and <code>crypto-hdkey</code> so it is quite easy to add a new type and definitions for new usages.</p> <h3 id="ur-has-an-active-air-gapped-wallet-community">UR has an active air-gapped wallet community.</h3> <p>Currently, the UR has an active <code>airgapped wallet community</code> which continues to improve the UR forward.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Currently, there is no existing protocol to define data transmissions via QR Codes so there are no backward compatibility issues that needs to be addressed now.</p> <h2 id="test-cases">Test Cases</h2> <p>The test cases can be found on the <code>ur-registry-eth</code> package released by the Keystone team.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>The reference implementation can be found on the <code>ur-registry-eth</code> package released by the Keystone team.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The offline signer should decode all the data from <code>eth-sign-request</code> and show them to the user for confirmation prior to signing. It is recommended to provide an address field in the <code>eth-sign-request</code>. If provided, the offline signer should verify the address being the same one as the address associated with the signing key.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-12-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 William Schwabhttps://github.com/wschwab https://wg-eips.ritovision.com/4524/

Extending ERC-20 with ERC165 and adding safeTransfer (like ERC-721 and ERC-1155)

<h2 id="abstract">Abstract</h2> <p>This standard extends <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens with <a href="https://wg-eips.ritovision.com/165/">EIP-165</a>, and adds familiar functions from <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> ensuring receiving contracts have implemented proper functionality.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/165/">EIP-165</a> adds (among other things) the ability to tell if a target recipient explicitly signals compatibility with an ERC. This is already used in the EIPs for NFTs, <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>. In addition, EIP-165 is a valuable building block for extensions on popular standards to signal implementation, a trend we've seen in a number of NFT extensions. This EIP aims to bring these innovations back to ERC-20.</p> <p>The importance of <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> is perhaps felt most for app developers looking to integrate with a generic standard such as ERC-20 or ERC-721, while integrating newer innovations built atop these standards. An easy example would be token permits, which allow for a one-transaction approval and transfer. This has already been implemented in many popular ERC-20 tokens using the <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> standard or similar. A platform integrating ERC-20 tokens has no easy way of telling if a particular token has implemented token permits or not. (As of this writing, ERC-2612 does not require EIP-165.) With EIP-165, the app (or contracts) could query <code>supportsInterface</code> to see if the <code>interfaceId</code> of a particular EIP is registered (in this case, EIP-2612), allowing for easier and more modular functions interacting with ERC-20 contracts. It is already common in NFT extensions to include an EIP-165 interface with a standard, we would argue this is at least in part due to the underlying <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> standards integrating EIP-165. Our hope is that this extension to ERC-20 would also help future extensions by making them easier to integrate.</p> <h2 id="specification">Specification</h2> <p>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> <p>In order to be compliant with this EIP, and ERC-20-compliant contract MUST also implement the following functions:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> 0.8.10</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;./IERC20.sol&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;./IERC165.sol&#39;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> the EIP-165 interfaceId for this interface is 0x534f5876</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> SaferERC</span><span class="z-keyword">-</span><span class="z-constant">20</span><span> is IERC20</span><span>,</span><span> IERC165 </span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeTransfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeTransferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeTransferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>safeTransfer</code> and <code>safeTransferFrom</code> MUST transfer as expected to EOA addresses, and to contracts implementing <code>ERC20Receiver</code> and returning the function selector (<code>0x4fc35859</code>) when called, and MUST revert when transferring to a contract which either does not have <code>ERC20Receiver</code> implemented, or does not return the function selector when called.</p> <p>In addition, a contract accepting safe transfers MUST implement the following if it wishes to accept safe transfers, and MUST return the function selector (<code>0x4fc35859</code>):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> 0.8.10</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;./IERC165.sol&#39;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC20Receiver</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onERC20Received</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _operator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable z-parameter z-function"> _data</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes4</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This EIP is meant to be minimal and straightforward. Adding EIP-165 to ERC-20 is useful for a number of applications, and outside of a minimal amount of code increasing contract size, carries no downside. The <code>safeTransfer</code> and <code>safeTransferFrom</code> functions are well recognized from ERC-721 and ERC-1155, and therefore keeping identical naming conventions is reasonable, and the benefits of being able to check for implementation before transferring are as useful for ERC-20 tokens as they are for ERC-721 and ERC-1155.</p> <p>Another easy backport from EIP721 and EIP1155 might be the inclusion of a metadata URI for tokens, allowing them to easily reference logo and other details. This has not been included, both in order to keep this EIP as minimal as possible, and because it is already sufficiently covered by <a href="https://wg-eips.ritovision.com/1046/">EIP-1046</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no issues with backwards compatibility in this EIP, as the full suite of ERC-20 functions is unchanged.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases have been provided in the implementation repo <a rel="external" href="https://github.com/wschwab/SaferERC-20/blob/main/src/SaferERC-20.t.sol">here</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A sample repo demonstrating an implementation of this EIP has been created <a rel="external" href="https://github.com/wschwab/SaferERC-20">here</a>. It is (as of this writing) in a Dapptools environment, for details on installing and running Dapptools see the Dapptools repo.</p> <h2 id="security-considerations">Security Considerations</h2> <p><code>onERC20Received</code> is a callback function. Callback functions have been exploited in the past as a reentrancy vector, and care should be taken to make sure implementations are not vulnerable.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-12-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Brayton Goodallhttps://github.com/Spore-Druid-Bray Mihir Faujdarhttps://github.com/uink45 https://wg-eips.ritovision.com/4520/

Reserve `0xEB` and `0xEC` for usage as extended opcode space.

<h2 id="abstract">Abstract</h2> <p>Reserve <code>0xEB</code> and <code>0xEC</code> for usage as extended opcode space.</p> <h2 id="motivation">Motivation</h2> <p>It would be convenient to introduce new opcodes that are likely to be infrequently used, whilst also being able to have greater than 256 opcodes in total. As a single byte opcode is half the size of a double byte opcode, the greatest efficiency in code sizes will be one where frequently used opcodes are single bytes. Two prefix bytes are used to accommodate up to 510 double byte opcodes.</p> <h2 id="specification">Specification</h2> <p>For example, a new arithmetic opcode may be allocated to <code>0xEC 01</code>(<code>ADD</code>), and a novel opcode may be introduced at <code>0xEB F4</code>(<code>DELEGATECALL</code>).</p> <p>Triple byte opcodes may be doubly-prefixed by <code>0xEB EB</code>, <code>0xEC EC</code>, <code>0xEB EC</code> and <code>0xEC EB</code>. It is possible to allocate experimental opcodes to this triple-byte space initially, and if they prove safe and useful, they could later be allocated a location in double-byte or single-byte space.</p> <p>Only <code>0xEB EB</code>, <code>0xEC EC</code>, <code>0xEC EC</code>, and <code>0xEB EC</code> may be interpreted as further extensions of the opcode space. <code>0xEB</code> and <code>0xEC</code> do not themselves affect the stack or memory, however opcodes specified by further bytes may. If a multi-byte opcode is yet to be defined, it is to be treated as <code>INVALID</code> rather than as a <code>NOP</code>, as per usual for undefined opcodes.</p> <h2 id="rationale">Rationale</h2> <p>It was considered that two prefix bytes rather than one would be adequate for reservation as extension addresses. Both <code>0xEB</code> and <code>0xEC</code> were chosen to be part of the E-series of opcodes. For example, the <code>0xEF</code> byte is reserved for contracts conforming to the Ethereum Object Format. By having unassigned opcodes for extending the opcode space, there will be a lower risk of breaking the functionalities of deployed contracts compared to choosing assigned opcodes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Previous usage of <code>0xEB</code> and <code>0xEC</code> may result in unexpected behaviour and broken code.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no known security considerations.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-11-25T00:00:00+00:00 2026-02-11T14:48:26+00:00 Simon Fremauxhttps://github.com/dievardump William Schwabhttps://github.com/wschwab https://wg-eips.ritovision.com/4494/

ERC-712-singed approvals for ERC-721 NFTs

<h2 id="abstract">Abstract</h2> <p>The "Permit" approval flow outlined in <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> has proven a very valuable advancement in UX by creating gasless approvals for ERC20 tokens. This EIP extends the pattern to ERC-721 NFTs. This EIP borrows heavily from ERC-2612.</p> <p>This requires a separate EIP due to the difference in structure between ERC-20 and ERC-721 tokens. While ERC-20 permits use value (the amount of the ERC-20 token being approved) and a nonce based on the owner's address, ERC-721 permits focus on the <code>tokenId</code> of the NFT and increment nonce based on the transfers of the NFT.</p> <h2 id="motivation">Motivation</h2> <p>The permit structure outlined in <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> allows for a signed message (structured as outlined in <a href="https://wg-eips.ritovision.com/712/">ERC-712</a>) to be used in order to create an approval. Whereas the normal approval-based pull flow generally involves two transactions, one to approve a contract and a second for the contract to pull the asset, which is poor UX and often confuses new users, a permit-style flow only requires signing a message and a transaction. Additional information can be found in <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>.</p> <p><a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> only outlines a permit architecture for ERC-20 tokens. This ERC proposes an architecture for ERC-721 NFTs, which also contain an approve architecture that would benefit from a signed message-based approval flow.</p> <h2 id="specification">Specification</h2> <p>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> <p>Three new functions MUST be added to <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> 0.8.10</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface for token permits for ERC-721</span></span> <span class="giallo-l"><span class="z-comment">///</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC4494</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> ERC165 bytes to add to interface array - set in parent contract</span></span> <span class="giallo-l"><span class="z-comment"> ///</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> _INTERFACE_ID_ERC4494 = 0x5604e225</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Function to approve by way of owner signature</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> spender</span><span class="z-comment"> the address to approve</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> the index of the NFT to approve the spender on</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> deadline</span><span class="z-comment"> a timestamp expiry for the permit</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sig</span><span class="z-comment"> a traditional or EIP-2098 signature</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> permit</span><span>(</span><span class="z-support">address</span><span class="z-variable"> spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> deadline</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sig</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the nonce of an NFT - useful for creating permits</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> the index of the NFT to get the nonce of</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> uint256 representation of the nonce</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> nonces</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the domain separator used in the encoding of the signature for permits, as defined by EIP-712</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> bytes32 domain separator</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> DOMAIN_SEPARATOR</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The semantics of which are as follows:</p> <p>For all addresses <code>spender</code>, <code>uint256</code>s <code>tokenId</code>, <code>deadline</code>, and <code>nonce</code>, and <code>bytes</code> <code>sig</code>, a call to <code>permit(spender, tokenId, deadline, sig)</code> MUST set <code>spender</code> as approved on <code>tokenId</code> as long as the owner of <code>tokenId</code> remains in possession of it, and MUST emit a corresponding <code>Approval</code> event, if and only if the following conditions are met:</p> <ul> <li>the current blocktime is less than or equal to <code>deadline</code></li> <li>the owner of the <code>tokenId</code> is not the zero address</li> <li><code>nonces[tokenId]</code> is equal to <code>nonce</code></li> <li><code>sig</code> is a valid <code>secp256k1</code> or <a href="https://wg-eips.ritovision.com/2098/">EIP-2098</a> signature from owner of the <code>tokenId</code>:</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>keccak256(abi.encodePacked(</span></span> <span class="giallo-l"><span> hex&quot;1901&quot;,</span></span> <span class="giallo-l"><span> DOMAIN_SEPARATOR,</span></span> <span class="giallo-l"><span> keccak256(abi.encode(</span></span> <span class="giallo-l"><span> keccak256(&quot;Permit(address spender,uint256 tokenId,uint256 nonce,uint256 deadline)&quot;),</span></span> <span class="giallo-l"><span> spender,</span></span> <span class="giallo-l"><span> tokenId,</span></span> <span class="giallo-l"><span> nonce,</span></span> <span class="giallo-l"><span> deadline))</span></span> <span class="giallo-l"><span>));</span></span></code></pre> <p>where <code>DOMAIN_SEPARATOR</code> MUST be defined according to <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>. The <code>DOMAIN_SEPARATOR</code> should be unique to the contract and chain to prevent replay attacks from other domains, and satisfy the requirements of EIP-712, but is otherwise unconstrained. A common choice for <code>DOMAIN_SEPARATOR</code> is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>DOMAIN_SEPARATOR = keccak256(</span></span> <span class="giallo-l"><span> abi.encode(</span></span> <span class="giallo-l"><span> keccak256(&#39;EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)&#39;),</span></span> <span class="giallo-l"><span> keccak256(bytes(name)),</span></span> <span class="giallo-l"><span> keccak256(bytes(version)),</span></span> <span class="giallo-l"><span> chainid,</span></span> <span class="giallo-l"><span> address(this)</span></span> <span class="giallo-l"><span>));</span></span></code></pre> <p>In other words, the message is the following ERC-712 typed structure:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">types</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">EIP712Domain</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">chainId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">verifyingContract</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Permit</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">spender</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tokenId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nonce</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">deadline</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">primaryType</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Permit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">domain</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-invalid z-illegal"> e</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">c</span><span class="z-constant">721</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">m</span><span class="z-invalid z-illegal">e</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">version</span><span class="z-support">&quot;</span><span>:</span><span class="z-invalid z-illegal"> v</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">n</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-invalid z-illegal"> c</span><span class="z-invalid z-illegal">h</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">d</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">verifyingContract</span><span class="z-support">&quot;</span><span>:</span><span class="z-invalid z-illegal"> t</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">k</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">A</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal">s</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">spender</span><span class="z-support">&quot;</span><span>:</span><span class="z-invalid z-illegal"> s</span><span class="z-invalid z-illegal">p</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">r</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-invalid z-illegal"> v</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">u</span><span class="z-invalid z-illegal">e</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nonce</span><span class="z-support">&quot;</span><span>:</span><span class="z-invalid z-illegal"> n</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">e</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">deadline</span><span class="z-support">&quot;</span><span>:</span><span class="z-invalid z-illegal"> d</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">e</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span><span>}</span></span></code></pre> <p>In addition:</p> <ul> <li>the <code>nonce</code> of a particular <code>tokenId</code> (<code>nonces[tokenId]</code>) MUST be incremented upon any transfer of the <code>tokenId</code></li> <li>the <code>permit</code> function MUST check that the signer is not the zero address</li> </ul> <p>Note that nowhere in this definition do we refer to <code>msg.sender</code>. The caller of the <code>permit</code> function can be any address.</p> <p>This EIP requires <a href="https://wg-eips.ritovision.com/165/">EIP-165</a>. EIP165 is already required in <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, but is further necessary here in order to register the interface of this EIP. Doing so will allow easy verification if an NFT contract has implemented this EIP or not, enabling them to interact accordingly. The interface of this EIP (as defined in EIP-165) is <code>0x5604e225</code>. Contracts implementing this EIP MUST have the <code>supportsInterface</code> function return <code>true</code> when called with <code>0x5604e225</code>.</p> <h2 id="rationale">Rationale</h2> <p>The <code>permit</code> function is sufficient for enabling a <code>safeTransferFrom</code> transaction to be made without the need for an additional transaction.</p> <p>The format avoids any calls to unknown code.</p> <p>The <code>nonces</code> mapping is given for replay protection.</p> <p>A common use case of permit has a relayer submit a Permit on behalf of the owner. In this scenario, the relaying party is essentially given a free option to submit or withhold the Permit. If this is a cause of concern, the owner can limit the time a Permit is valid for by setting deadline to a value in the near future. The deadline argument can be set to uint(-1) to create Permits that effectively never expire.</p> <p>ERC-712 typed messages are included because of its use in <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a>, which in turn cites widespread adoption in many wallet providers.</p> <p>While ERC-2612 focuses on the value being approved, this EIP focuses on the <code>tokenId</code> of the NFT being approved via <code>permit</code>. This enables a flexibility that cannot be achieved with ERC-20 (or even <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>) tokens, enabling a single owner to give multiple permits on the same NFT. This is possible since each ERC-721 token is discrete (oftentimes referred to as non-fungible), which allows assertion that this token is still in the possession of the <code>owner</code> simply and conclusively.</p> <p>Whereas ERC-2612 splits signatures into their <code>v,r,s</code> components, this EIP opts to instead take a <code>bytes</code> array of variable length in order to support <a href="https://wg-eips.ritovision.com/2098/">EIP-2098</a> signatures (64 bytes), which cannot be easily separated or reconstructed from <code>r,s,v</code> components (65 bytes).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are already some ERC-721 contracts implementing a <code>permit</code>-style architecture, most notably Uniswap v3.</p> <p>Their implementation differs from the specification here in that:</p> <ul> <li>the <code>permit</code> architecture is based on <code>owner</code></li> <li>the <code>nonce</code> is incremented at the time the <code>permit</code> is created</li> <li>the <code>permit</code> function must be called by the NFT owner, who is set as the <code>owner</code></li> <li>the signature is split into <code>r,s,v</code> instead of <code>bytes</code></li> </ul> <p>Rationale for differing on design decisions is detailed above.</p> <h2 id="test-cases">Test Cases</h2> <p>Basic test cases for the reference implementation can be found <a rel="external" href="https://github.com/dievardump/erc721-with-permits/tree/main/test">here</a>.</p> <p>In general, test suites should assert at least the following about any implementation of this EIP:</p> <ul> <li>the nonce is incremented after each transfer</li> <li><code>permit</code> approves the <code>spender</code> on the correct <code>tokenId</code></li> <li>the permit cannot be used after the NFT is transferred</li> <li>an expired permit cannot be used</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation has been set up <a rel="external" href="https://github.com/dievardump/erc721-with-permits">here</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Extra care should be taken when creating transfer functions in which <code>permit</code> and a transfer function can be used in one function to make sure that invalid permits cannot be used in any way. This is especially relevant for automated NFT platforms, in which a careless implementation can result in the compromise of a number of user assets.</p> <p>The remaining considerations have been copied from <a href="https://wg-eips.ritovision.com/2612/">ERC-2612</a> with minor adaptation, and are equally relevant here:</p> <p>Though the signer of a <code>Permit</code> may have a certain party in mind to submit their transaction, another party can always front run this transaction and call <code>permit</code> before the intended party. The end result is the same for the <code>Permit</code> signer, however.</p> <p>Since the ecrecover precompile fails silently and just returns the zero address as <code>signer</code> when given malformed messages, it is important to ensure <code>ownerOf(tokenId) != address(0)</code> to avoid <code>permit</code> from creating an approval to any <code>tokenId</code> which does not have an approval set.</p> <p>Signed <code>Permit</code> messages are censorable. The relaying party can always choose to not submit the <code>Permit</code> after having received it, withholding the option to submit it. The <code>deadline</code> parameter is one mitigation to this. If the signing party holds ETH they can also just submit the <code>Permit</code> themselves, which can render previously signed <code>Permit</code>s invalid.</p> <p>The standard <a rel="external" href="https://swcregistry.io/docs/SWC-114">ERC-20 race condition for approvals</a> applies to <code>permit</code> as well.</p> <p>If the <code>DOMAIN_SEPARATOR</code> contains the <code>chainId</code> and is defined at contract deployment instead of reconstructed for every signature, there is a risk of possible replay attacks between chains in the event of a future chain split.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-11-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/4488/

Greatly decreases the gas cost of transaction calldata and simultaneously caps total transaction calldata in a block

<h2 id="abstract">Abstract</h2> <p>Decrease transaction calldata gas cost, and add a limit of how much total transaction calldata can be in a block.</p> <h2 id="motivation">Motivation</h2> <p>Rollups are in the short and medium term, and possibly the long term, the only trustless scaling solution for Ethereum. Transaction fees on L1 have been very high for months and there is greater urgency in doing anything required to help facilitate an ecosystem-wide move to rollups. Rollups are significantly reducing fees for many Ethereum users: Optimism and Arbitrum frequently provide fees that are ~3-8x lower than the Ethereum base layer itself, and ZK rollups, which have better data compression and can avoid including signatures, have fees ~40-100x lower than the base layer.</p> <p>However, even these fees are too expensive for many users. The long-term solution to the long-term inadequacy of rollups by themselves has always been <a rel="external" href="https://github.com/ethereum/consensus-specs#sharding">data sharding</a>, which would add ~1-2 MB/sec of dedicated data space for rollups to the chain. However, data sharding will still take a considerable amount of time to finish implementing and deploying. Hence, a short-term solution to further cut costs for rollups, and to incentivize an ecosystem-wide transition to a rollup-centric Ethereum, is desired.</p> <p>This EIP presents a quick-to-implement short-term solution that also mitigates security risks.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th></tr></thead><tbody> <tr><td><code>NEW_CALLDATA_GAS_COST</code></td><td><code>3</code></td></tr> <tr><td><code>BASE_MAX_CALLDATA_PER_BLOCK</code></td><td><code>1,048,576</code></td></tr> <tr><td><code>CALLDATA_PER_TX_STIPEND</code></td><td><code>300</code></td></tr> </tbody></table> <p>Reduce the gas cost of transaction calldata to <code>NEW_CALLDATA_GAS_COST</code> per byte, regardless of whether the byte is zero or nonzero.</p> <p>Add a rule that a block is only valid if <code>sum(len(tx.calldata) for tx in block.txs) &lt;= BASE_MAX_CALLDATA_PER_BLOCK + len(block.txs) * CALLDATA_PER_TX_STIPEND</code>.</p> <h2 id="rationale">Rationale</h2> <p>A natural alternative proposal is to decrease <code>NEW_CALLDATA_GAS_COST</code> without adding a limit. However, this presents a security concern: today, the average block size <a rel="external" href="https://etherscan.io/chart/blocksize">is 60-90 kB</a>, but the <em>maximum</em> block size is <code>30M / 16 = 1,875,000</code> bytes (plus about a kilobyte of block and tx overhead). Simply decreasing the calldata gas cost from 16 to 3 would increase the maximum block size to 10M bytes. This would push the Ethereum p2p networking layer to unprecedented levels of strain and risk breaking the network; some previous live tests of ~500 kB blocks a few years ago had already taken down a few bootstrap nodes.</p> <p>The decrease-cost-and-cap proposal achieves most of the benefits of the decrease, as rollups are unlikely to <em>dominate</em> Ethereum block space in the short term future and so 1.5 MB will be sufficient, while preventing most of the security risk.</p> <p>Historically, the Ethereum protocol community has been suspicious of multi-dimensional resource limit rules (in this case, gas and calldata) because such rules greatly increase the complexity of the block packing problem that proposers (today miners, post-merge validators) need to solve. Today, proposers can generate blocks with near-optimal fee revenue by simply choosing transactions in highest-to-lowest order of priority fee. In a multi-dimensional world, proposers would have to deal with multi-dimensional constraints. Multi-dimensional knapsack problems are much more complicated than the single-dimensional equivalent, and well-optimized proprietary implementations built by pools may well outperform default open source implementations.</p> <p>Today, there are two key reasons why this is less of a problem than before:</p> <ol> <li><a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> means that, at least most of the time, the problem that block proposers are solving is <em>not</em> a knapsack problem. Rather, block proposers are simply including all the transactions they can find with sufficient base fee and priority fee. Hence, naive algorithms will also frequently generate close-to-optimal results.</li> <li>The existence of sophisticated proprietary strategies for miner extractable value (MEV) extraction means that decentralized optimal block production is already in the medium and long term a lost cause. Research is instead going into solutions that separate away the specialization-friendly task of block body generation from the role of a validator ("proposer/builder separation"). Instead of being a fundamental change, two-dimensional knapsack problems today would be merely "yet another" MEV opportunity.</li> </ol> <p>Hence, it's worth rethinking the historical opposition to multi-dimensional resource limits and considering them as a pragmatic way to simultaneously achieve moderate scalability gains while retaining security.</p> <p>Additionally, the stipend mechanism makes the two-dimensional optimization problem even less of an issue in practice. 90% of all transactions (<a href="https://wg-eips.ritovision.com/4488/./assets/gas_and_calldata_sample.csv">sample</a> taken from blocks <code>13500000, 13501000 ... 13529000</code>) have &lt;300 bytes of calldata. Hence, if a naive transaction selection algorithm overfills the calldata of a block that the proposer is creating, the proposer will still be able to keep adding transactions from 90% of their mempool.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a backwards incompatible gas repricing that requires a scheduled network upgrade.</p> <p>Users will be able to continue operating with no changes.</p> <p>Miners will be able to continue operating with no changes except for a rule to stop adding new transactions into a block when the total calldata size reaches the maximum. However, there are pragmatic heuristics that they could add to achieve closer-to-optimal returns in such cases: for example, if a block fills up to the size limit, they could repeatedly remove the last data-heavy transaction and replace it with as many data-light transactions as possible, until doing so is no longer profitable.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The <em>burst</em> data capacity of the chain does not increase as a result of this proposal (in fact, it slightly decreases). However, the <em>average</em> data capacity will increase. This means that the storage requirements of history-storing will go up. A worst-case scenario would be a theoretical long-run maximum of ~1,262,861 bytes per 12 sec slot, or ~3.0 TB per year.</p> <p>We recommend <a href="https://wg-eips.ritovision.com/4444/">EIP-4444</a> or some similar history expiry proposal be implemented either at the same time or soon after this EIP to mitigate this risk.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-11-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Richard Moorehttps://github.com/ricmoo Nick Johnsonhttps://github.com/arachnid https://wg-eips.ritovision.com/4430/

A technique for contracts to provide a human-readable description of a transaction's side-effects.

<h2 id="abstract">Abstract</h2> <p>Use a contract method to provide <em>virtual functions</em> which can generate a human-readable description at the same time as the machine-readable bytecode, allowing the user to agree to the human-readable component in a UI while the machine can execute the bytecode once accepted.</p> <h2 id="motivation">Motivation</h2> <p>When using an Ethereum Wallet (e.g. MetaMask, Clef, Hardware Wallets) users must accept a transaction before it can be submitted (or the user may decline).</p> <p>Due to the complexity of Ethereum transactions, wallets are very limited in their ability to provide insight into the effects of a transaction that the user is approving; outside special-cased support for common transactions such as ERC20 transfers, this often amounts to asking the user to sign an opaque blob of binary data.</p> <p>This EIP presents a method for dapp developers to enable a more comfortable user experience by providing wallets with a means to generate a better description about what the contract claims will happen.</p> <p>It does not address malicious contracts which wish to lie, it only addresses honest contracts that want to make their user's life better. We believe that this is a reasonable security model, as transaction descriptions can be audited at the same time as contract code, allowing auditors and code reviewers to check that transaction descriptions are accurate as part of their review.</p> <h2 id="specification">Specification</h2> <p>The <strong>description</strong> (a string) and the matching <strong>execcode</strong> (bytecode) are generated simultaneously by evaluating the method on a contract:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> eipXXXDescribe</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> inputs</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> reserved</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable"> description</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> execcode</span><span>)</span></span></code></pre> <p>The human-readable <strong>description</strong> can be shown in any client which supports user interaction for approval, while the <strong>execcode</strong> is the data that should be included in a transaction to the contract to perform that operation.</p> <p>The method must be executable in a static context, (i.e. any side effects, such as logX, sstore, etc.), including through indirect calls may be ignored.</p> <p>During evaluation, the <code>ADDRESS</code> (i.e. <code>to</code>), <code>CALLER</code> (i.e. <code>from</code>), <code>VALUE</code>, and <code>GASPRICE</code> must be the same as the values for the transaction being described, so that the code generating the description can rely on them.</p> <p>When executing the bytecode, best efforts should be made to ensure <code>BLOCKHASH</code>, <code>NUMBER</code>, <code>TIMESTAMP</code> and <code>DIFFICULTY</code> match the <code>"latest"</code> block. The <code>COINBASE</code> should be the zero address.</p> <p>The method may revert, in which case the signing must be aborted.</p> <h2 id="rationale">Rationale</h2> <h3 id="meta-description">Meta Description</h3> <p>There have been many attempts to solve this problem, many of which attempt to examine the encoded transaction data or message data directly.</p> <p>In many cases, the information that would be necessary for a meaningful description is not present in the final encoded transaction data or message data.</p> <p>Instead this EIP uses an indirect description of the data.</p> <p>For example, the <code>commit(bytes32)</code> method of ENS places a commitment <strong>hash</strong> on-chain. The hash contains the <strong>blinded</strong> name and address; since the name is blinded, the encoded data (i.e. the hash) no longer contains the original values and is insufficient to access the necessary values to be included in a description.</p> <p>By instead describing the commitment indirectly (with the original information intact: NAME, ADDRESS and SECRET) a meaningful description can be computed (e.g. "commit to NAME for ADDRESS (with SECRET)") and the matching data can be computed (i.e. <code>commit(hash(name, owner, secret))</code>).</p> <p>This technique of blinded data will become much more popular with L2 solutions, which use blinding not necessarily for privacy, but for compression.</p> <h3 id="entangling-the-contract-address">Entangling the Contract Address</h3> <p>To prevent signed data being used across contracts, the contract address is entanlged into both the transaction implicitly via the <code>to</code> field.</p> <h3 id="alternatives">Alternatives</h3> <ul> <li> <p>NatSpec and company are a class of more complex languages that attempt to describe the encoded data directly. Because of the language complexity they often end up being quite large requiring entire runtime environments with ample processing power and memory, as well as additional sandboxing to reduce security concerns. One goal of this is to reduce the complexity to something that could execute on hardware wallets and other simple wallets. These also describe the data directly, which in many cases (such as blinded data), cannot adequately describe the data at all</p> </li> <li> <p>Custom Languages; due to the complexity of Ethereum transactions, any language used would require a lot of expressiveness and re-inventing the wheel. The EVM already exists (it may not be ideal), but it is there and can handle everything necessary.</p> </li> <li> <p>Format Strings (e.g. Trustless Signing UI Protocol; format strings can only operate on the class of regular languages, which in many cases is insufficient to describe an Ethereum transaction. This was an issue quite often during early attempts at solving this problem.</p> </li> <li> <p>The signTypedData <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> has many parallels to what this EIP aims to solve</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This does not affect backwards compatibility.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>I will add deployed examples by address and chain ID.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="escaping-text">Escaping Text</h3> <p>Wallets must be careful when displaying text provided by contracts and proper efforts must be taken to sanitize it, for example, be sure to consider:</p> <ul> <li>HTML could be embedded to attempt to trick web-based wallets into executing code using the script tag (possibly uploading any private keys to a server)</li> <li>In general, extreme care must be used when rendering HTML; consider the ENS names <code>&lt;span style="display:none"&gt;not-&lt;/span&gt;ricmoo.eth</code> or <code>&amp;thinsp;ricmoo.eth</code>, which if rendered without care would appear as <code>ricmoo.eth</code>, which it is not</li> <li>Other marks which require escaping could be included, such as quotes (<code>"</code>), formatting (<code>\n</code> (new line), <code>\f</code> (form feed), <code>\t</code> (tab), any of many non-standard whitespaces), back-slassh (<code>\</code>)</li> <li>UTF-8 has had bugs in the past which could allow arbitrary code execution and crashing renderers; consider using the UTF-8 replacement character (or <em>something</em>) for code-points outside common planes or common sub-sets within planes</li> <li>Homoglyphs attacks</li> <li>Right-to-left mark may affect rendering</li> <li>Many other things, deplnding on your environment</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-11-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 George Kadianakishttps://github.com/asn-d6 lightclienthttps://github.com/lightclient Alex Stokeshttps://github.com/ralexstokes https://wg-eips.ritovision.com/4444/

Prune historical data in clients older than one year

<h2 id="abstract">Abstract</h2> <p>Clients must stop serving historical headers, bodies, and receipts older than one year on the p2p layer. Clients may locally prune this historical data.</p> <h2 id="motivation">Motivation</h2> <p>Historical blocks and receipts currently occupy more than 400GB of disk space (and growing!). Therefore, to validate the chain, users must typically have a 1TB disk.</p> <p>Historical data is not necessary for validating new blocks, so once a client has synced the tip of the chain, historical data is only retrieved when requested explicitly over the JSON-RPC or when a peer attempts to sync the chain. By pruning the history, this proposal reduces the disk requirements for users. Pruning history also allows clients to remove code that processes historical blocks. This means that execution clients don't need to maintain code paths that deal with each upgrade's compounding changes.</p> <p>Finally, this change will result in less bandwidth usage on the network as clients adopt more lightweight sync strategies based on the PoS weak subjectivity assumption.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>Parameter</th><th>Value</th><th>Description</th></tr></thead><tbody> <tr><td><code>HISTORY_PRUNE_EPOCHS</code></td><td>82125</td><td>A year in beacon chain epochs</td></tr> </tbody></table> <p>Clients SHOULD NOT serve headers, block bodies, and receipts that are older than <code>HISTORY_PRUNE_EPOCHS</code> epochs on the p2p network.</p> <p>Clients MAY locally prune headers, block bodies, and receipts that are older than <code>HISTORY_PRUNE_EPOCHS</code> epochs.</p> <h4 id="bootstrapping-and-syncing">Bootstrapping and syncing</h4> <p>This EIP impacts the way clients bootstrap and sync. Clients will not be able to full sync using devp2p since historical data will no longer be served.</p> <p>Clients MUST use a valid Weak Subjectivity Checkpoint to bootstrap from a more recent view of the chain. For the purpose of syncing, clients treat weak subjectivity checkpoints as the genesis block. We call this method "checkpoint sync".</p> <p>For the purposes of this proposal, we assume clients always start with a configured and valid weak subjectivity checkpoint. The way this is achieved is out-of-scope for this proposal.</p> <h2 id="rationale">Rationale</h2> <p>This proposal forces clients to stop serving old historical data over p2p. We make this explicit to force clients to seek historical data from other sources, instead of relying on the optional behavior of some clients which would result in quality degradation.</p> <h3 id="why-a-year">Why a year?</h3> <p>This proposal sets <code>HISTORY_PRUNE_EPOCHS</code> to 82125 epochs (one earth year). This constant is large enough to provide sufficient room for the Weak Subjectivity Period to grow, and it's also small enough so as to not occupy too much disk space.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="preserving-historical-data">Preserving historical data</h3> <p>This proposal impacts nodes that make use of historical data (e.g. web3 applications that display history of blocks, transactions or accounts). Preserving the history of Ethereum is fundamental and we believe there are various out-of-band ways to achieve this.</p> <p>Historical data can be packaged and shared via torrent magnet links or over networks like IPFS. Furthermore, systems like the Portal Network or The Graph can be used to acquire historical data.</p> <p>Clients should allow importing and exporting of historical data. Clients can provide scripts that fetch/verify data and automatically import them.</p> <h3 id="full-syncing-from-genesis">Full syncing from genesis</h3> <p>Full syncing will no longer be possible over the p2p network. However, we do want to allow interested parties to do so on their own.</p> <p>We suggest that a specialized "full sync" client is built. The client is a shim that pieces together different releases of execution engines and can import historical blocks to validate the entire Ethereum chain from genesis and generate all other historical data.</p> <p>It's important to also note that although archive nodes with "state sync" functionality are in development, full sync is currently the only reliable way to bootstrap them. Clients that wish to continue providing archive support would need the ability to import historical blocks retrieved out-of-band and retain support for each historical upgrade of the network.</p> <h3 id="user-experience">User experience</h3> <p>This proposal impacts the UX for setting up applications that use historical data. Hence we suggest that clients introduce this change in two phases:</p> <p>In the first phase, clients don't prune historical data by default. They introduce a command line option similar to geth's <code>--txlookuplimit</code> that users can use if they want to prune historical data.</p> <p>In the second phase, history is pruned by default and the command line option is removed. Clients assume that users will find and import data in an out-of-band way.</p> <h3 id="json-rpc-changes">JSON-RPC changes</h3> <p>After this proposal is implemented, certain JSON-RPC endpoints (e.g. like <code>getBlockByHash</code>) won't be able to tell whether a given hash is invalid or just outdated. Other endpoints like <code>getLogs</code> will simply no longer have the data the user is requesting. The way this regression should be handled by applications or clients is out-of-scope for this proposal.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="relying-on-weak-subjectivity">Relying on weak subjectivity</h3> <p>With the move to PoS, it's essential for security to use valid weak subjectivity checkpoints because of long-range attacks.</p> <p>This proposal relies on the weak subjectivity assumption and assumes that clients will not bootstrap with an invalid or old WS checkpoint.</p> <p>This proposal also assumes that the weak subjectivity period will never be longer than <code>HISTORY_PRUNE_EPOCHS</code>. If that were to happen, clients with an old weak subjectivity checkpoint would never be able to "checkpoint sync" since the p2p network would not be able to provide the required data.</p> <h3 id="centralization-censorship-risk">Centralization/censorship risk</h3> <p>There are censorship/availability risks if there is a lack of incentives to keep historical data.</p> <p>It's important that Ethereum historical data are preserved and seeded by independent organizations, and their availability should be checked frequently. We consider these mechanisms as out-of-scope for this proposal.</p> <p>Furthermore, there is a risk that more dapps will rely on centralized services for acquiring historical data because it will be harder to setup a full node.</p> <h3 id="confusion-with-other-proposals">Confusion with other proposals</h3> <p>Because there are a number of alternative proposals for reducing the execution client's footprint on disk, we've decided to enforce a specific pronunciation of the EIP. When pronouncing the EIP number, it <strong>MUST</strong> be pronounced EIP "four fours". All other pronunciation are incorrect.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-11-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 John Petersonhttps://github.com/John-peterson-coinbase Roberto Bayardohttps://github.com/roberto-bayardo David Núñezhttps://github.com/cygnusv https://wg-eips.ritovision.com/4931/

Create a standard interface for upgrading ERC20 token contracts.

<h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> token upgrades. This standard specifies an interface that supports the conversion of tokens from one contract (called the "source token") to those from another (called the "destination token"), as well as several helper methods to provide basic information about the token upgrade (i.e. the address of the source and destination token contracts, the ratio that source will be upgraded to destination, etc.).</p> <h2 id="motivation">Motivation</h2> <p>Token contract upgrades typically require each asset holder to exchange their old tokens for new ones using a bespoke interface provided by the developers. This standard interface will allow asset holders as well as centralized and decentralized exchanges to conduct token upgrades more efficiently since token contract upgrade scripts will be essentially reusable. Standardization will reduce the security overhead involved in verifying the functionality of the upgrade contracts. It will also provide asset issuers clear guidance on how to effectively implement a token upgrade.</p> <h2 id="specification">Specification</h2> <p>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> <p>Please Note: Methods marked with (Optional Ext.) are a part of the optional extension for downgrade functionality and may remain unimplemented if downgrade functionality is not required.</p> <h3 id="token-upgrade-interface-contract">Token Upgrade Interface Contract</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IEIP4931</span><span> {</span></span></code></pre><h4 id="methods">Methods</h4> <h5 id="upgradesource">upgradeSource</h5> <p>Returns the address of the original (source) token that will be upgraded.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A getter to determine the contract that is being upgraded from (&quot;source contract&quot;)</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> address of the source token contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> upgradeSource</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">address</span><span>)</span></span></code></pre><h5 id="upgradedestination">upgradeDestination</h5> <p>Returns the address of the token contract that is being upgraded to.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A getter to determine the contract that is being upgraded to (&quot;destination contract&quot;)</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> address of the destination token contract</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> upgradeDestination</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">address</span><span>)</span></span></code></pre><h5 id="isupgradeactive">isUpgradeActive</h5> <p>Returns the current status of the upgrade functionality. Status MUST return <code>true</code> when the upgrade contract is functional and serving upgrades. It MUST return <code>false</code> when the upgrade contract is not currently serving upgrades.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The method will return true when the contract is serving upgrades and otherwise false</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> status of the upgrade as a boolean</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isUpgradeActive</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span></span></code></pre><h5 id="isdowngradeactive">isDowngradeActive</h5> <p>Returns the current status of the downgrade functionality. Status MUST return <code>true</code> when the upgrade contract is functional and serving downgrades. It MUST return <code>false</code> when the upgrade contract is not currently serving downgrades. When the downgrade Optional Ext. is not implemented, this method will always return <code>false</code> to signify downgrades are not available.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The method will return true when the contract is serving downgrades and otherwise false</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> status of the downgrade as a boolean</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isDowngradeActive</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span></span></code></pre><h5 id="ratio">ratio</h5> <p>Returns the ratio of destination token to source token, expressed as a 2-tuple, that the upgrade will use. E.g. <code>(3, 1)</code> means the upgrade will provide 3 destination tokens for every 1 source token being upgraded.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A getter for the ratio of destination tokens to source tokens received when conducting an upgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Two</span><span class="z-comment"> uint256, the first represents the numerator while the second represents</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> the denominator of the ratio of destination tokens to source tokens allotted during the upgrade</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> ratio</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span>,</span><span class="z-support"> uint256</span><span>)</span></span></code></pre><h5 id="totalupgraded">totalUpgraded</h5> <p>Returns the total number of tokens that have been upgraded from source to destination. If the downgrade Optional Ext. is implemented, calls to <code>downgrade</code> will reduce the <code>totalUpgraded</code> return value making it possible for the value to decrease between calls. The return value will be strictly increasing if downgrades are not implemented.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A getter for the total amount of source tokens that have been upgraded to destination tokens.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> The value may not be strictly increasing if the downgrade Optional Ext. is implemented.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> number of source tokens that have been upgraded to destination tokens</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> totalUpgraded</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span>)</span></span></code></pre><h5 id="computeupgrade">computeUpgrade</h5> <p>Computes the <code>destinationAmount</code> of destination tokens that correspond to a given <code>sourceAmount</code> of source tokens, according to the predefined conversion ratio, as well as the <code>sourceRemainder</code> amount of source tokens that can't be upgraded. For example, let's consider a (3, 2) ratio, which means that 3 destination tokens are provided for every 2 source tokens; then, for a source amount of 5 tokens, <code>computeUpgrade(5)</code> must return <code>(6, 1)</code>, meaning that 6 destination tokens are expected (in this case, from 4 source tokens) and 1 source token is left as remainder.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A method to mock the upgrade call determining the amount of destination tokens received from an upgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> as well as the amount of source tokens that are left over as remainder</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sourceAmount</span><span class="z-comment"> The amount of source tokens that will be upgraded</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> destinationAmount</span><span class="z-comment"> A uint256 representing the amount of destination tokens received if upgrade is called</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> sourceRemainder</span><span class="z-comment"> A uint256 representing the amount of source tokens left over as remainder if upgrade is called</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> computeUpgrade</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> sourceAmount</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> destinationAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> sourceRemainder</span><span>)</span></span></code></pre><h5 id="computedowngrade-optional-ext">computeDowngrade (Optional Ext.)</h5> <p>Computes the <code>sourceAmount</code> of source tokens that correspond to a given <code>destinationAmount</code> of destination tokens, according to the predefined conversion ratio, as well as the <code>destinationRemainder</code> amount of destination tokens that can't be downgraded. For example, let's consider a (3, 2) ratio, which means that 3 destination tokens are provided for every 2 source tokens; for a destination amount of 13 tokens, <code>computeDowngrade(13)</code> must return <code>(4, 1)</code>, meaning that 4 source tokens are expected (in this case, from 12 destination tokens) and 1 destination token is left as remainder.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A method to mock the downgrade call determining the amount of source tokens received from a downgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> as well as the amount of destination tokens that are left over as remainder</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> destinationAmount</span><span class="z-comment"> The amount of destination tokens that will be downgraded</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> sourceAmount</span><span class="z-comment"> A uint256 representing the amount of source tokens received if downgrade is called</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> destinationRemainder</span><span class="z-comment"> A uint256 representing the amount of destination tokens left over as remainder if upgrade is called</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> computeDowngrade</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> destinationAmount</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> sourceAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> destinationRemainder</span><span>)</span></span></code></pre><h5 id="upgrade">upgrade</h5> <p>Upgrades the <code>amount</code> of source token to the destination token in the specified ratio. The destination tokens will be sent to the <code>_to</code> address. The function MUST lock the source tokens in the upgrade contract or burn them. If the downgrade Optional Ext. is implemented, the source tokens MUST be locked instead of burning. The function MUST <code>throw</code> if the caller's address does not have enough source token to upgrade or if <code>isUpgradeActive</code> is returning <code>false</code>. The function MUST also fire the <code>Upgrade</code> event. <code>approve</code> MUST be called first on the source contract.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A method to conduct an upgrade from source token to destination token.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> The call will fail if upgrade status is not true, if approve has not been called</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> on the source contract, or if sourceAmount is larger than the amount of source tokens at the msg.sender address.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> If the ratio would cause an amount of tokens to be destroyed by rounding/truncation, the upgrade call will</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> only upgrade the nearest whole amount of source tokens returning the excess to the msg.sender address. </span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Emits the Upgrade event</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address the destination tokens will be sent to upon completion of the upgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sourceAmount</span><span class="z-comment"> The amount of source tokens that will be upgraded </span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> upgrade</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> sourceAmount</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre><h5 id="downgrade-optional-ext">downgrade (Optional Ext.)</h5> <p>Downgrades the <code>amount</code> of destination token to the source token in the specified ratio. The source tokens will be sent to the <code>_to</code> address. The function MUST unwrap the destination tokens back to the source tokens. The function MUST <code>throw</code> if the caller's address does not have enough destination token to downgrade or if <code>isDowngradeActive</code> is returning <code>false</code>. The function MUST also fire the <code>Downgrade</code> event. <code>approve</code> MUST be called first on the destination contract.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A method to conduct a downgrade from destination token to source token.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> The call will fail if downgrade status is not true, if approve has not been called</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> on the destination contract, or if destinationAmount is larger than the amount of destination tokens at the msg.sender address.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> If the ratio would cause an amount of tokens to be destroyed by rounding/truncation, the downgrade call will only downgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> the nearest whole amount of destination tokens returning the excess to the msg.sender address. </span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Emits the Downgrade event</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address the source tokens will be sent to upon completion of the downgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> destinationAmount</span><span class="z-comment"> The amount of destination tokens that will be downgraded </span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> downgrade</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> destinationAmount</span><span>)</span><span class="z-storage z-type"> external</span></span></code></pre><h4 id="events">Events</h4> <h5 id="upgrade-1">Upgrade</h5> <p>MUST trigger when tokens are upgraded.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> Address that called upgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Address that destination tokens were sent to upon completion of the upgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sourceAmount</span><span class="z-comment"> Amount of source tokens that were upgraded</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> destinationAmount</span><span class="z-comment"> Amount of destination tokens sent to the _to address</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Upgrade</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> sourceAmount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> destinationAmount</span><span>)</span></span></code></pre><h5 id="downgrade-optional-ext-1">Downgrade (Optional Ext.)</h5> <p>MUST trigger when tokens are downgraded.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> Address that called downgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Address that source tokens were sent to upon completion of the downgrade</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sourceAmount</span><span class="z-comment"> Amount of source tokens sent to the _to address</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> destinationAmount</span><span class="z-comment"> Amount of destination tokens that were downgraded</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Downgrade</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> sourceAmount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> destinationAmount</span><span>)</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>There have been several notable ERC20 upgrades (Ex. Golem: GNT -&gt; GLM) where the upgrade functionality is written directly into the token contracts. We view this as a suboptimal approach to upgrades since it tightly couples the upgrade with the existing tokens. This EIP promotes the use of a third contract to facilitate the token upgrade to decouple the functionality of the upgrade from the functionality of the token contracts. Standardizing the upgrade functionality will allow asset holders and exchanges to write simplified reusable scripts to conduct upgrades which will reduce the overhead of conducting upgrades in the future. The interface aims to be intentionally broad leaving much of the specifics of the upgrade to the implementer, so that the token contract implementations do not interfere with the upgrade process. Finally, we hope to create a greater sense of security and validity for token upgrades by enforcing strict means of disposing of the source tokens during the upgrade. This is achieved by the specification of the <code>upgrade</code> method. The agreed upon norm is that burnable tokens shall be burned. Otherwise, tokens shall be effectively burned by being sent to the <code>0x00</code> address. When downgrade Optional Ext. is implemented, the default is instead to lock source tokens in the upgrade contract to avoid a series of consecutive calls to <code>upgrade</code> and <code>downgrade</code> from artificially inflating the supply of either token (source or destination).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no breaking backwards compatibility issues. There are previously implemented token upgrades that likely do not adhere to this standard. In these cases, it may be relevant for the asset issuers to communicate that their upgrade is not EIP-4931 compliant.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment">SPDX-License-Identifier: Apache-2.0</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> 0.8.9</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC20/IERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IEIP4931.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> SourceUpgrade</span><span class="z-storage"> is</span><span class="z-entity z-name"> IEIP4931</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> SafeERC20</span><span class="z-keyword"> for</span><span class="z-entity z-name"> IERC20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> constant</span><span> RATIO_SCALE </span><span class="z-keyword">=</span><span class="z-constant"> 10</span><span class="z-keyword">*</span><span class="z-keyword">*</span><span class="z-constant">18</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> IERC20 </span><span class="z-storage z-type">private</span><span> source</span><span>;</span></span> <span class="giallo-l"><span> IERC20 </span><span class="z-storage z-type">private</span><span> destination</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-storage z-type"> private</span><span> upgradeStatus</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-storage z-type"> private</span><span> downgradeStatus</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> numeratorRatio</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> denominatorRatio</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> sourceUpgradedTotal</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> public</span><span> upgradedBalance</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _source</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _destination</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _upgradeStatus</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _downgradeStatus</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _numeratorRatio</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _denominatorRatio</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_source </span><span class="z-keyword">!=</span><span> _destination</span><span>,</span><span class="z-string"> &quot;SourceUpgrade: source and destination addresses are the same&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_source </span><span class="z-keyword">!=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;SourceUpgrade: source address cannot be zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_destination </span><span class="z-keyword">!=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;SourceUpgrade: destination address cannot be zero address&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_numeratorRatio </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;SourceUpgrade: numerator of ratio cannot be zero&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_denominatorRatio </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;SourceUpgrade: denominator of ratio cannot be zero&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> source </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>_source</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> destination </span><span class="z-keyword">=</span><span class="z-entity z-name"> IERC20</span><span>(</span><span>_destination</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> upgradeStatus </span><span class="z-keyword">=</span><span> _upgradeStatus</span><span>;</span></span> <span class="giallo-l"><span> downgradeStatus </span><span class="z-keyword">=</span><span> _downgradeStatus</span><span>;</span></span> <span class="giallo-l"><span> numeratorRatio </span><span class="z-keyword">=</span><span> _numeratorRatio</span><span>;</span></span> <span class="giallo-l"><span> denominatorRatio </span><span class="z-keyword">=</span><span> _denominatorRatio</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A getter to determine the contract that is being upgraded from (&quot;source contract&quot;)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> address of the source token contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> upgradeSource</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> address</span><span>(</span><span>source</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A getter to determine the contract that is being upgraded to (&quot;destination contract&quot;)</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> address of the destination token contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> upgradeDestination</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> address</span><span>(</span><span>destination</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The method will return true when the contract is serving upgrades and otherwise false</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> status of the upgrade as a boolean</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isUpgradeActive</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> upgradeStatus</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The method will return true when the contract is serving downgrades and otherwise false</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> status of the downgrade as a boolean</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isDowngradeActive</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> downgradeStatus</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A getter for the ratio of destination tokens to source tokens received when conducting an upgrade</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Two</span><span class="z-comment"> uint256, the first represents the numerator while the second represents</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the denominator of the ratio of destination tokens to source tokens allotted during the upgrade</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ratio</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span>,</span><span class="z-support"> uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>numeratorRatio</span><span>,</span><span> denominatorRatio</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A getter for the total amount of source tokens that have been upgraded to destination tokens.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The value may not be strictly increasing if the downgrade Optional Ext. is implemented.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> number of source tokens that have been upgraded to destination tokens</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalUpgraded</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> sourceUpgradedTotal</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A method to mock the upgrade call determining the amount of destination tokens received from an upgrade</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> as well as the amount of source tokens that are left over as remainder</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sourceAmount</span><span class="z-comment"> The amount of source tokens that will be upgraded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> destinationAmount</span><span class="z-comment"> A uint256 representing the amount of destination tokens received if upgrade is called</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> sourceRemainder</span><span class="z-comment"> A uint256 representing the amount of source tokens left over as remainder if upgrade is called</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> computeUpgrade</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> sourceAmount</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> destinationAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> sourceRemainder</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> sourceRemainder </span><span class="z-keyword">=</span><span> sourceAmount % </span><span>(</span><span>numeratorRatio </span><span class="z-keyword">/</span><span> denominatorRatio</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> upgradeableAmount </span><span class="z-keyword">=</span><span> sourceAmount </span><span class="z-keyword">-</span><span> (</span><span>sourceRemainder </span><span class="z-keyword">*</span><span> RATIO_SCALE</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> destinationAmount </span><span class="z-keyword">=</span><span> upgradeableAmount </span><span class="z-keyword">*</span><span> (</span><span>numeratorRatio </span><span class="z-keyword">/</span><span> denominatorRatio</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A method to mock the downgrade call determining the amount of source tokens received from a downgrade</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> as well as the amount of destination tokens that are left over as remainder</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> destinationAmount</span><span class="z-comment"> The amount of destination tokens that will be downgraded</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> sourceAmount</span><span class="z-comment"> A uint256 representing the amount of source tokens received if downgrade is called</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> destinationRemainder</span><span class="z-comment"> A uint256 representing the amount of destination tokens left over as remainder if upgrade is called</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> computeDowngrade</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> destinationAmount</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> sourceAmount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> destinationRemainder</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> destinationRemainder </span><span class="z-keyword">=</span><span> destinationAmount % </span><span>(</span><span>denominatorRatio </span><span class="z-keyword">/</span><span> numeratorRatio</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> upgradeableAmount </span><span class="z-keyword">=</span><span> destinationAmount </span><span class="z-keyword">-</span><span> (</span><span>destinationRemainder </span><span class="z-keyword">*</span><span> RATIO_SCALE</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> sourceAmount </span><span class="z-keyword">=</span><span> upgradeableAmount </span><span class="z-keyword">/</span><span> (</span><span>denominatorRatio </span><span class="z-keyword">/</span><span> numeratorRatio</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A method to conduct an upgrade from source token to destination token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The call will fail if upgrade status is not true, if approve has not been called</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> on the source contract, or if sourceAmount is larger than the amount of source tokens at the msg.sender address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If the ratio would cause an amount of tokens to be destroyed by rounding/truncation, the upgrade call will</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> only upgrade the nearest whole amount of source tokens returning the excess to the msg.sender address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Emits the Upgrade event</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address the destination tokens will be sent to upon completion of the upgrade</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> sourceAmount</span><span class="z-comment"> The amount of source tokens that will be upgraded</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> upgrade</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> sourceAmount</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>upgradeStatus </span><span class="z-keyword">==</span><span class="z-constant"> true</span><span>,</span><span class="z-string"> &quot;SourceUpgrade: upgrade status is not active&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-support">uint256</span><span> destinationAmount</span><span>,</span><span class="z-support"> uint256</span><span> sourceRemainder</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> computeUpgrade</span><span>(</span><span>sourceAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> sourceAmount </span><span class="z-keyword">-</span><span class="z-keyword">=</span><span> sourceRemainder</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>sourceAmount </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;SourceUpgrade: disallow conversions of zero value&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> upgradedBalance</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> sourceAmount</span><span>;</span></span> <span class="giallo-l"><span> source</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> msg.sender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> sourceAmount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> destination</span><span>.</span><span class="z-entity z-name">safeTransfer</span><span>(</span><span>_to</span><span>,</span><span> destinationAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> sourceUpgradedTotal </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> sourceAmount</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Upgrade</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _to</span><span>,</span><span> sourceAmount</span><span>,</span><span> destinationAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> A method to conduct a downgrade from destination token to source token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The call will fail if downgrade status is not true, if approve has not been called</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> on the destination contract, or if destinationAmount is larger than the amount of destination tokens at the msg.sender address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If the ratio would cause an amount of tokens to be destroyed by rounding/truncation, the downgrade call will only downgrade</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> the nearest whole amount of destination tokens returning the excess to the msg.sender address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Emits the Downgrade event</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address the source tokens will be sent to upon completion of the downgrade</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> destinationAmount</span><span class="z-comment"> The amount of destination tokens that will be downgraded</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> downgrade</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> destinationAmount</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>upgradeStatus </span><span class="z-keyword">==</span><span class="z-constant"> true</span><span>,</span><span class="z-string"> &quot;SourceUpgrade: upgrade status is not active&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-support">uint256</span><span> sourceAmount</span><span>,</span><span class="z-support"> uint256</span><span> destinationRemainder</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> computeDowngrade</span><span>(</span><span>destinationAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> destinationAmount </span><span class="z-keyword">-</span><span class="z-keyword">=</span><span> destinationRemainder</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>destinationAmount </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;SourceUpgrade: disallow conversions of zero value&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>upgradedBalance</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> sourceAmount</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;SourceUpgrade: can not downgrade more than previously upgraded&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> upgradedBalance</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> sourceAmount</span><span>;</span></span> <span class="giallo-l"><span> destination</span><span>.</span><span class="z-entity z-name">safeTransferFrom</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> msg.sender</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> destinationAmount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> source</span><span>.</span><span class="z-entity z-name">safeTransfer</span><span>(</span><span>_to</span><span>,</span><span> sourceAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> sourceUpgradedTotal </span><span class="z-keyword">-</span><span class="z-keyword">=</span><span> sourceAmount</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Downgrade</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> _to</span><span>,</span><span> sourceAmount</span><span>,</span><span> destinationAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>The main security consideration is ensuring the implementation of the interface handles the source tokens during the upgrade in such a way that they are no longer accessible. Without careful handling, the validity of the upgrade may come into question since source tokens could potentially be upgraded multiple times. This is why EIP-4931 will strictly enforce the use of <code>burn</code> for source tokens that are burnable. For non-burnable tokens, the accepted method is to send the source tokens to the <code>0x00</code> address. When the downgrade Optional Ext. is implemented, the constraint will be relaxed, so that the source tokens can be held by the upgrade contract.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a rel="external" href="https://creativecommons.org/publicdomain/zero/1.0/">CC0</a>.</p> 2021-10-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ansgar Dietrichshttps://github.com/adietrichs https://wg-eips.ritovision.com/4396/

Accounts for block time in the base fee calculation to target a stable throughput by time instead of by block.

<h2 id="abstract">Abstract</h2> <p>This EIP proposes accounting for time between blocks in the base fee calculation to target a stable throughput by time, instead of by block. Aiming to minimize changes to the calculation, it only introduces a variable block gas target proportional to the block time. The EIP can, in principle, be applied to either a Proof-of-Work or a Proof-of-Stake chain, however the security implications for the Proof-of-Work case remain unexplored.</p> <h2 id="motivation">Motivation</h2> <p>The current base fee calculation chooses the gas usage of a block as the signal to determine whether demand for block space is too low (indicating that the base fee should be lowered) or too high (indicating that the base fee should be increased). While simple, this choice of signal has drawbacks: it does not take the block time into account. Assuming a relatively constant demand, a proposer constructing a block after 20 seconds will have transactions available with twice the gas of a proposer constructing a block after 10 seconds. Using the same gas target for both is accordingly sub-optimal. In practice, there are several undesirable consequences of this flawed signal:</p> <h3 id="base-fee-volatility-under-proof-of-work">Base Fee Volatility Under Proof-of-Work</h3> <p>Under Proof-of-Work (PoW), block times are stochastic, and for that reason there exists large block time variability. This variability contributes to the base fee volatility, where the base fee can be expected to oscillate around the equilibrium value even under perfectly stable demand.</p> <h3 id="missed-slots">Missed Slots</h3> <p>Under Proof-of-Stake (PoS), block times are ideally uniform (always 12s), but missed slots lead to individual blocks with increased block time (24s, 36s, ...). Such missed slots will result in the next block being overfull, and with the current update rule, signal a fake demand spike and thus cause a small unwarranted base fee spike.</p> <p>More importantly, these missed slots directly reduce the overall throughput of the execution chain by the gas target of one block. While the next block can be expected to include the "delayed" transactions of the missed slot, the resulting base fee spike then results in some number of under-full blocks. In the end the block space of the missed slot is lost for the chain.</p> <p>This is particularly problematic because a Denial-of-Service (DoS) attack on block proposers can cause them to miss slots, and compromises the overall chain performance.</p> <h3 id="throughput-degradation-during-consensus-issues">Throughput Degradation During Consensus Issues</h3> <p>A more severe version of individual missed slots can be caused by consensus issues that prevent a significant portion of block proposers from continuing to create blocks. This can be due to block proposers forking off (and creating blocks on their own fork), being unable to keep up with the current chain head for another reason, or simply being unable to create valid blocks.</p> <p>In all these situations, average block times go up significantly, causing chain throughput to fall by the same fraction. While this effect is already present under PoW, the self-healing mechanism of difficulty adjustments is relatively quick to kick in and restore normal block times. On the other hand, under PoS the automatic self-healing mechanism can be extremely slow: potentially several months to return to normal with up to a third of slots missed, or several weeks if more than a third of slots are missed.</p> <p>For all these reasons, it would be desirable to target a stable throughput per time instead of per block, by taking block time into account during the base fee calculation.</p> <p>To maximize the chance of this EIP being included in the merge fork, the adjustments are kept to a minimum, with more involved changes discussed in the rationale section.</p> <h2 id="specification">Specification</h2> <p>Using the pseudocode language of <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>, the updated base fee calculation becomes:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant">BASE_FEE_MAX_CHANGE_DENOMINATOR</span><span class="z-keyword"> =</span><span class="z-constant"> 8</span></span> <span class="giallo-l"><span class="z-constant">BLOCK_TIME_TARGET</span><span class="z-keyword"> =</span><span class="z-constant"> 12</span></span> <span class="giallo-l"><span class="z-constant">MAX_GAS_TARGET_PERCENT</span><span class="z-keyword"> =</span><span class="z-constant"> 95</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">class</span><span class="z-entity z-name"> World</span><span>(</span><span class="z-constant">ABC</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-storage z-type"> def</span><span class="z-entity z-name"> validate_block</span><span>(</span><span class="z-variable z-parameter z-function">self</span><span>,</span><span class="z-variable z-parameter z-function"> block</span><span>:</span><span> Block</span><span>)</span><span> -&gt;</span><span class="z-constant"> None</span><span>:</span></span> <span class="giallo-l"><span> parent_gas_limit</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>parent</span><span>(</span><span>block</span><span>)</span><span>.</span><span>gas_limit</span></span> <span class="giallo-l"><span> parent_block_time</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>parent</span><span>(</span><span>block</span><span>)</span><span>.</span><span>timestamp</span><span class="z-keyword"> -</span><span class="z-variable z-language"> self</span><span>.</span><span>parent</span><span>(</span><span class="z-variable z-language">self</span><span>.</span><span>parent</span><span>(</span><span>block</span><span>)</span><span>)</span><span>.</span><span>timestamp</span></span> <span class="giallo-l"><span> parent_base_gas_target</span><span class="z-keyword"> =</span><span> parent_gas_limit</span><span class="z-keyword"> //</span><span class="z-constant"> ELASTICITY_MULTIPLIER</span></span> <span class="giallo-l"><span> parent_adjusted_gas_target</span><span class="z-keyword"> =</span><span class="z-support"> min</span><span>(</span><span>parent_base_gas_target</span><span class="z-keyword"> *</span><span> parent_block_time</span><span class="z-keyword"> //</span><span class="z-constant"> BLOCK_TIME_TARGET</span><span>,</span><span> parent_gas_limit</span><span class="z-keyword"> *</span><span class="z-constant"> MAX_GAS_TARGET_PERCENT</span><span class="z-keyword"> //</span><span class="z-constant"> 100</span><span>)</span></span> <span class="giallo-l"><span> parent_base_fee_per_gas</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>parent</span><span>(</span><span>block</span><span>)</span><span>.</span><span>base_fee_per_gas</span></span> <span class="giallo-l"><span> parent_gas_used</span><span class="z-keyword"> =</span><span class="z-variable z-language"> self</span><span>.</span><span>parent</span><span>(</span><span>block</span><span>)</span><span>.</span><span>gas_used</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> parent_gas_used</span><span class="z-keyword"> ==</span><span> parent_adjusted_gas_target</span><span>:</span></span> <span class="giallo-l"><span> expected_base_fee_per_gas</span><span class="z-keyword"> =</span><span> parent_base_fee_per_gas</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> parent_gas_used</span><span class="z-keyword"> &gt;</span><span> parent_adjusted_gas_target</span><span>:</span></span> <span class="giallo-l"><span> gas_used_delta</span><span class="z-keyword"> =</span><span> parent_gas_used</span><span class="z-keyword"> -</span><span> parent_adjusted_gas_target</span></span> <span class="giallo-l"><span> base_fee_per_gas_delta</span><span class="z-keyword"> =</span><span class="z-support"> max</span><span>(</span><span>parent_base_fee_per_gas</span><span class="z-keyword"> *</span><span> gas_used_delta</span><span class="z-keyword"> //</span><span> parent_base_gas_target</span><span class="z-keyword"> //</span><span class="z-constant"> BASE_FEE_MAX_CHANGE_DENOMINATOR</span><span>,</span><span class="z-constant"> 1</span><span>)</span></span> <span class="giallo-l"><span> expected_base_fee_per_gas</span><span class="z-keyword"> =</span><span> parent_base_fee_per_gas</span><span class="z-keyword"> +</span><span> base_fee_per_gas_delta</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span> gas_used_delta</span><span class="z-keyword"> =</span><span> parent_adjusted_gas_target</span><span class="z-keyword"> -</span><span> parent_gas_used</span></span> <span class="giallo-l"><span> base_fee_per_gas_delta</span><span class="z-keyword"> =</span><span> parent_base_fee_per_gas</span><span class="z-keyword"> *</span><span> gas_used_delta</span><span class="z-keyword"> //</span><span> parent_base_gas_target</span><span class="z-keyword"> //</span><span class="z-constant"> BASE_FEE_MAX_CHANGE_DENOMINATOR</span></span> <span class="giallo-l"><span> expected_base_fee_per_gas</span><span class="z-keyword"> =</span><span> parent_base_fee_per_gas</span><span class="z-keyword"> -</span><span> base_fee_per_gas_delta</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-constant"> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant"> ...</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="mechanism">Mechanism</h3> <p>The proposed new base fee calculation only adjusts the block gas target by scaling it with the block time, capped at a maximum percent of the overall block gas limit:</p> <h4 id="current-base-fee-calculation">Current Base Fee Calculation</h4> <p><img src="https://wg-eips.ritovision.com/4396/./assets/old_formula.png" alt="" /></p> <h4 id="proposed-base-fee-calculation">Proposed Base Fee Calculation</h4> <p><img src="https://wg-eips.ritovision.com/4396/./assets/new_formula.png" alt="" /></p> <p>This new calculation thus targets a stable throughput per time instead of per block.</p> <h3 id="limitations">Limitations</h3> <p>Under PoS, block time increases always come in multiples of full blocks (e.g. a single missed slot = 24s instead of 12s block time). Accounting for this already requires doubling the block gas target, even for a single missed slot. However, with the block elasticity currently set to 2, this target would be equal to the block gas limit. Having the new target equal to the block gas limit is less than ideal, and thus is reduced slightly, according to the <code>MAX_GAS_TARGET_PERCENT</code> parameter. The reason for the existence of this parameter is twofold:</p> <ul> <li>Ensure that the signal remains meaningful: A target equal to or greater than the gas limit could never be reached, so the base fee would always be reduced after a missed slot.</li> <li>Ensure that the base fee can still react to genuine demand increases: During times of many offline block proposers (and thus many missed slots), genuine demand increases still need a way to eventually result in a base fee increase, to avoid a fallback to a first-price priority fee auction.</li> </ul> <p>However, this means that even a single missed slot cannot be fully compensated. Even worse, any second or further sequential missed slot cannot be compensated for at all, as the gas target is already at its max. This effect becomes more pronounced as the share of offline validators increases:</p> <p><img src="https://wg-eips.ritovision.com/4396/./assets/degradation.png" alt="" /></p> <p>As can be observed, while this EIP does indeed increase the robustness of the network throughput in cases of offline validators, it does so imperfectly. Furthermore, there is a tradeoff effected by the <code>MAX_GAS_TARGET_PERCENT</code> parameter, with a higher value resulting in a higher network robustness, but a more impaired base fee adjustment mechanism during times of frequent missed slots.</p> <h3 id="possible-extensions">Possible Extensions</h3> <p>These limitations directly result from the design goal of a minimal change, to maximize chances of being included in the merge. There are natural ways of extending the EIP design to more effectively handle offline validators, at the expense of somewhat more extensive changes:</p> <h4 id="persistent-multi-slot-buffer">Persistent Multi-Slot Buffer</h4> <p>To be able to compensate multiple consecutive missed slots, a gas buffer could be introduced, that would allow the gas beyond the block elasticity to be carried forward to future blocks. To avoid long-run buffer accumulation that would delay a return to normal operations once block proposers are back online, a cap on the buffer would be added. Even for a relatively small buffer cap, the throughput robustness is significantly improved:</p> <p><img src="https://wg-eips.ritovision.com/4396/./assets/degradation_buffers.png" alt="" /></p> <p>With an elasticity still at 2, there is no way of avoiding the eventual breakdown for more than 50% offline block proposers.</p> <p>The main implementation complexity for this approach comes from the introduction of the buffer as a new persistent field. To retain the ability for calculating base fees only based on headers, it would have to be added to the block header.</p> <h4 id="increased-block-elasticity">Increased Block Elasticity</h4> <p>In addition to the introduction of a buffer, increasing the block elasticity is another tool for increasing throughput robustness. The following diagram shows the effect of different elasticity levels, both in the presence and absence of a persistent buffer:</p> <p><img src="https://wg-eips.ritovision.com/4396/./assets/degradation_elasticity.png" alt="" /></p> <p>Again, a clear positive effect can be observed.</p> <p>The main additional complexity here would come from the increased peak load (networking, compute &amp; disk access) of multiple sequential overfull blocks. Note though that PoS with its minimum block time of 12s significantly reduces worst case peak stress as compared to PoW.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The EIP has minimal impact on backwards compatibility, only requiring updates to existing base fee calculation tooling.</p> <h2 id="test-cases">Test Cases</h2> <p>tbd</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>tbd</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="timestamp-manipulation">Timestamp Manipulation</h3> <p>Under PoW, miners are in control over the timestamp field of their blocks. While there are some enforced limits to valid timestamps, implications regarding potential timestamp manipulation are nontrivial and remain unexplored for this EIP.</p> <p>Under PoS, each slot has a <a rel="external" href="https://github.com/ethereum/consensus-specs/blob/v1.1.3/specs/merge/beacon-chain.md#process_execution_payload">fixed assigned timestamp</a>, rendering any timestamp manipulation by block proposers impossible.</p> <h3 id="suppressing-base-fee-increases">Suppressing Base Fee Increases</h3> <p>As discussed in the rationale, a high value for <code>MAX_GAS_TARGET_PERCENT</code> during times of many offline block proposers results in a small remaining signal space for genuine demand increases that should result in base fee increases. This in turn decreases the cost for block proposers for suppresing these base fee increases, instead forcing the fallback to a first-price priority fee auction.</p> <p>While the arguments of incentive incompatibility for base fee suppression of the base EIP-1559 case still apply here, with a decreasing cost of this individually irrational behavior the risk for overriding psychological factors becomes more significant.</p> <p>Even in such a case the system degradation would however be graceful, as it would only temporarily suspend the base fee burn. As soon as the missing block proposers would come back online, the system would return to its ordinary EIP-1559 equilibrium.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-10-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jules Laihttps://github.com/julesl23 https://wg-eips.ritovision.com/4393/

An interface for tip tokens that allows tipping to holders of NFTs and multi tokens

<h2 id="abstract">Abstract</h2> <p>This standard outlines a smart contract interface for tipping to non-fungible and multi tokens. Holders of the tokens are able to withdraw the tips as <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> rewards.</p> <p>For the purpose of this EIP, a micropayment is termed as a financial transaction that involves usually a small sum of money called "tips" that are sent to specific <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> NFTs and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> multi tokens, as rewards to their holders. A holder (also referred to as controller) is used as a more generic term for owner, as NFTs may represent non-digital assets such as services.</p> <h2 id="motivation">Motivation</h2> <p>A cheap way to send tips to any type of NFT or multi token. This can be achieved by gas optimising the tip token contract and sending the tips in batches using the <code>tipBatch</code> function from the interface.</p> <p>To make it easy to implement into dapps a tipping service to reward the NFT and multi token holders. Allows for fairer distribution of revenue back to NFT holders from the user community.</p> <p>To make the interface as minimal as possible in order to allow adoption into many different use cases.</p> <p>Some use cases include:</p> <ul> <li> <p>In game purchases and other virtual goods</p> </li> <li> <p>Tipping messages, posts, music and video content</p> </li> <li> <p>Donations/crowdfunding</p> </li> <li> <p>Distribution of royalties</p> </li> <li> <p>Pay per click advertising</p> </li> <li> <p>Incentivising use of services</p> </li> <li> <p>Reward cards and coupons</p> </li> </ul> <p>These can all leverage the security, immediacy and transparency of blockchain.</p> <h2 id="specification">Specification</h2> <p>This standard proposal outlines a generalised way to allow tipping via implementation of an <code>ITipToken</code> interface. The interface is intentionally kept to a minimum in order to allow for maximum use cases.</p> <p>Smart contracts implementing this EIP standard MUST implement all of the functions in this EIP interface. MUST also emit the events specified in the interface so that a complete state of the tip token contract can be derived from the events emitted alone.</p> <p>Smart contracts implementing this EIP standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> supportsInterface function and MUST return the constant value true if 0xE47A7022 is passed through the interfaceID argument. Note that revert in this document MAY mean a require, throw (not recommended as depreciated) or revert solidity statement with or without error messages.</p> <p>Note that, nft (or NFT in caps) in the code and as mentioned in this document, MAY also refer to an EIP-1155 fungible token.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ITipToken</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when the tip token implementation approves the address</span></span> <span class="giallo-l"><span class="z-comment"> of an NFT for tipping.</span></span> <span class="giallo-l"><span class="z-comment"> The holders of the &#39;nft&#39; are approved to receive rewards.</span></span> <span class="giallo-l"><span class="z-comment"> When an NFT Transfer event emits, this also indicates that the approved</span></span> <span class="giallo-l"><span class="z-comment"> addresses for that NFT (if any) is reset to none.</span></span> <span class="giallo-l"><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x985A3267.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ApprovalForNFT</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable"> holders</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> nft</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> approved</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a user has deposited an ERC-20 compatible token to</span></span> <span class="giallo-l"><span class="z-comment"> the tip token&#39;s contract address or to an external address.</span></span> <span class="giallo-l"><span class="z-comment"> This also indicates that the deposit has been exchanged for an</span></span> <span class="giallo-l"><span class="z-comment"> amount of tip tokens</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Deposit</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> rewardToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tipTokenAmount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a holder withdraws an amount of ERC-20 compatible</span></span> <span class="giallo-l"><span class="z-comment"> reward. This reward comes from the tip token&#39;s contract address or from</span></span> <span class="giallo-l"><span class="z-comment"> an external address, depending on the tip token implementation</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> WithdrawReward</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> holder</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> rewardToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when the tip token constructor or initialize method is</span></span> <span class="giallo-l"><span class="z-comment"> executed.</span></span> <span class="giallo-l"><span class="z-comment"> Importantly the ERC-20 compatible token &#39;rewardToken_&#39; to use as reward</span></span> <span class="giallo-l"><span class="z-comment"> to NFT holders is set at this time and remains the same throughout the</span></span> <span class="giallo-l"><span class="z-comment"> lifetime of the tip token contract.</span></span> <span class="giallo-l"><span class="z-comment"> The &#39;rewardToken_&#39; and &#39;tipToken_&#39; MAY be the same.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> InitializeTipToken</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tipToken_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> rewardToken_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> owner_</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits every time a user tips an NFT holder.</span></span> <span class="giallo-l"><span class="z-comment"> Also includes the reward token address and the reward token amount that</span></span> <span class="giallo-l"><span class="z-comment"> will be held pending until the holder withdraws the reward tokens.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Tip</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable"> holder</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> nft</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> rewardToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-variable"> rewardTokenAmount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Enable or disable approval for tipping for a single NFT held</span></span> <span class="giallo-l"><span class="z-comment"> by a holder or a multi token shared by holders</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if calling nft&#39;s supportsInterface does not return</span></span> <span class="giallo-l"><span class="z-comment"> true for either IERC721 or IERC1155.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if any of the &#39;holders&#39; is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if &#39;nft&#39; has not approved the tip token contract address as operator.</span></span> <span class="giallo-l"><span class="z-comment"> MUST emit the &#39;ApprovalForNFT&#39; event to reflect approval or not approval.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> holders</span><span class="z-comment"> The holders of the NFT (NFT controllers)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> nft</span><span class="z-comment"> The NFT contract address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> id</span><span class="z-comment"> The NFT token id</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> approved</span><span class="z-comment"> True if the &#39;holder&#39; is approved, false to revoke approval</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setApprovalForNFT</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> holders</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> nft</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> approved</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Checks if &#39;holder&#39; and &#39;nft&#39; with token &#39;id&#39; have been approved</span></span> <span class="giallo-l"><span class="z-comment"> by setApprovalForNFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> This does not check that the holder of the NFT has </span><span class="z-keyword">changed</span><span class="z-comment">. That is</span></span> <span class="giallo-l"><span class="z-comment"> left to the implementer to detect events for change of ownership and to</span></span> <span class="giallo-l"><span class="z-comment"> take appropriate action</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> holder</span><span class="z-comment"> The holder of the NFT (NFT controller)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> nft</span><span class="z-comment"> The NFT contract address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> id</span><span class="z-comment"> The NFT token id</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if &#39;holder&#39; and &#39;nft&#39; with token &#39;id&#39; have previously been</span></span> <span class="giallo-l"><span class="z-comment"> approved by the tip token contract</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isApprovalForNFT</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> holder</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> nft</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> id</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Sends tip from msg.sender to holder of a single NFT or</span></span> <span class="giallo-l"><span class="z-comment"> to shared holders of a multi token</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> If &#39;nft&#39; has not been approved for tipping, MUST revert</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if &#39;nft&#39; is zero address.</span></span> <span class="giallo-l"><span class="z-comment"> MUST burn the tip &#39;amount&#39; to the &#39;holder&#39; and send the reward to</span></span> <span class="giallo-l"><span class="z-comment"> an account pending for the holder(s).</span></span> <span class="giallo-l"><span class="z-comment"> If &#39;nft&#39; is a multi token that has multiple holders then each holder</span></span> <span class="giallo-l"><span class="z-comment"> MUST receive tip amount in proportion of their balance of multi tokens</span></span> <span class="giallo-l"><span class="z-comment"> MUST emit the &#39;Tip&#39; event to reflect the amounts that msg.sender tipped</span></span> <span class="giallo-l"><span class="z-comment"> to holder(s) of &#39;nft&#39;.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> nft</span><span class="z-comment"> The NFT contract address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> id</span><span class="z-comment"> The NFT token id</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> amount</span><span class="z-comment"> Amount of tip tokens to send to the holder of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tip</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> nft</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amount</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Sends a batch of tips to holders of &#39;nfts&#39; for gas efficiency</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> If NFT has not been approved for tipping, revert</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if the input arguments lengths are not all the same</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert if any of the user addresses are zero</span></span> <span class="giallo-l"><span class="z-comment"> MUST revert the whole batch if there are any errors</span></span> <span class="giallo-l"><span class="z-comment"> MUST emit the &#39;Tip&#39; events so that the state of the amounts sent to</span></span> <span class="giallo-l"><span class="z-comment"> each holder and for which nft and from whom, can be reconstructed.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> users</span><span class="z-comment"> User accounts to tip from</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> nfts</span><span class="z-comment"> The NFT contract addresses whose holders to tip to</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> ids</span><span class="z-comment"> The NFT token ids that uniquely identifies the &#39;nfts&#39;</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> amounts</span><span class="z-comment"> Amount of tip tokens to send to the holders of the NFTs</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tipBatch</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> users</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> nfts</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> ids</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> amounts</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Deposit an ERC-20 compatible token in exchange for tip tokens</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> The price of tip tokens can be different for each deposit as</span></span> <span class="giallo-l"><span class="z-comment"> the amount of reward token sent ultimately is a ratio of the</span></span> <span class="giallo-l"><span class="z-comment"> amount of tip tokens to tip over the user&#39;s tip tokens balance available</span></span> <span class="giallo-l"><span class="z-comment"> multiplied by the user&#39;s deposit balance.</span></span> <span class="giallo-l"><span class="z-comment"> The deposited tokens can be held in the tip tokens contract account or</span></span> <span class="giallo-l"><span class="z-comment"> in an external escrow. This will depend on the tip token implementation.</span></span> <span class="giallo-l"><span class="z-comment"> Each tip token contract MUST handle only one type of ERC-20 compatible</span></span> <span class="giallo-l"><span class="z-comment"> reward for deposits.</span></span> <span class="giallo-l"><span class="z-comment"> This token address SHOULD be passed in to the tip token constructor or</span></span> <span class="giallo-l"><span class="z-comment"> initialize method. SHOULD revert if ERC-20 reward for deposits is</span></span> <span class="giallo-l"><span class="z-comment"> zero address.</span></span> <span class="giallo-l"><span class="z-comment"> MUST emit the &#39;Deposit&#39; event that shows the user, deposited token details</span></span> <span class="giallo-l"><span class="z-comment"> and amount of tip tokens minted in exchange</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> user</span><span class="z-comment"> The user account</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> amount</span><span class="z-comment"> Amount of ERC-20 token to deposit in exchange for tip tokens.</span></span> <span class="giallo-l"><span class="z-comment"> This deposit is to be used later as the reward token</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deposit</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> An NFT holder can withdraw their tips as an ERC-20 compatible</span></span> <span class="giallo-l"><span class="z-comment"> reward at a time of their choosing</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST revert if not enough balance pending available to withdraw.</span></span> <span class="giallo-l"><span class="z-comment"> MUST send &#39;amount&#39; to msg.sender account (the holder)</span></span> <span class="giallo-l"><span class="z-comment"> MUST reduce the balance of reward tokens pending by the &#39;amount&#39; withdrawn.</span></span> <span class="giallo-l"><span class="z-comment"> MUST emit the &#39;WithdrawReward&#39; event to show the holder who withdrew, the reward</span></span> <span class="giallo-l"><span class="z-comment"> token address and &#39;amount&#39;</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> amount</span><span class="z-comment"> Amount of ERC-20 token to withdraw as a reward</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> withdrawReward</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> MUST have identical behaviour to ERC-20 balanceOf and is the amount</span></span> <span class="giallo-l"><span class="z-comment"> of tip tokens held by &#39;user&#39;</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> user</span><span class="z-comment"> The user account</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> balance of tip tokens held by user</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> The balance of deposit available to become rewards when</span></span> <span class="giallo-l"><span class="z-comment"> user sends the tips</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> user</span><span class="z-comment"> The user account</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> remaining balance of the ERC-20 compatible token deposited</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceDepositOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> The amount of reward token owed to &#39;holder&#39;</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> The pending tokens can come from the tip token contract account</span></span> <span class="giallo-l"><span class="z-comment"> or from an external escrow, depending on tip token implementation</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> holder</span><span class="z-comment"> The holder of NFT(s) (NFT controller)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> amount of reward tokens owed to the holder from tipping</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> rewardPendingOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> holder</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="tipping-and-rewards-to-holders">Tipping and rewards to holders</h3> <p>A user first deposits a compatible EIP-20 to the tip token contract that is then held (less any agreed fee) in escrow, in exchange for tip tokens. These tip tokens can then be sent by the user to NFTs and multi tokens (that have been approved by the tip token contract for tipping) to be redeemed for the original EIP-20 deposits on withdrawal by the holders as rewards.</p> <h3 id="tip-token-transfer-and-value-calculations">Tip Token transfer and value calculations</h3> <p>Tip token values are exchanged with EIP-20 deposits and vice-versa. It is left to the tip token implementer to decide on the price of a tip token and hence how much tip to mint in exchange for the EIP-20 deposited. One possibility is to have fixed conversion rates per geographical region so that users from poorer countries are able to send the same number of tips as those from richer nations for the same level of appreciation for content/assets etc. Hence, not skewed by average wealth when it comes to analytics to discover what NFTs are actually popular, allowing creators to have a level playing field.</p> <p>Whenever a user sends a tip, an equivalent value of deposited EIP-20 MUST be transferred to a pending account for the NFT or multi token holder, and the tip tokens sent MUST be burnt. This equivalent value is calculated using a simple formula:</p> <p>_total user balance of EIP-20 deposit _ tip amount / total user balance of tip tokens*</p> <p>Thus adding *free* tips to a user's balance of tips for example, simply dilutes the overall value of each tip for that user, as collectively they still refer to the same amount of EIP-20 deposited.</p> <p>Note if the tip token contract inherits from an EIP-20, tips can be transferred from one user to another directly. The deposit amount would be already in the tip token contract (or an external escrow account) so only tip token contract's internal mapping of user account to deposit balances needs to be updated. It is RECOMMENDED that the tip amount be burnt from user A and then minted back to user B in the amount that keeps user B's average EIP-20 deposited value per tip the same, so that the value of the tip does not fluctuate in the process of tipping.</p> <p>If not inheriting from EIP-20, then minting the tip tokens MUST emit <code>event Transfer(address indexed from, address indexed to, uint256 value)</code> where sender is the zero address for a mint and to is the zero address for a burn. The Transfer event MUST be the same signature as the Transfer function in the <code>IERC20</code> interface.</p> <h3 id="royalty-distribution">Royalty distribution</h3> <p>EIP-1155 allows for shared holders of a token id. Imagine a scenario where an article represented by an NFT was written by multiple contributors. Here, each contributor is a holder and the fractional sharing percentage between them can be represented by the balance that each holds in the EIP-1155 token id. So for two holders A and B of EIP-1155 token 1, if holder A's balance is 25 and holder B's is 75 then any tip sent to token 1 would distribute 25% of the reward pending to holder A and the remaining 75% pending to holder B.</p> <p>Here is an example implementation of ITipToken contract data structures:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Mapping from NFT/multi token to token id to holder(s)</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> address</span><span>[</span><span>]</span><span>)</span><span>)</span><span class="z-storage z-type"> private</span><span> _tokenIdToHolders</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Mapping from user to user&#39;s deposit balance</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _depositBalances</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Mapping from holder to holder&#39;s reward pending amount</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _rewardsPending</span><span>;</span></span></code></pre> <p>This copes with EIP-721 contracts that must have unique token ids and single holders (to be compliant with the standard), and EIP-1155 contracts that can have multiple token ids and multiple holders per instance. The <code>tip</code> function implementation would then access <code>_tokenIdToHolders</code> via indices NFT/multi token address and token id to distribute to holder's or holders' <code>_rewardsPending</code>.</p> <p>For scenarios where royalties are to be distributed to holders directly, then implementation of the <code>tip</code> method of <code>ITipToken</code> contract MAY send the royalty amount straight from the user's account to the holder of a single NFT or to the shared holders of a multi token, less an optional agreed fee. In this case, the tip token type is the reward token.</p> <h3 id="caveats">Caveats</h3> <p>To keep the <code>ITipToken</code> interface simple and general purpose, each tip token contract MUST use one EIP-20 compatible deposit type at a time. If tipping is required to support many EIP-20 deposits then each tip token contract MUST be deployed separately per EIP-20 compatible type required. Thus, if tipping is required from both ETH and BTC wrapper EIP-20 deposits then the tip token contract is deployed twice. The tip token contract's constructor is REQUIRED to pass in the address of the EIP-20 token supported for the deposits for the particular tip token contract. Or in the case for upgradeable tip token contracts, an initialize method is REQUIRED to pass in the EIP-20 token address.</p> <p>This EIP does not provide details for where the EIP-20 reward deposits are held. It MUST be available at the time a holder withdraws the rewards that they are owed. A RECOMMENDED implementation would be to keep the deposits locked in the tip token contract address. By keeping a mapping structure that records the balances pending to holders then the deposits can remain where they are when a user tips, and only transferred out to a holder's address when a holder withdraws it as their reward.</p> <p>This standard does not specify the type of EIP-20 compatible deposits allowed. Indeed, could be tip tokens themselves. But it is RECOMMENDED that balances of the deposits be checked after transfer to find out the exact amount deposited to keep internal accounting consistent. In case, for example, the EIP-20 contract takes fees and hence reduces the actual amount deposited.</p> <p>This standard does not specify any functionality for refunds for deposits nor for tip tokens sent, it is left to the implementor to add this to their smart contract(s). The reasoning for this is to keep the interface light and not to enforce upon implementors the need for refunds but to leave that as a choice.</p> <h3 id="minimising-gas-costs">Minimising Gas Costs</h3> <p>By caching tips off-chain and then batching them up to call the <code>tipBatch</code> method of the ITipToken interface then essentially the cost of initialising transactions is paid once rather than once per tip. Plus, further gas savings can be made off-chain if multiple tips sent by the same user to the same NFT token are accumulated together and sent as one entry in the batch.</p> <p>Further savings can be made by grouping users together sending to the same NFT, so that checking the validity of the NFT and whether it is an EIP-721 or EIP-1155, is performed once for each group.</p> <p>Clever ways to minimise on-chain state updating of the deposit balances for each user and the reward balances of each holder, can help further to minimise the gas costs when sending in a batch if the batch is ordered beforehand. For example, can avoid the checks if the next NFT in the batch is the same. This left to the tip token contract implementer. Whatever optimisation is applied, it MUST still allow information of which account tipped which account and for what NFT to be reconstructed from the Tip and the TipBatch events emitted.</p> <h2 id="rationale">Rationale</h2> <h3 id="simplicity">Simplicity</h3> <p>ITipToken interface uses a minimal number of functions, in order to keep its use as general purpose as possible, whilst there being enough to guide implementation that fulfils its purpose for micropayments to NFT holders.</p> <h3 id="use-of-nfts">Use of NFTs</h3> <p>Each NFT is a unique non-fungible token digital asset stored on the blockchain that are uniquely identified by its address and token id. It's truth burnt using cryptographic hashing on a secure blockchain means that it serves as an anchor for linking with a unique digital asset, service or other contractual agreement. Such use cases may include (but only really limited by imagination and acceptance):</p> <ul> <li>Digital art, collectibles, music, video, licenses and certificates, event tickets, ENS names, gaming items, objects in metaverses, proof of authenticity of physical items, service agreements etc.</li> </ul> <p>This mechanism allows consumers of the NFT a secure way to easily tip and reward the NFT holder.</p> <h3 id="new-business-models">New Business Models</h3> <p>To take the music use case for example. Traditionally since the industry transitioned from audio distributed on physical medium such as CDs, to an online digital distribution model via streaming, the music industry has been controlled by oligopolies that served to help in the transition. They operate a fixed subscription model and from that they set the amount of royalty distribution to content creators; such as the singers, musicians etc. Using tip tokens represent an additional way for fans of music to reward the content creators. Each song or track is represented by an NFT and fans are able to tip the song (hence the NFT) that they like, and in turn the content creators of the NFT are able to receive the EIP-20 rewards that the tips were bought for. A fan led music industry with decentralisation and tokenisation is expected to bring new revenue, and bring fans and content creators closer together.</p> <p>Across the board in other industries a similar ethos can be applied where third party controllers move to a more facilitating role rather than a monetary controlling role that exists today.</p> <h3 id="guaranteed-audit-trail">Guaranteed audit trail</h3> <p>As the Ethereum ecosystem continues to grow, many dapps are relying on traditional databases and explorer API services to retrieve and categorize data. This EIP standard guarantees that event logs emitted by the smart contract MUST provide enough data to create an accurate record of all current tip token and EIP-20 reward balances. A database or explorer can provide indexed and categorized searches of every tip token and reward sent to NFT holders from the events emitted by any tip token contract that implements this standard. Thus, the state of the tip token contract can be reconstructed from the events emitted alone.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>A tip token contract can be fully compatible with EIP-20 specification and inherit some functions such as transfer if the tokens are allowed to be sent directly to other users. Note that balanceOf has been adopted and MUST be the number of tips held by a user's address. If inheriting from, for example, OpenZeppelin's implementation of EIP-20 token then their contract is responsible for maintaining the balance of tip token. Therefore, tip token balanceOf function SHOULD simply directly call the parent (super) contract's balanceOf function.</p> <p>What hasn't been carried over to tip token standard, is the ability for a spender of other users' tips. For the moment, this standard does not foresee a need for this.</p> <p>This EIP does not stress a need for tip token secondary markets or other use cases where identifying the tip token type with names rather than addresses might be useful, so these functions were left out of the ITipToken interface and is the remit for implementers.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Though it is RECOMMENDED that users' deposits are kept locked in the tip token contract or external escrow account, and SHOULD NOT be used for anything but the rewards for holders, this cannot be enforced. This standard stipulates that the rewards MUST be available for when holders withdraw their rewards from the pool of deposits.</p> <p>Before any users can tip an NFT, the holder of the NFT has to give their approval for tipping from the tip token contract. This standard stipulates that holders of the NFTs receive the rewards. It SHOULD be clear in the tip token contract code that it does so, without obfuscation to where the rewards go. Any fee charges SHOULD be made obvious to users before acceptance of their deposit. There is a risk that rogue implementers may attempt to *hijack* potential tip income streams for their own purposes. But additionally the number and frequency of transactions of the tipping process should make this type of fraud quicker to be found out.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-10-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Rex Creedhttps://github.com/aug2uag Dane Scarboroughdane@nftapps.us https://wg-eips.ritovision.com/4353/

This interface enables access to publicly viewable staking data of an NFT.

<h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/721/">EIP-721</a> tokens can be deposited or staked in NFTs for a variety of reasons including escrow, rewards, benefits, and others. There is currently no means of retrieving the number of tokens staked and/or bound to an NFT. This proposal outlines a standard that may be implemented by all wallets and marketplaces easily to correctly retrieve the staked token amount of an NFT.</p> <h2 id="motivation">Motivation</h2> <p>Without staked token data, the actual amount of staked tokens cannot be conveyed from token owners to other users, and cannot be displayed in wallets, marketplaces, or block explorers. The ability to identify and verify an exogenous value derived from the staking process may be critical to the aims of an NFT holder.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Interface of the ERC4353 standard, as defined in the</span></span> <span class="giallo-l"><span class="z-comment"> * https://eips.ethereum.org/EIPS/eip-4353.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Implementers can declare support of contract interfaces, which can then be</span></span> <span class="giallo-l"><span class="z-comment"> * queried by others.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment">: The ERC-165 identifier for this interface is 0x3a3d855f.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC721Staked</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns uint256 amount of on-chain tokens staked to the NFT.</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Wallets and marketplaces would need to call this for displaying</span></span> <span class="giallo-l"><span class="z-comment"> * the amount of tokens staked and/or bound to the NFT.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> stakedAmount</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="suggested-flow">Suggested flow:</h3> <h4 id="constructor-deployment">Constructor/deployment</h4> <ul> <li>Creator - the owner of an NFT with its own rules for depositing tokens at and/or after the minting of a token.</li> <li>Token Amount - the current amount of on-chain <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> or derived tokens bound to an NFT from one or more deposits.</li> <li>Withdraw Mechanism - rules based approach for withdrawing staked tokens and making sure to update the balance of the staked tokens.</li> </ul> <h3 id="staking-at-mint-and-locking-tokens-in-nft">Staking at mint and locking tokens in NFT</h3> <p>The suggested and intended implementation of this standard is to stake tokens at the time of minting an NFT, and not implementing any outbound transfer of tokens outside of <code>burn</code>. Therefore, only to stake at minting and withdraw only at burning.</p> <h4 id="nft-displayed-in-wallet-or-marketplace">NFT displayed in wallet or marketplace</h4> <p>A wallet or marketplace checks if an NFT has publicly staked tokens available for display - if so, call <code>stakedAmount(tokenId)</code> to get the current amount of tokens staked and/or bound to the NFT.</p> <p>The logical code looks something like this and inspired by William Entriken:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> contracts/Token.sol</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/access/Ownable.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> Token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Very simple ERC721 example with stake interface example.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment"> this implementation enforces recommended procedure:</span></span> <span class="giallo-l"><span class="z-comment"> * 1) stake at mint</span></span> <span class="giallo-l"><span class="z-comment"> * 2) withdraw at burn</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC721Staked</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721URIStorage</span><span>, </span><span class="z-entity z-name">Ownable</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> track original minter of tokenId</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span> (</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> address</span><span> payable</span><span>)</span><span class="z-storage z-type"> private</span><span> payees</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> map tokens to stored staked token value</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span> (</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> tokenValue</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> metadata</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span class="z-entity z-name"> ERC721</span><span> (</span></span> <span class="giallo-l"><span> &quot;Staked NFT&quot;, </span></span> <span class="giallo-l"><span> &quot;SNFT&quot;</span></span> <span class="giallo-l"><span> )</span><span>{</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> mints a new NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> address that will own the minted NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> id the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _uri</span><span class="z-comment"> metadata</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mint</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> payable</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _uri</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> payable</span></span> <span class="giallo-l"><span class="z-entity z-name"> onlyOwner</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _mint</span><span>(</span><span>_to</span><span>,</span><span> _tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setTokenURI</span><span>(</span><span>_tokenId</span><span>,</span><span> _uri</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> payees</span><span>[</span><span>_tokenId</span><span>]</span><span class="z-keyword"> =</span><span> _to</span><span>;</span></span> <span class="giallo-l"><span> tokenValue</span><span>[</span><span>_tokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> msg</span><span>.</span><span>value</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> staked interface</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> id of the NFT</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> _value</span><span class="z-comment"> staked value</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> stakedAmount</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _value </span><span class="z-keyword">=</span><span> tokenValue</span><span>[</span><span>_tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _value</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> removes NFT &amp; transfers crypto to minter</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _tokenId</span><span class="z-comment"> the NFT we want to remove</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> burn</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-entity z-name"> onlyOwner</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">_burn</span><span>(</span><span>_tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> payees</span><span>[</span><span>_tokenId</span><span>]</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>tokenValue</span><span>[</span><span>_tokenId</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> tokenValue</span><span>[</span><span>_tokenId</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This standard is completely agnostic to how tokens are deposited or handled by the NFT. It is, therefore, the choice and responsibility of the author to encode and communicate the encoding of their tokenomics to purchasees of their token and/or to make their contracts viewable by purchasees.</p> <p>Although the intention of this standard is for tokens staked at mint and withdrawable only upon burn, the interface may be modified for dynamic withdrawing and depositing of tokens especially under DeFi application settings. In its current form, the contract logic may be the determining factor whether a deviation from the standard exists.</p> <h2 id="backward-compatibility">Backward Compatibility</h2> <p>TBD</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">const</span><span> {</span><span class="z-variable z-other z-constant"> expect</span><span> }</span><span class="z-keyword"> =</span><span class="z-entity z-name"> require</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">chai</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span> {</span><span class="z-variable z-other z-constant"> ethers</span><span>,</span><span class="z-variable z-other z-constant"> waffle</span><span> }</span><span class="z-keyword"> =</span><span class="z-entity z-name"> require</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">hardhat</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> provider</span><span class="z-keyword"> =</span><span class="z-variable z-other"> waffle</span><span>.</span><span class="z-variable z-other">provider</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">describe</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">StakedNFT</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> _id</span><span class="z-keyword"> =</span><span class="z-constant"> 1234567890</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> value</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">1.5</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> Token</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> Interface</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> owner</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> addr1</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> addr2</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> beforeEach</span><span>(</span><span class="z-storage">async</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> Token</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-entity z-name">getContractFactory</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC721Staked</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> [</span><span class="z-variable z-other">owner</span><span>,</span><span class="z-variable z-other"> addr1</span><span>,</span><span class="z-keyword"> ...</span><span class="z-variable z-other">addr2</span><span>]</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-entity z-name">getSigners</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> Interface</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> Token</span><span>.</span><span class="z-entity z-name">deploy</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> describe</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Staked NFT</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> it</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Should set the right owner</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage"> async</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> mint</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> addr1</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> _id</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">http://foobar</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span class="z-variable z-other">_id</span><span>)</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">addr1</span><span>.</span><span class="z-variable z-other">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> it</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Should not have staked balance without value</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage"> async</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> mint</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> addr1</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> _id</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">http://foobar</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">stakedAmount</span><span>(</span><span class="z-variable z-other">_id</span><span>)</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">parseEther</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> it</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Should set and return the staked amount</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage"> async</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> mint</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> addr1</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> _id</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">http://foobar</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> {</span><span>value</span><span>:</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">parseEther</span><span>(</span><span class="z-variable z-other">value</span><span>)</span><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">stakedAmount</span><span>(</span><span class="z-variable z-other">_id</span><span>)</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">parseEther</span><span>(</span><span class="z-variable z-other">value</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> it</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Should decrease owner eth balance on mint (deposit)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage"> async</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> balance1</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> provider</span><span>.</span><span class="z-entity z-name">getBalance</span><span>(</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> mint</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> addr1</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> _id</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">http://foobar</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> {</span><span>value</span><span>:</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">parseEther</span><span>(</span><span class="z-variable z-other">value</span><span>)</span><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> balance2</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> provider</span><span>.</span><span class="z-entity z-name">getBalance</span><span>(</span><span class="z-variable z-other">owner</span><span>.</span><span class="z-variable z-other">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> diff</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseFloat</span><span>(</span><span class="z-variable z-other">ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">formatEther</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> balance1</span><span>.</span><span class="z-entity z-name">sub</span><span>(</span><span class="z-variable z-other">balance2</span><span>)</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">toFixed</span><span>(</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">diff</span><span class="z-keyword"> ===</span><span class="z-variable z-other"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> it</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Should add to payee&#39;s eth balance on burn (withdraw)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage"> async</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> balance1</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> provider</span><span>.</span><span class="z-entity z-name">getBalance</span><span>(</span><span class="z-variable z-other">addr1</span><span>.</span><span class="z-variable z-other">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> mint</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> addr1</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> _id</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">http://foobar</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> {</span><span>value</span><span>:</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">parseEther</span><span>(</span><span class="z-variable z-other">value</span><span>)</span><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">burn</span><span>(</span><span class="z-variable z-other">_id</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> balance2</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> provider</span><span>.</span><span class="z-entity z-name">getBalance</span><span>(</span><span class="z-variable z-other">addr1</span><span>.</span><span class="z-variable z-other">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> diff</span><span class="z-keyword"> =</span><span class="z-entity z-name"> parseFloat</span><span>(</span><span class="z-variable z-other">ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">formatEther</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> balance2</span><span>.</span><span class="z-entity z-name">sub</span><span>(</span><span class="z-variable z-other">balance1</span><span>)</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">toFixed</span><span>(</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-variable z-other">diff</span><span class="z-keyword"> ===</span><span class="z-variable z-other"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> it</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Should update balance after transfer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage"> async</span><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> mint</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> addr1</span><span>.</span><span class="z-variable z-other">address</span><span>,</span><span class="z-variable z-other"> _id</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">http://foobar</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> {</span><span>value</span><span>:</span><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">parseEther</span><span>(</span><span class="z-variable z-other">value</span><span>)</span><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">burn</span><span>(</span><span class="z-variable z-other">_id</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> expect</span><span>(</span><span class="z-keyword">await</span><span class="z-variable z-other"> Interface</span><span>.</span><span class="z-entity z-name">stakedAmount</span><span>(</span><span class="z-variable z-other">_id</span><span>)</span><span>)</span><span>.</span><span class="z-variable z-other">to</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> ethers</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">parseEther</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>The purpose of this standard is to simply and publicly identify whether an NFT claims to have staked tokens.</p> <p>Staked claims will be unreliable without a locking mechanism enforced, for example, if staked tokens can only be transferred at burn. Otherwise, tokens may be deposited and/or withdrawn at any time via arbitrary methods. Also, contracts that may allow arbitrary transfers without updating the correct balance will result in potential issues. A strict rules-based approach should be taken with these edge cases in mind.</p> <p>A dedicated service may exist to verify the claims of a token by analyzing transactions on the explorer. In this manner, verification may be automated to ensure a token's claims are valid. The logical extension of this method may be to extend the interface and support flagging erroneous claims, all the while maintaining a simple goal of validating and verifying a staked amount exists to benefit the operator experience.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-10-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Simon Tianhttps://github.com/simontianx https://wg-eips.ritovision.com/4341/

The ordering information of multiple NFTs is retained and managed

<h2 id="abstract">Abstract</h2> <p>This standard introduces a smart contract interface that can represent a batch of non-fungible tokens of which the ordering information shall be retained and managed. Such information is particularly useful if <code>tokenId</code>s are encoded with the sets of <code>unicodes</code> for logographic characters and emojis. As a result, NFTs can be utilized as carriers of meanings.</p> <h2 id="motivation">Motivation</h2> <p>Non-fungible tokens are widely accepted as carriers of crypto-assets, hence in both <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>, the ordering information of multiple NFTs is discarded. However, as proposed in <a href="https://wg-eips.ritovision.com/3754/">EIP-3754</a>, non-fungible tokens are thought of as basic units on a blockchain and can carry abstract meanings with unicoded <code>tokenId</code>s. Transferring such tokens is transmitting an ordered sequence of unicodes, thus effectively transmitting phrases or meanings on a blockchain.</p> <p>A <strong><a rel="external" href="https://en.wikipedia.org/wiki/Logogram">logograph</a></strong> is a written character that represents a word or morpheme, examples include <em>hanzi</em> in Mandarin, <em>kanji</em> in Japanese, <em>hanja</em> in Korean, and etc. A <a rel="external" href="https://en.wikipedia.org/wiki/Unicode">unicode</a> is an information technology standard for the consistent encoding, representation, and handling of texts.</p> <p>It is natural to combine the two to create unicoded NFTs to represent logographic characters. Since a rich amount of meanings can be transmitted in just a few characters in such languages, it is technically practical and valuable to create a standard for it. Emojis are similar with logographs and can be included as well. For non-logographic languages such as English, although the same standard can be applied, it is tedious to represent each letter with an NFT, hence the gain is hardly justifiable.</p> <p>A motivating example is instead of sending the two Chinese characters of the Great Wall <code>长城</code>, two NFTs with IDs <code>#38271</code> and <code>#22478</code> respectively can be transferred in a batch. The two IDs are corresponding to the decimal unicode of the two characters. The receiving end decodes the IDs and retrieves the original characters. A key point is the ordering information matters in this scenario since the tuples <code>(38271, 22478)</code> and <code>(22478, 38271)</code> can be decoded as <code>长城</code> and <code>城长</code>, respectively, and both are legitimate words in the Chinese language. This illustrates the key difference between this standard and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a>.</p> <p>Besides, in the eastern Asian culture, characters are sometimes considered or practically used as gifts in holidays such as Spring Feastival, etc. <code>(24685, 21916, 21457, 36001)</code> <code>恭喜发财</code> can be used literally as a gift to express the best wishes for financial prosperity. It is therefore cuturally natural to transfer tokens to express meanings with this standard.</p> <p>Also in logographic language systems, ancient teachings are usually written in concise ways such that a handful of characters can unfold a rich amount of meanings. Modern people now get a reliable technical means to pass down their words, poems and proverbs to the future generations by sending tokens.</p> <p>Other practical and interesting applications include Chinese chess, wedding vows, family generation quotes and sayings, funeral commendation words, prayers, anecdotes and etc.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.8.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> @title EIP-4341 Multi Ordered NFT Standard</span></span> <span class="giallo-l"><span> @dev See https://eips.ethereum.org/EIPS/eip-4341</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>interface ERC4341 /* is ERC165 */ {</span></span> <span class="giallo-l"><span> event Transfer(address indexed from, address indexed to, uint256 id, uint256 amount);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> event TransferBatch(address indexed from, address indexed to, uint256[] ids, uint256[] amounts);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> event ApprovalForAll(address indexed owner, address indexed operator, bool approved);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes calldata data) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function safeBatchTransferFrom(address from, address to, uint256[] calldata ids, uint256[] calldata amounts, bytes calldata data) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function safePhraseTransferFrom(address from, address to, uint256[] calldata phrase, bytes calldata data) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function balanceOf(address owner, uint256 id) external view returns (uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function balanceOfPhrase(address owner) external view returns (uint256);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function balanceOfBatch(address[] calldata owners, uint256[] calldata ids) external view returns (uint256[] memory);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function retrievePhrase(address owner, uint256 phraseId) external view returns (uint256[] memory);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function setApprovalForAll(address operator, bool approved) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function isApprovedForAll(address owner, address operator) external view returns (bool);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>In <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> and <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, NFTs are used to represent crypto-assets, and in this standard together with <a href="https://wg-eips.ritovision.com/3754/">EIP-3754</a>, NFTs are equipped with utilities. In this standard, the ordering information of a batch of NFTs is retained and managed through a construct <code>phrase</code>.</p> <h3 id="phrase">Phrase</h3> <p>A <code>phrase</code> is usually made of a handful of basic characters or an orderred sequence of unicodes and is able to keep the ordering information in a batch of tokens. Technically, it is stored in an array of unsigned integers, and is not supposed to be disseminated. A phrase does not increase or decrease the amount of any NFT in anyway. A phrase cannot be transferred, however, it can be retrieved and decoded to restore the original sequence of unicodes. The phrase information is kept in storage and hence additional storage than <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> is required.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><a href="https://wg-eips.ritovision.com/3754/">EIP-3754</a> is the pre-requisite to this standard.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>https://github.com/simontianx/ERC4341</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-09-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Devin Conleyhttps://github.com/devinaconley https://wg-eips.ritovision.com/4987/

Interface to query ownership and balance of held tokens

<h2 id="abstract">Abstract</h2> <p>The proposed standard defines a lightweight interface to expose functional ownership and balances of held tokens. A held token is a token owned by a contract. This standard may be implemented by smart contracts which hold <a href="https://wg-eips.ritovision.com/20/">EIP-20</a>, <a href="https://wg-eips.ritovision.com/721/">EIP-721</a>, or <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> tokens and is intended to be consumed by both on-chain and off-chain systems that rely on ownership and balance verification.</p> <h2 id="motivation">Motivation</h2> <p>As different areas of crypto (DeFi, NFTs, etc.) converge and composability improves, there will more commonly be a distinction between the actual owner (likely a contract) and the functional owner (likely a user) of a token. Currently, this results in a conflict between mechanisms that require token deposits and systems that rely on those tokens for ownership or balance verification.</p> <p>This proposal aims to address that conflict by providing a standard interface for token holders to expose ownership and balance information. This will allow users to participate in these DeFi mechanisms without giving up existing token utility. Overall, this would greatly increase interoperability across systems, benefiting both users and protocol developers.</p> <p>Example implementers of this ERC standard include</p> <ul> <li>staking or farming contracts</li> <li>lending pools</li> <li>time lock or vesting vaults</li> <li>fractionalized NFT contracts</li> <li>smart contract wallets</li> </ul> <p>Example consumers of this ERC standard include</p> <ul> <li>governance systems</li> <li>gaming</li> <li>PFP verification</li> <li>art galleries or showcases</li> <li>token based membership programs</li> </ul> <h2 id="specification">Specification</h2> <p>Smart contracts implementing the <code>ERC20</code> held token standard MUST implement all of the functions in the <code>IERC20Holder</code> interface.</p> <p>Smart contracts implementing the <code>ERC20</code> held token standard MUST also implement <code>ERC165</code> and return true when the interface ID <code>0x74c89d54</code> is passed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> the ERC20 holder standard provides a common interface to query</span></span> <span class="giallo-l"><span class="z-comment"> * token balance information</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC20Holder</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> emitted when the token is transferred to the contract</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> functional token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAmount</span><span class="z-comment"> held token amount</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Hold</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenAmount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> emitted when the token is released back to the user</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> functional token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAmount</span><span class="z-comment"> held token amount</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Release</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenAmount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> get the held balance of the token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> should throw for invalid queries and return zero for no balance</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> functional token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> held</span><span class="z-comment"> token balance</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> heldBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenAddress</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>Smart contracts implementing the <code>ERC721</code> held token standard MUST implement all of the functions in the <code>IERC721Holder</code> interface.</p> <p>Smart contracts implementing the <code>ERC721</code> held token standard MUST also implement <code>ERC165</code> and return true when the interface ID <code>0x16b900ff</code> is passed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> the ERC721 holder standard provides a common interface to query</span></span> <span class="giallo-l"><span class="z-comment"> * token ownership and balance information</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC721Holder</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> emitted when the token is transferred to the contract</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> functional token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> held token ID</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Hold</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> emitted when the token is released back to the user</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> functional token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> held token ID</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Release</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> get the functional owner of a held token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> should throw for invalid queries and return zero for a token ID that is not held</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> held token ID</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> functional</span><span class="z-comment"> token owner</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> heldOwnerOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> get the held balance of the token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> should throw for invalid queries and return zero for no balance</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> functional token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> held</span><span class="z-comment"> token balance</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> heldBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> tokenAddress</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> owner</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Smart contracts implementing the <code>ERC1155</code> held token standard MUST implement all of the functions in the <code>IERC1155Holder</code> interface.</p> <p>Smart contracts implementing the <code>ERC1155</code> held token standard MUST also implement <code>ERC165</code> and return true when the interface ID <code>0xced24c37</code> is passed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> the ERC1155 holder standard provides a common interface to query</span></span> <span class="giallo-l"><span class="z-comment"> * token balance information</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC1155Holder</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> emitted when the token is transferred to the contract</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> functional token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> held token ID</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAmount</span><span class="z-comment"> held token amount</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Hold</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenAmount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> emitted when the token is released back to the user</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> functional token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> held token ID</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAmount</span><span class="z-comment"> held token amount</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Release</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenAmount</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> get the held balance of the token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> should throw for invalid queries and return zero for no balance</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenAddress</span><span class="z-comment"> held token address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> owner</span><span class="z-comment"> functional token owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> held token ID</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> held</span><span class="z-comment"> token balance</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> heldBalanceOf</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> tokenAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> owner</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This interface is designed to be extremely lightweight and compatible with any existing token contract. Any token holder contract likely already stores all relevant information, so this standard is purely adding a common interface to expose that data.</p> <p>The token address parameter is included to support contracts that can hold multiple token contracts simultaneously. While some contracts may only hold a single token address, this is more general to either scenario.</p> <p>Separate interfaces are proposed for each token type (EIP-20, EIP-721, EIP-1155) because any contract logic to support holding these different tokens is likely independent. In the scenario where a single contract does hold multiple token types, it can simply implement each appropriate held token interface.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Importantly, the proposed specification is fully compatible with all existing EIP-20, EIP-721, and EIP-1155 token contracts.</p> <p>Token holder contracts will need to be updated to implement this lightweight interface.</p> <p>Consumer of this standard will need to be updated to respect this interface in any relevant ownership logic.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A full example implementation including <a href="https://wg-eips.ritovision.com/4987/./assets/IERC721Holder.sol">interfaces</a>, a vault <a href="https://wg-eips.ritovision.com/4987/./assets/Vault.sol">token holder</a>, and a <a href="https://wg-eips.ritovision.com/4987/./assets/Consumer.sol">consumer</a>, can be found at <code>assets/eip-4987/</code>.</p> <p>Notably, consumers of the <code>IERC721Holder</code> interface can do a chained lookup for the owner of any specific token ID using the following logic.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> get the functional owner of a token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> token id of interest</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getOwner</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> get raw owner</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> owner </span><span class="z-keyword">=</span><span> token</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if owner is not contract, return</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>owner</span><span>.</span><span class="z-entity z-name">isContract</span><span>(</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check for token holder interface support</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span class="z-entity z-name"> IERC165</span><span>(</span><span>owner</span><span>)</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-constant">0x16b900ff</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> ret</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-keyword">!</span><span>ret</span><span>)</span><span class="z-keyword"> return</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> catch</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check for held owner</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span class="z-entity z-name"> IERC721Holder</span><span>(</span><span>owner</span><span>)</span><span>.</span><span class="z-entity z-name">heldOwnerOf</span><span>(</span><span class="z-support">address</span><span>(</span><span>token</span><span>)</span><span>,</span><span> tokenId</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>user </span><span class="z-keyword">!=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span class="z-keyword"> return</span><span> user</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> catch</span><span> {</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Consumers of this standard should be cautious when using ownership information from unknown contracts. A bad actor could implement the interface, but report invalid or malicious information with the goal of manipulating a governance system, game, membership program, etc.</p> <p>Consumers should also verify the overall token balance and ownership of the holder contract as a sanity check.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-09-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Anton Bukovhttps://github.com/k06a Mikhail Melnikhttps://github.com/ZumZoom https://wg-eips.ritovision.com/3978/

Reprice reverted SSTORE/CREATE/SELFDESTRUCT/LOGX operations gas via gas refund mechanism

<h2 id="abstract">Abstract</h2> <p>For reverted state modification operations, keep access cost, but refund modification cost.</p> <h2 id="motivation">Motivation</h2> <p>Reverting a transaction, or any of its sub-calls, drops any state modifications that happened inside. But now, users are being charged for the dropped modifications as if they persisted.</p> <p>Since <a href="https://wg-eips.ritovision.com/3298/">EIP-3298</a>, the gas refund mechanism works for storage restores only inside the same transaction. But on revert, the gas refund is not increased; it is completely erased. It can even be cheaper to transfer tokens back at the end of a transaction instead of reverting, to keep the existing gas refund. This should be changed.</p> <ul> <li>Reverted SSTORE deserves to be repriced to SLOAD gas (100 gas)</li> <li>Reverted LOG0, LOG1, LOG2, LOG3 and LOG4 deserve to be repriced to 100 gas</li> <li>Reverted CALL with value (<code>positive_value_cost</code> = 9,000 gas) deserves to be repriced to 100 gas</li> <li>Reverted CALL with value and account creation (<code>value_to_empty_account_cost</code> = 25,000 gas) deserves to be repriced to 100 gas</li> <li>Reverted CREATE and CREATE2 (32,000 gas) deserve to be repriced to 100 gas</li> <li>Reverted SELFDESTRUCT (5,000 or 25,000 gas) deserves to be repriced to 100 gas</li> </ul> <p>Moreover, it seems fair to charge CREATE and CREATE2 operations 32,000 fix price conditionally only if returned bytecode is not empty.</p> <h2 id="specification">Specification</h2> <p>For each callframe, track <code>revert_gas_refund</code>, initially 0.</p> <p>The set of operations that modify <code>revert_gas_refund</code> are:</p> <ul> <li>SSTORE</li> <li>LOG0, LOG1, LOG2, LOG3, LOG4</li> <li>CALL</li> <li>CREATE, CREATE2</li> <li>SELFDESTRUCT</li> </ul> <p>They increase <code>revert_gas_refund</code> as follows:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">call</span><span>.</span><span class="z-variable z-other">revert_gas_refund</span><span class="z-keyword"> +=</span><span class="z-variable z-other"> operation</span><span>.</span><span class="z-variable z-other">gas</span><span class="z-keyword"> -</span><span class="z-variable z-other z-constant"> WARM_STORAGE_READ_COST</span></span></code></pre> <p>And in case of revert let's use this value instead of just erasing <code>gas_refund</code>:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-keyword">if</span><span> (</span><span class="z-variable z-other">call</span><span>.</span><span class="z-variable z-other">reverted</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> existing behavior</span></span> <span class="giallo-l"><span class="z-variable z-other"> tx</span><span>.</span><span class="z-variable z-other">gas_refund</span><span class="z-keyword"> -=</span><span class="z-variable z-other"> call</span><span>.</span><span class="z-variable z-other">gas_refund</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> New behavior added to existing according to the EIP-3978</span></span> <span class="giallo-l"><span class="z-variable z-other"> tx</span><span>.</span><span class="z-variable z-other">gas_refund</span><span class="z-keyword"> +=</span><span class="z-variable z-other"> call</span><span>.</span><span class="z-variable z-other">revert_gas_refund</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Gas should reflect the cost of use. The revert cost reflects the cost of access during execution, but not the cost of modification.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No known backward incompatibilities.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-09-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gregory Markouhttps://github.com/GregTheGreek https://wg-eips.ritovision.com/3788/

Reject transactions that do not explicitly have the same chainId as the node's configuration.

<h2 id="abstract">Abstract</h2> <p>Reject transactions that do not explicitly have the same chainId as the node's configuration.</p> <h2 id="motivation">Motivation</h2> <p>Per <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> a transaction with a <code>chainId = 0</code> is considered to be a valid transaction. This was a feature to offer developers the ability to submit replayable transactions across different chains. With the rise of evm compatible chains, many of which use forks, or packages from popular Ethereum clients, we are putting user funds at risk. This is because most wallet interfaces do not expose the chainId to the user, meaning they typically do not have insight into what chainId they are signing. Should a malicious actor (or accidental) choose to, they can easily have users submit transactions with a <code>chainId = 0</code> on a non-mainnet network, allowing the malicious actor to replay the transaction on ethereum mainnet (or other networks for that matter) as a grief or sophisticated attack.</p> <h2 id="specification">Specification</h2> <p>As of the fork block <code>N</code>, consider transactions with a <code>chaindId = 0</code> to be invalid. Such that transactions are verified based on the nodes configuration. Eg:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>if (node.cfg.chainId != tx.chainId) {</span></span> <span class="giallo-l"><span> // Reject transaction</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The configuration set by the node is the main source of truth, and thus should be explicitly used when deciding how to filter out a transaction. This check should exist in two places, as a filter on the JSON-RPC (eg: <code>eth_sendTransaction</code>), and strictly enforced on the EVM during transaction validation.</p> <p>This ensures that users will not have transactions pending that will be guaranteed to fail, and prevents the transaction from being included in a block.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This breaks all applications or tooling that submit transactions with a <code>chainId == 0</code> after block number <code>N</code>.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>It should be noted this will not prevent a malicious actor from deploying a network with <code>chainId = 1</code>, or copying any other networks chainId.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-08-27T00:00:00+00:00 2026-02-11T14:48:26+00:00 Soham Zemsehttps://github.com/zemse https://wg-eips.ritovision.com/3772/

Using lossy compression on uint256 to improve gas costs, ideally by a factor up to 4x.

<h2 id="abstract">Abstract</h2> <p>This document specifies compression of <code>uint256</code> to smaller data structures like <code>uint64</code>, <code>uint96</code>, <code>uint128</code>, for optimizing costs for storage. The smaller data structure (represented as <code>cintx</code>) is divided into two parts, in the first one we store <code>significant</code> bits and in the other number of left <code>shift</code>s needed on the significant bits to decompress. This document also includes two specifications for decompression due to the nature of compression being lossy, i.e. it causes underflow.</p> <h2 id="motivation">Motivation</h2> <ul> <li>Storage is costly, each storage slot costs almost $0.8 to initialize and $0.2 to update (20 gwei, 2000 ETHUSD).</li> <li>Usually, we store money amounts in <code>uint256</code> which takes up one entire slot.</li> <li>If it's DAI value, the range we work with most is 0.001 DAI to 1T DAI (or 10¹²). If it's ETH value, the range we work with most is 0.000001 ETH to 1B ETH. Similarly, any token of any scale has a reasonable range of 10¹⁵ amounts that we care/work with.</li> <li>However, uint256 type allows us to represent $10^-18 to $10⁵⁸, and most of it is a waste. In technical terms, we have the probability distribution for values larger than $10¹⁵ and smaller than $10^-3 as negligible (i.e. P[val &gt; 10¹⁵] ≈ 0 and P[val &lt; 10^-3] ≈ 0).</li> <li>Number of bits required to represent 10¹⁵ values = log₂(10¹⁵) = 50 bits. So just 50 bits (instead of 256) are reasonably enough to represent a practical range of money, causing a very negligible difference.</li> </ul> <h2 id="specification">Specification</h2> <p>In this specification, the structure for representing a compressed value is represented using <code>cintx</code>, where x is the number of bits taken by the entire compressed value. On the implementation level, an <code>uintx</code> can be used for storing a <code>cintx</code> value.</p> <h3 id="compression">Compression</h3> <h4 id="uint256-into-cint64-up-to-cint120">uint256 into cint64 (up to cint120)</h4> <p>The rightmost, or least significant, 8 bits in <code>cintx</code> are reserved for storing the shift and the rest available bits are used to store the significant bits starting from the first <code>1</code> bit in <code>uintx</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> cint64</span><span> {</span><span class="z-support"> uint56</span><span> significant</span><span>;</span><span class="z-support"> uint8</span><span> shift</span><span>;</span><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> cint120</span><span> {</span><span class="z-support"> uint112</span><span> significant</span><span>;</span><span class="z-support"> uint8</span><span> shift</span><span>;</span><span> }</span></span></code></pre><h4 id="uint256-into-cint128-up-to-cint248">uint256 into cint128 (up to cint248)</h4> <p>The rightmost, or least significant, 7 bits in <code>cintx</code> are reserved for storing the shift and the rest available bits are used to store the significant bits starting from the first one bit in <code>uintx</code>.</p> <blockquote> <p>In the following code example, <code>uint7</code> is used just for representation purposes only, but it should be noted that uints in Solidity are in multiples of 8.</p> </blockquote> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> cint128</span><span> {</span><span class="z-support"> uint121</span><span> significant</span><span>;</span><span class="z-support"> uint7</span><span> shift</span><span>;</span><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> cint248</span><span> {</span><span class="z-support"> uint241</span><span> significant</span><span>;</span><span class="z-support"> uint7</span><span> shift</span><span>;</span><span> }</span></span></code></pre> <p>Examples:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Example:</span></span> <span class="giallo-l"><span>uint256 value: 2**100, binary repr: 1000000...(hundred zeros)</span></span> <span class="giallo-l"><span>cint64 { significant: 10000000...(55 zeros), shift: 00101101 (45 in decimal)}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Example:</span></span> <span class="giallo-l"><span>uint256 value: 2**100-1, binary repr: 111111...(hundred ones)</span></span> <span class="giallo-l"><span>cint64 { significant: 11111111...(56 ones), shift: 00101100 (44 in decimal) }</span></span></code></pre><h3 id="decompression">Decompression</h3> <p>Two decompression methods are defined: a normal <code>decompress</code> and a <code>decompressRoundingUp</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">library</span><span class="z-entity z-name"> CInt64</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> packs the uint256 amount into a cint64</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> compress</span><span>(</span><span class="z-support">uint256</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">cint64</span><span>)</span><span> {</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> unpacks cint64, by shifting the significant bits left by shift</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> decompress</span><span>(</span><span class="z-variable">cint64</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> unpacks cint64, by shifting the significant bits left by shift</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> and having 1s in the shift bits</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> decompressRoundingUp</span><span>(</span><span class="z-variable">cint64</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span><span>}</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="normal-decompression">Normal Decompression</h4> <p>The <code>significant</code> bits in the <code>cintx</code> are moved to a <code>uint256</code> space and shifted left by <code>shift</code>.</p> <blockquote> <p>NOTE: In the following example, cint16 is used for visual demonstration purposes. But it should be noted that it is definitely not safe for storing money amounts because its significant bits capacity is 8, while at least 50 bits are required for storing money amounts.</p> </blockquote> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Example:</span></span> <span class="giallo-l"><span>cint16{significant:11010111, shift:00000011}</span></span> <span class="giallo-l"><span>decompressed uint256: 11010111000 // shifted left by 3</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Example:</span></span> <span class="giallo-l"><span>cint64 { significant: 11111111...(56 ones), shift: 00101100 (44 in decimal) }</span></span> <span class="giallo-l"><span>decompressed uint256: 1111...(56 ones)0000...(44 zeros)</span></span></code></pre><h4 id="decompression-along-with-rounding-up">Decompression along with rounding up</h4> <p>The <code>significant</code> bits in the <code>cintx</code> are moved to a <code>uint256</code> space and shifted left by <code>shift</code> and the least significant <code>shift</code> bits are <code>1</code>s.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Example:</span></span> <span class="giallo-l"><span>cint16{significant:11011110, shift:00000011}</span></span> <span class="giallo-l"><span>decompressed rounded up value: 11011110111 // shifted left by 3 and 1s instead of 0s</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Example:</span></span> <span class="giallo-l"><span>cint64 { significant: 11111111...(56 ones), shift: 00101100 (44 in decimal) }</span></span> <span class="giallo-l"><span>decompressed uint256: 1111...(100 ones)</span></span></code></pre> <p>This specification is to be used by a new smart contract for managing its internal state so that any state mutating calls to it can be cheaper. These compressed values on a smart contract's state are something that should not be exposed to the external world (other smart contracts or clients). A smart contract should expose a decompressed value if needed.</p> <h2 id="rationale">Rationale</h2> <ul> <li>The <code>significant</code> bits are stored in the most significant part of <code>cintx</code> while <code>shift</code> bits in the least significant part, to help prevent obvious dev mistakes. For e.g. a number smaller than 2⁵⁶-1 its compressed <code>cint64</code> value would be itself if the arrangement were to be opposite than specified. If a developer forgets to uncompress a value before using it, this case would still pass if the compressed value is the same as decompressed value.</li> <li>It should be noted that using <code>cint64</code> doesn't render gas savings automatically. The solidity compiler needs to pack more data into the same storage slot.</li> <li>Also the packing and unpacking adds some small cost too.</li> <li>Though this design can also be seen as a binary floating point representation, however using floating point numbers on EVM is not in the scope of this ERC. The primary goal of floating point numbers is to be able to represent a wider range in an available number of bits, while the goal of compression in this ERC is to keep as much precision as possible. Hence, it specifies for the use of minimum exponent/shift bits (i.e 8 up to <code>uint120</code> and 7 up to <code>uint248</code>).</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> uses 3 slots</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> UserData1</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> amountCompressed</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> hash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> beneficiary</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> uses 2 slots</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> UserData2</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint64</span><span> amountCompressed</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> beneficiary</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> hash</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no known backward-incompatible issues.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>On the implementation level <code>uint64</code> may be used directly, or with custom types introduced in 0.8.9.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> compress</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> full</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint64</span><span class="z-variable"> cint</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> bits </span><span class="z-keyword">=</span><span class="z-entity z-name"> mostSignificantBitPosition</span><span>(</span><span>full</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>bits </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span class="z-constant"> 55</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> cint </span><span class="z-keyword">=</span><span class="z-support"> uint64</span><span>(</span><span>full</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 8</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span> bits </span><span class="z-keyword">-</span><span class="z-keyword">=</span><span class="z-constant"> 55</span><span>;</span></span> <span class="giallo-l"><span> cint </span><span class="z-keyword">=</span><span> (</span><span class="z-support">uint64</span><span>(</span><span>full </span><span class="z-keyword">&gt;&gt;</span><span> bits</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 8</span><span>)</span><span class="z-keyword"> +</span><span> bits</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> decompress</span><span>(</span><span class="z-support">uint64</span><span class="z-variable"> cint</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> full</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> bits </span><span class="z-keyword">=</span><span class="z-support"> uint8</span><span>(</span><span>cint % </span><span>(</span><span class="z-constant">1</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 9</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> full </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span>cint </span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 8</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span> bits</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> decompressRoundingUp</span><span>(</span><span class="z-support">uint64</span><span class="z-variable"> cint</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> full</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> bits </span><span class="z-keyword">=</span><span class="z-support"> uint8</span><span>(</span><span>cint % </span><span>(</span><span class="z-constant">1</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 9</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> full </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span>cint </span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 8</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span> bits </span><span class="z-keyword">+</span><span> (</span><span>(</span><span class="z-constant">1</span><span class="z-keyword"> &lt;&lt;</span><span> bits</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The above gist has <code>library CInt64</code> that contains demonstrative logic for compression, decompression, and arithmetic for <code>cint64</code>. The gist also has an example contract that uses the library for demonstration purposes.</p> <p>The CInt64 format is intended only for storage, while dev should convert it to uint256 form using suitable logic (decompress or decompressRoundingUp) to perform any arithmetic on it.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The following security considerations are discussed:</p> <ol> <li>Effects due to lossy compression <ul> <li>Error estimation for <code>cint64</code></li> <li>Handling the error</li> </ul> </li> <li>Losing precision due to incorrect use of <code>cintx</code></li> <li>Compressing something other than money <code>uint256</code>s.</li> </ol> <h3 id="1-effects-due-to-lossy-compression">1. Effects due to lossy compression</h3> <p>When a value is compressed, it causes underflow, i.e. some less significant bits are sacrificed. This results in a <code>cintx</code> value whose decompressed value is less than or equal to the actual <code>uint256</code> value.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint</span><span> a </span><span class="z-keyword">=</span><span class="z-constant"> 2</span><span class="z-keyword">*</span><span class="z-keyword">*</span><span class="z-constant">100</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 100 # of 1s in binary format</span></span> <span class="giallo-l"><span class="z-support">uint</span><span> c </span><span class="z-keyword">=</span><span> a</span><span>.</span><span class="z-entity z-name">compress</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">decompress</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>a </span><span class="z-keyword">&gt;</span><span> c</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> true</span></span> <span class="giallo-l"><span>a </span><span class="z-keyword">-</span><span> (</span><span class="z-constant">2</span><span class="z-keyword">*</span><span class="z-keyword">*</span><span>(</span><span class="z-constant">100</span><span class="z-keyword"> -</span><span class="z-constant"> 56</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> ==</span><span> c</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Visual example:</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> before: 1111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> after: 1111111111111111111111111111111111111111111111111111111100000000000000000000000000000000000000000000</span></span></code></pre><h4 id="error-estimation-for-cint64">Error estimation for cint64</h4> <p>Let's consider we have a <code>value</code> of the order 2^m (less than 2^m and greater than or equal to 2^m-1).</p> <p>For all values such that 2^m - 1 - (2^m-56 - 1) &lt;= <code>value</code> &lt;= 2^m - 1, the compressed value <code>cvalue</code> is 2^m - 1 - (2^m-56 - 1).</p> <p>The maximum error is 2^m-56 - 1, approximating it to decimal: 10^n-17 (log₂(56) is 17). Here <code>n</code> is number of decimal digits + 1.</p> <p>For e.g. compressing a value of the order $1,000,000,000,000 (or 1T or 10¹²) to <code>cint64</code>, the maximum error turns out to be 10^12+1-17 = $10^-4 = $0.0001. This means the precision after 4 decimal places is lost, or we can say that the uncompressed value is at maximum $0.0001 smaller. Similarly, if someone is storing $1,000,000 into <code>cint64</code>, the uncompressed value would be at maximum $0.0000000001 smaller. In comparison, the storage costs are almost $0.8 to initialize and $0.2 to update (20 gwei, 2000 ETHUSD).</p> <h4 id="handling-the-error">Handling the error</h4> <p>Note that compression makes the value slightly smaller (underflow). But we also have another operation that also does that. In integer math, the division is a lossy operation (causing underflow). For instance,</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-constant">10000001</span><span class="z-keyword"> /</span><span class="z-constant"> 2</span><span class="z-keyword"> ==</span><span class="z-constant"> 5000000</span><span class="z-comment"> //</span><span class="z-comment"> true</span></span></code></pre> <p>The result of the division operation is not always exact, but it's smaller than the actual value, in some cases as in the above example. Though, most engineers try to reduce this effect by doing all the divisions at the end.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>1001 / 2 * 301 == 150500 // true</span></span> <span class="giallo-l"><span>1001 * 301 / 2 == 150650 // true</span></span></code></pre> <p>The division operation has been in use in the wild, and plenty of lossy integer divisions have taken place, causing DeFi users to get very very slightly less withdrawal amounts, which they don't even notice. If been careful, then the risk is very negligible. Compression is similar, in the sense that it is also a division by 2^shift. If been careful with this too, the effects are minimized.</p> <p>In general, one should follow the rule:</p> <ol> <li>When a smart contract has to transfer a compressed amount to a user, they should use a rounded down value (by using <code>amount.decompress()</code>).</li> <li>When a smart contract has to transferFrom a compressed amount from a user to itself, i.e charging for some bill, they should use a rounded up value (by using <code>amount.decompressUp()</code>).</li> </ol> <p>The above ensures that smart contract does not loose money due to the compression, it is the user who receives less funds or pays more funds. The extent of rounding is something that is negligible enough for the user. Also just to mention, this rounding up and down pattern is observed in many projects including UniswapV3.</p> <h3 id="2-losing-precision-due-to-incorrect-use-of-cintx">2. Losing precision due to incorrect use of <code>cintx</code></h3> <p>This is an example where dev errors while using compression can be a problem.</p> <p>Usual user amounts mostly have an max entropy of 50, i.e. 10¹⁵ (or 2⁵⁰) values in use, that is the reason why we find uint56 enough for storing significant bits. However, let's see an example:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint64</span><span> sharesC </span><span class="z-keyword">=</span><span class="z-comment"> //</span><span class="z-comment"> reading compressed value from storage;</span></span> <span class="giallo-l"><span class="z-support">uint64</span><span> price </span><span class="z-keyword">=</span><span class="z-comment"> //</span><span class="z-comment"> CALL;</span></span> <span class="giallo-l"><span class="z-support">uint64</span><span> amountC </span><span class="z-keyword">=</span><span> sharesC</span><span>.</span><span class="z-entity z-name">cmuldiv</span><span>(</span><span>price</span><span>,</span><span> PRICE_UNIT</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>user</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>amountC</span><span>.</span><span class="z-entity z-name">uncompress</span><span>(</span><span>)</span><span>)</span><span>;</span></span></code></pre> <p>The above code results in a serious precision loss. <code>sharesC</code> has an entropy of 50, as well as <code>priceC</code> also has an entropy of 50. When we multiply them, we get a value that contains entropies of both, and hence, an entropy of 100. After multiplication is done, <code>cmul</code> compresses the value, which drops the entropy of <code>amountC</code> to 56 (as we have uint56 there to store significant bits).</p> <p>To prevent entropy/precision from dropping, we get out from compression.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint64</span><span> sharesC </span><span class="z-keyword">=</span><span> shares</span><span>.</span><span class="z-entity z-name">compress</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint64</span><span> priceC </span><span class="z-keyword">=</span><span> price</span><span>.</span><span class="z-entity z-name">compress</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> amount </span><span class="z-keyword">=</span><span> sharesC</span><span>.</span><span class="z-entity z-name">uncompress</span><span>(</span><span>)</span><span class="z-keyword"> *</span><span> price </span><span class="z-keyword">/</span><span> PRICE_UNIT</span><span>;</span></span> <span class="giallo-l"><span>user</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span>amount</span><span>)</span><span>;</span></span></code></pre> <p>Compression is only useful when writing to storage while doing arithmetic with them should be done very carefully.</p> <h3 id="3-compressing-something-other-than-money-uint256s">3. Compressing something other than money <code>uint256</code>s.</h3> <p>Compressed Integers is intended to only compress money amount. Technically there are about 10⁷⁷ values that a <code>uint256</code> can store but most of those values have a flat distribution i.e. the probability is 0 or extremely negligible. (What is a probability that a user would be depositing 1000T DAI or 1T ETH to a contract? In normal circumstances it doesn't happen, unless someone has full access to the mint function). Only the amounts that people work with have a non-zero distribution ($0.001 DAI to $1T or 10¹⁵ to 10³⁰ in uint256). 50 bits are enough to represent this information, just to round it we use 56 bits for precision.</p> <p>Using the same method for compressing something else which have a completely different probability distribution will likely result in a problem. It's best to just not compress if you're not sure about the distribution of values your <code>uint256</code> is going to take. And also, for things you think you are sure about using compression for, it's better to give more thought if compression can result in edge cases (e.g. in previous multiplication example).</p> <h3 id="4-compressing-stable-vs-volatile-money-amounts">4. Compressing Stable vs Volatile money amounts</h3> <p>Since we have a dynamic <code>uint8 shift</code> value that can move around. So even if you wanted to represent 1 Million SHIBA INU tokens or 0.0002 WBTC (both $10 as of this writing), cint64 will pick its top 56 significant bits which will take care of the value representation.</p> <p>It can be a problem for volatile tokens if the coin is extremely volatile wrt user's native currency. Imagine a very unlikely case where a coin goes 2⁵⁶x up (price went up by 10¹⁶ lol). In such cases <code>uint56</code> might not be enough as even its least significant bit is very valuable. If such insanely volatile tokens are to be stored, you should store more significant bits, i.e. using <code>cint96</code> or <code>cint128</code>.</p> <p><code>cint64</code> has 56 bits for storing significant, when only 50 were required. Hence there are 6 extra bits, which means that it is fine if the $ value of the cryptocurrency stored in cint64 increases by 2⁶ or 64x. If the value goes down it's not a problem.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-08-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Simon Tianhttps://github.com/simontianx https://wg-eips.ritovision.com/3754/

NFTs for representing abstract ownership

<h2 id="abstract">Abstract</h2> <p>In this standard, a non-fungible token stands as atomic existence and encourages layers of abstraction built on top of it. Ideal for representing concepts like rights, a form of abstract ownership. Such right can take the form of NFT options, oracle membership, virtual coupons, etc., and can then be made liquid because of this tokenization.</p> <h2 id="motivation">Motivation</h2> <p>Non-fungible tokens are popularized by the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> NFT standard for representing "ownership over digital or physical assets". Over the course of development, reputable NFT projects are about crypto-assets, digital collectibles, etc. The proposed standard aims to single out a special type of NFTs that are ideal for representing abstract ownership such as rights. Examples include the right of making a function call to a smart contract, an NFT option that gives the owner the right, but not obligation, to purchase an ERC-721 NFT, and the prepaid membership (time-dependent right) of accessing to data feeds provided by oracles without having to pay the required token fees. An on-chain subscription business model can then be made available by this standard. The conceptual clarity of an NFT is hence improved by this standard.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface IERC3754 {</span></span> <span class="giallo-l"><span> event Transfer(address indexed from, address indexed to, uint256 indexed tokenId);</span></span> <span class="giallo-l"><span> event Approval(address indexed owner, address indexed approved, uint256 indexed tokenId);</span></span> <span class="giallo-l"><span> event ApprovalForAll(address indexed owner, address indexed operator, bool approved);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function balanceOf(address owner) external view returns (uint256);</span></span> <span class="giallo-l"><span> function ownerOf(uint256 tokenId) external view returns (address);</span></span> <span class="giallo-l"><span> function approve(address to, uint256 tokenId) external;</span></span> <span class="giallo-l"><span> function getApproved(uint256 tokenId) external view returns (address);</span></span> <span class="giallo-l"><span> function setApprovalForAll(address operator, bool approved) external;</span></span> <span class="giallo-l"><span> function isApprovedForAll(address owner, address operator) external view returns (bool);</span></span> <span class="giallo-l"><span> function transferFrom(address from, address to, uint256 tokenId) external;</span></span> <span class="giallo-l"><span> function safeTransferFrom(address from, address to, uint256 tokenId) external;</span></span> <span class="giallo-l"><span> function safeTransferFrom(address from, address to, uint256 tokenId, bytes memory _data) external;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The NFTs defined in the <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> standard are already largely accepted and known as representing ownership of digital assets, and the NFTs by this standard aim to be accepted and known as representing abstract ownership. This is achieved by allowing and encouraging layers of abstract utilities built on top of them. Ownership of such NFTs is equivalent with having the rights to perform functions assigned to such tokens. Transfer of such rights is also made easier because of this tokenization. To further distinguish this standard from <a href="https://wg-eips.ritovision.com/721/">ERC-721</a>, data fields and functions related to <code>URI</code> are excluded.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There is no further backwards compatibility required.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>https://github.com/simontianx/ERC3754</p> <h2 id="security-considerations">Security Considerations</h2> <p>The security is enhanced from ERC721, given tokens are minted without having to provide <code>URI</code>s. Errors in dealing with <code>URI</code>s can be avoided.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-08-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 lightclienthttps://github.com/lightclient https://wg-eips.ritovision.com/3756/

Set an in-protocol cap for the gas limit

<h2 id="abstract">Abstract</h2> <p>Set an in-protocol cap for the gas limit of 30,000,000.</p> <h2 id="motivation">Motivation</h2> <p>A high gas limit increases pressure on the network. In the benign case, it increases the size of the state and history faster than we can sustain. In the malicious case, it amplifies the devastation of certain denial-of-service attacks.</p> <h2 id="specification">Specification</h2> <p>As of the fork block <code>N</code>, consider blocks with a <code>gas_limit</code> greater than <code>30,000,000</code> invalid.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-cap-the-gas-limit">Why Cap the Gas Limit</h3> <p>The gas limit is currently under the control of block proposers. They have the ability to increase the gas limit to whatever value they desire. This allows them to bypass the EIP and All Core Devs processes in protocol decisions that may negatively affect the security and/or decentralization of the network.</p> <h3 id="no-fixed-gas-limit">No Fixed Gas Limit</h3> <p>A valuable property of proposers choosing the gas limit is they can scale it down quickly if the network becomes unstable or is undergoing certain types of attacks. For this reason, we maintain their ability to lower the gas limit <em>below</em> 30,000,000.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backwards compatibility issues.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>No security considerations.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-08-07T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gregory Markouhttps://github.com/GregTheGreek https://wg-eips.ritovision.com/3709/ <h2 id="simple-summary">Simple Summary</h2> <p>Deprecates usage of <a href="https://wg-eips.ritovision.com/2718/">EIP-2718</a> <code>TransactionType</code> 1 in wallets and providers, upgrading all type 1 transactions to a type 2 transaction.</p> <h2 id="abstract">Abstract</h2> <p>Since both <code>TransactionType</code> 1 and 2 contain <code>access_list</code>, we propose the removal of offering <code>TransactionType</code> 1 from wallets and providers, instead the transaction will be converted to <code>TransactionType</code> 2 to make use of the new gas properties introduced by <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a>.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> was introduced as the first <code>TransactionType</code>, type 1, with the intention of adding <code>access_list</code> to the <code>TransactionPayload</code>. <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> introduced the second <code>TransactionType</code> 2, which is represented as <code>rlp([chain_id, nonce, max_priority_fee_per_gas, max_fee_per_gas, gas_limit, destination, amount, data, access_list, signature_y_parity, signature_r, signature_s])</code>. The intention behind EIP-1559 was to enhance the user experience surrounding gas fees, and as we move forward we expect that the majority of the network will begin to using <code>TransactionType</code> 2 instead of the legacy style transactions. <code>TransactionType</code> 1 is a legacy transaction with the addition of <code>access_list</code> meaning that users will not benefit from enhancements made by EIP-1559. <code>TransactionType</code> 2 contains <code>access_list</code>, thus there is no reason to further support <code>TransactionType</code> 1 if the end goal is to push users towards using <code>TransactionType</code> 2 anyway.</p> <h2 id="specification">Specification</h2> <p>For wallets and providers, if a user submits a transaction for signing with where <code>TransactionType == 0x1</code>, the developer should upgrade the transaction to meet the criteria of transaction of type 2.</p> <p>The following fields need to be changed, or amended:</p> <ul> <li><code>access_list</code>: Nothing changes and it should remain in the transaction.</li> <li><code>type</code>: Should change from <code>0x1</code> to <code>0x2</code>.</li> <li><code>gas_price</code>: Should be removed in favour of <code>max_fee_per_gas</code> &amp; <code>max_priority_fee_per_gas</code> (see <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> for proper usage).</li> </ul> <h2 id="rationale">Rationale</h2> <p>Improve the user experience for submitting transactions, and move away from legacy style transactions.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no known security considerations at this time.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-07-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Auryn Macmillanhttps://github.com/auryn-macmillan https://wg-eips.ritovision.com/3722/

A ridiculously simple general purpose social media smart contract.

<h1 id="poster">Poster</h1> <h2 id="abstract">Abstract</h2> <p>A ridiculously simple general purpose social media smart contract. It takes two strings (<code>content</code> and <code>tag</code>) as parameters and emits those strings, along with msg.sender, as an event. That's it. The EIP also includes a proposed standard json format for a Twitter-like application, where each <code>post()</code> call can include multiple posts and/or operations. The assumption being that application state will be constructed off-chain via some indexer.</p> <h2 id="motivation">Motivation</h2> <p>Poster is intended to be used as a base layer for decentralized social media. It can be deployed to the same address (via the singleton factory) on just about any EVM compatible network. Any Ethereum account can make posts to the deployment of Poster on its local network.</p> <h2 id="specification">Specification</h2> <h3 id="contract">Contract</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Poster</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NewPost</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>, </span><span class="z-support">string</span><span class="z-variable"> content</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tag</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> post</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> content</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> tag</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> NewPost</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> content</span><span>,</span><span> tag</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="abi">ABI</h3> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">anonymous</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">indexed</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">internalType</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">user</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">indexed</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">internalType</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">content</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">indexed</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">internalType</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tag</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">NewPost</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">event</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">internalType</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">content</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">internalType</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">tag</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">post</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">outputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">stateMutability</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nonpayable</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">function</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h3 id="standard-json-format-for-twitter-like-posts">Standard json format for Twitter-like posts</h3> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">content</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">microblog</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">text</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">this is the first post in a thread</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">microblog</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">text</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">this is the second post in a thread</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">replyTo</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">this[0]</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">microblog</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">text</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">this is a reply to some other post</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">replyTo</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">some_post_id</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">microblog</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">text</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">this is a post with an image</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">image</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ipfs://ipfs_hash</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">microblog</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">text</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">this post replaces a previously posted post</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">edit</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">some_post_id</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">delete</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">target</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">some_post_id</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">like</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">target</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">some_post_id</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">repost</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">target</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">some_post_id</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">follow</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">target</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">some_account</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">unfollow</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">target</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">some_account</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">block</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">target</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">some_account</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">report</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">target</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">some_account or some_post_id</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">permissions</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">account</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;account_to_set_permissions&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">permissions</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">post</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">delete</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">like</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">follow</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">block</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">report</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">permissions</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">microblog</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">text</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">This is a post from an account with permissions to post on behalf of another account.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">from</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&lt;from_address&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <p>There was some discussion around whether or not an post ID should also be emitted, whether the content should be a string or bytes, and whether or not anything at all should actually be emitted.</p> <p>We decided not to emit an ID, since it meant adding state or complexity to the contract and there is a fairly common pattern of assigning IDs on the indexer layer based on transactionHash + logIndex.</p> <p>We decided to emit a string, rather than bytes, simply because that would make content human readable on many existing interfaces, like Etherscan for example. This did, unfortunately, eliminate some of the benefit that we might have gotten from a more compact encoding scheme like CBOR, rather than JSON. But this also would not have satisfied the human readable criteria.</p> <p>While there would have been some gas savings if we decided against emitting anything at all, it would have redically increased the node requirements to index posts. As such, we decided it was worth the extra gas to actually emit the content.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>Poster has been deployed at <code>0x000000000000cd17345801aa8147b8D3950260FF</code> on multiple networks using the <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2470">Singleton Factory</a>. If it is not yet deployed on your chosen network, you can use the Singleton Factory to deploy an instance of Poster at the same address on just about any EVM compatible network using these parameters:</p> <blockquote> <p><strong>initCode:</strong> <code>0x608060405234801561001057600080fd5b506101f6806100206000396000f3fe608060405234801561001057600080fd5b506004361061002b5760003560e01c80630ae1b13d14610030575b600080fd5b61004361003e3660046100fa565b610045565b005b8181604051610055929190610163565b60405180910390203373ffffffffffffffffffffffffffffffffffffffff167f6c7f3182d7e4cb876251f9ae1489975fdbbf15d9f35d393f2ac9b1ff57cec69f86866040516100a5929190610173565b60405180910390a350505050565b60008083601f8401126100c4578182fd5b50813567ffffffffffffffff8111156100db578182fd5b6020830191508360208285010111156100f357600080fd5b9250929050565b6000806000806040858703121561010f578384fd5b843567ffffffffffffffff80821115610126578586fd5b610132888389016100b3565b9096509450602087013591508082111561014a578384fd5b50610157878288016100b3565b95989497509550505050565b6000828483379101908152919050565b60006020825282602083015282846040840137818301604090810191909152601f9092017fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffe016010191905056fea2646970667358221220ee0377bd266748c5dbaf0a3f15ebd97be153932f2d14d460d9dd4271fee541b564736f6c63430008000033</code></p> <p><strong>salt:</strong> <code>0x9245db59943806d06245bc7847b3efb2c899d11b621a0f01bb02fd730e33aed2</code></p> </blockquote> <p>When verifying on the source code on a block explorer, make sure to set the optimizer to <code>yes</code> and the runs to <code>10000000</code>.</p> <p>The source code is available in the <a rel="external" href="https://github.com/ETHPoster/contract/blob/master/contracts/Poster.sol">Poster contract repo</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Given the ridiculously simple implementation of Poster, there does not appear to be any real security concerns at the contract level.</p> <p>At the application level, clients should confirm that posts including a <code>"from"</code> field that differs from <code>msg.sender</code> have been authorized by the <code>"from"</code> address via a <code>"permissions"</code> post, otherwise they should be considerred invalid or a post from <code>msg.sender</code>.</p> <p>Clients should also be sure to sanitize post data.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-07-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Andrei Maiborodahttps://github.com/gumb0 Paweł Bylicahttps://github.com/chfast https://wg-eips.ritovision.com/4200/

RJUMP, RJUMPI and RJUMPV instructions with a signed immediate encoding the jump destination

<h2 id="abstract">Abstract</h2> <p>Three new EVM jump instructions are introduced (<code>RJUMP</code>, <code>RJUMPI</code> and <code>RJUMPV</code>) which encode destinations as signed immediate values. These can be useful in the majority of (but not all) use cases and offer a cost reduction.</p> <h2 id="motivation">Motivation</h2> <p>A recurring discussion topic is that EVM only has a mechanism for dynamic jumps. They provide a very flexible architecture with only 2 (!) instructions. This flexibility comes at a cost however: it makes analysis of code more complicated and it also (partially) resulted in the need to have the <code>JUMPDEST</code> marker.</p> <p>In a great many cases control flow is actually static and there is no need for any dynamic behaviour, though not every use case can be solved by static jumps.</p> <p>There are various ways to reduce the need for dynamic jumps, some examples:</p> <ol> <li>With native support for functions / subroutines</li> <li>A "return to caller" instruction</li> <li>A "switch-case" table with dynamic indexing</li> </ol> <p>This change does not attempt to solve these, but instead introduces a minimal feature set to allow compilers to decide which is the most adequate option for a given use case. It is expected that compilers will use <code>RJUMP</code>/<code>RJUMPI</code> almost exclusively, with the exception of returning to the caller continuing to use <code>JUMP</code>.</p> <p>This functionality does not preclude the EVM from introducing other forms of control flow later on. <code>RJUMP</code>/<code>RJUMPI</code> can efficiently co-exists with a higher-level declaration of functions, where static relative jumps should be used for intra-function control flow.</p> <p>The main benefit of these instruction is reduced gas cost (both at deploy and execution time) and better analysis properties.</p> <h2 id="specification">Specification</h2> <p>We introduce three new instructions on the same block number <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> is activated on:</p> <ol> <li><code>RJUMP</code> (0xe0) - relative jump</li> <li><code>RJUMPI</code> (0xe1) - conditional relative jump</li> <li><code>RJUMPV</code> (0xe2) - relative jump via jump table</li> </ol> <p>If the code is legacy bytecode, all of these instructions result in an <em>exceptional halt</em>. (<em>Note: This means no change to behaviour.</em>)</p> <p>If the code is valid EOF1:</p> <ol> <li><code>RJUMP relative_offset</code> sets the <code>PC</code> to <code>PC_post_instruction + relative_offset</code>.</li> <li><code>RJUMPI relative_offset</code> pops a value (<code>condition</code>) from the stack, and sets the <code>PC</code> to <code>PC_post_instruction + ((condition == 0) ? 0 : relative_offset)</code>.</li> <li><code>RJUMPV max_index relative_offset+</code> pops a value (<code>case</code>) from the stack, and sets the <code>PC</code> to <code>PC_post_instruction + ((case &gt; max_index) ? 0 : relative_offset[case])</code>.</li> </ol> <p>The immediate argument <code>relative_offset</code> is encoded as a 16-bit <strong>signed</strong> (two's-complement) big-endian value. Under <code>PC_post_instruction</code> we mean the <code>PC</code> position after the entire immediate value.</p> <p>The immediate encoding of <code>RJUMPV</code> is more special: the unsigned 8-bit <code>max_index</code> value determines the maximum index in the jump table. The number of <code>relative_offset</code> values following is <code>max_index+1</code>. This allows table sizes up to 256. The encoding of <code>RJUMPV</code> must have at least one <code>relative_offset</code> and thus it will take at minimum 4 bytes. Furthermore, the <code>case &gt; max_index</code> condition falling through means that in many use cases, one would place the <em>default</em> path following the <code>RJUMPV</code> instruction. An interesting feature is that <code>RJUMPV 0 relative_offset</code> is an inverted-<code>RJUMPI</code>, which can be used in many cases instead of <code>ISZERO RJUMPI relative_offset</code>.</p> <p>We also extend the validation algorithm of <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a> to verify that each <code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> has a <code>relative_offset</code> pointing to an instruction. This means it cannot point to an immediate data of <code>PUSHn</code>/<code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code>. It cannot point outside of code bounds. It is allowed to point to a <code>JUMPDEST</code>, but is not required to.</p> <p>Because the destinations are validated upfront, the cost of these instructions are less than their dynamic counterparts: <code>RJUMP</code> should cost 2, and <code>RJUMPI</code> and <code>RJUMPV</code> should cost 4.</p> <h2 id="rationale">Rationale</h2> <h3 id="relative-addressing">Relative addressing</h3> <p>We chose relative addressing in order to support code which is relocatable. This also means a code snippet can be injected. A technique seen used prior to this EIP to achieve the same goal was to inject code like <code>PUSHn PC ADD JUMPI</code>.</p> <p>We do not see any significant downside to relative addressing and it allows us to also deprecate the <code>PC</code> instruction.</p> <h3 id="immediate-size">Immediate size</h3> <p>The signed 16-bit immediate means that the largest jump distance possible is 32767. In the case the bytecode at <code>PC=0</code> starts with an <code>RJUMP</code>, it will be possible to jump as far as <code>PC=32770</code>.</p> <p>Given <code>MAX_CODE_SIZE = 24576</code> (in <a href="https://wg-eips.ritovision.com/170/">EIP-170</a>) and <code>MAX_INITCODE_SIZE = 49152</code> (in <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a>), we think the 16-bit immediate is large enough.</p> <p>A version with an 8-bit immediate would only allow moving <code>PC</code> backward by 125 or forward by 127 bytes. While that seems to be a good enough distance for many for-loops, it is likely not good enough for cross-function jumps, and since the 16-bit immediate is the same size as what a dynamic jump would take in such cases (3 bytes: <code>JUMP PUSH1 n</code>), we think having less instructions is better.</p> <p>Should there be a need to have immediate encodings of other size (such as 8-bits, 24-bits or 32-bits), it would be possible to introduce new opcodes, similarly to how multiple <code>PUSH</code> instructions exist.</p> <h3 id="pushn-jump-sequences"><code>PUSHn JUMP</code> sequences</h3> <p>If we chose absolute addressing, then <code>RJUMP</code> could be viewed similar to the sequence <code>PUSHn JUMP</code> (and <code>RJUMPI</code> similar to <code>PUSHn JUMPI</code>). In that case one could argue that instead of introducing a new instruction, such sequences should get a discount, because EVMs could optimise them.</p> <p>We think this is a bad direction to go:</p> <ol> <li>It further complicates the already complex rules of gas calculation.</li> <li>And it either requires a consensus defined internal representation for EVM code, or forces EVM implementations to do optimisations on their own.</li> </ol> <p>Both of these are risky. Furthermore we think that EVM implementations should be free to chose what optimisations they apply, and the savings do not need to be passed down at all cost.</p> <p>Additionally it requires a potentially significant change to the current implementations which depend on a streaming one-by-one execution without a lookahead.</p> <h3 id="relation-to-dynamic-jumps">Relation to dynamic jumps</h3> <p>The goal was not to completely replace the current control flow system of the EVM, but to augment it. There are many cases where dynamic jumps are useful, such as returning to the caller.</p> <p>It is possible to introduce a new mechanism for having a pre-defined table of valid jump destinations, and dynamically supplying the index within this table to accomplish some form of dynamic jumps. This is very useful for efficiently encoding a form of "switch-cases" statements. It could also be used for "return to caller" cases, however it is likely inefficient or awkward.</p> <h3 id="lack-of-jumpdest">Lack of <code>JUMPDEST</code></h3> <p><code>JUMPDEST</code> serves two purposes:</p> <ol> <li>To efficiently partition code -- this can be useful for pre-calculating total gas usage for a given <em>block</em> (i.e. instructions between <code>JUMPDEST</code>s), and for JIT/AOT translation.</li> <li>To explicitly show valid locations (otherwise any non-data location would be valid).</li> </ol> <p>This functionality is not needed for static jumps, as the analysers can easily tell destinations from the static jump immediates during jumpdest-analysis.</p> <p>There are two benefits here:</p> <ol> <li>Not wasting a byte for a <code>JUMPDEST</code> also means a saving of 200 gas during deployment, for each jump destination.</li> <li>Saving an extra 1 gas per jump during execution, given <code>JUMPDEST</code> itself cost 1 gas and is "executed" during jumping.</li> </ol> <h3 id="rjumpv-fallback-case"><code>RJUMPV</code> fallback case</h3> <p>If no match is found (i.e. the <em>default</em> case) in the <code>RJUMPV</code> instruction execution will continue without branching. This allows for gaps in the arguments to be filled with <code>0</code>s, and a choice of implementation by the programmer. Alternate options would include exceptional aborts in case of no match.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change poses no risk to backwards compatibility, as it is introduced at the same time EIP-3540 is. The new instructions are not introduced for legacy bytecode (code which is not EOF formatted).</p> <h2 id="test-cases">Test Cases</h2> <h3 id="validation">Validation</h3> <h4 id="valid-cases">Valid cases</h4> <ul> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> with <code>JUMPDEST</code> as target <ul> <li><code>relative_offset</code> is positive/negative/<code>0</code></li> </ul> </li> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> with instruction other than <code>JUMPDEST</code> as target <ul> <li><code>relative_offset</code> is positive/negative/<code>0</code></li> </ul> </li> <li><code>RJUMPV</code> with various valid table sizes from 1 to 256</li> <li><code>RJUMP</code> as a final instruction in code section</li> </ul> <h4 id="invalid-cases">Invalid cases</h4> <ul> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> with truncated immediate</li> <li><code>RJUMPI</code>/<code>RJUMPV</code> as a final instruction in code section</li> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> target outside of code section bounds</li> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> target push data</li> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> target another <code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> immediate argument</li> </ul> <h3 id="execution">Execution</h3> <ul> <li><code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code> in legacy code aborts execution</li> <li><code>RJUMP</code> <ul> <li><code>relative_offset</code> is positive/negative/<code>0</code></li> </ul> </li> <li><code>RJUMPI</code> <ul> <li><code>relative_offset</code> is positive/negative/<code>0</code> <ul> <li><code>condition</code> equals <code>0</code></li> <li><code>condition</code> does not equal <code>0</code></li> </ul> </li> </ul> </li> <li><code>RJUMPV 0 relative_offset</code> <ul> <li><code>case</code> equals <code>0</code></li> <li><code>case</code> does not equal <code>0</code></li> </ul> </li> <li><code>RJUMPV</code> with table containing positive, negative, <code>0</code> offsets <ul> <li><code>case</code> equals <code>0</code></li> <li><code>case</code> does not equal <code>0</code></li> <li><code>case</code> outside of table bounds (<code>case &gt; max_index</code>, fallback case)</li> <li><code>case</code> &gt; 255</li> </ul> </li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Adding new instructions with immediate arguments should be carefully considered when implementing the EOF container validation algorithm.</p> <p>Static relative jump execution does not require runtime check of the jump destination. It greatly reduces execution cost. Therefore the gas cost of the new instructions can also be significantly reduced.</p> <p>The <code>RJUMPV</code> instruction relative offset table can have up to 256 one-byte entries, so reading an offset cannot be a potential attack surface.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-06-23T00:00:00+00:00 2026-02-11T14:49:28+00:00 Alex Beregszaszihttps://github.com/axic Andrei Maiborodahttps://github.com/gumb0 Paweł Bylicahttps://github.com/chfast https://wg-eips.ritovision.com/3670/

Validate EOF bytecode for correctness at the time of deployment.

<h2 id="abstract">Abstract</h2> <p>Introduce code validation at contract creation time for EOF formatted (<a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>) contracts. Reject contracts which contain truncated <code>PUSH</code>-data or undefined instructions. Legacy bytecode (code which is not EOF formatted) is unaffected by this change.</p> <h2 id="motivation">Motivation</h2> <p>Currently existing contracts require no validation of correctness and EVM implementations can decide how they handle truncated bytecode or undefined instructions. This change aims to bring code validity into consensus, so that it becomes easier to reason about bytecode. Moreover, EVM implementations may require fewer paths to decide which instruction is valid in the current execution context.</p> <p>If there's a desire to introduce new instructions without bumping the EOF version, having undefined instructions already deployed could potentially break such contracts, as some instructions might change their behavior. Rejecting to deploy undefined instructions allows introducing new instructions with or without bumping the EOF version.</p> <h3 id="eof1-forward-compatibility">EOF1 forward compatibility</h3> <p>The EOF1 format provides following forward compatibility properties:</p> <ol> <li>New instructions can be defined for previously unassigned opcodes. These instructions may have immediate values.</li> <li>Mandatory EOF sections may be made optional.</li> <li>New optional EOF sections may be introduced. They can be placed in any order in relation to previously defined sections.</li> </ol> <h2 id="specification">Specification</h2> <p>This feature is introduced on the same block EIP-3540 is enabled, therefore every EOF1-compatible bytecode MUST be validated according to these rules.</p> <ol> <li>Previously deprecated instructions <code>CALLCODE</code> (0xf2) and <code>SELFDESTRUCT</code> (0xff), as well as instructions deprecated in EIP-3540, are invalid and their opcodes are undefined. (<strong>NOTE</strong> there are more instructions deprecated and rejected in EOF, as specced out by separate EIPs)</li> <li>At contract creation time <em>code validation</em> is performed on each code section of the EOF container. The code is invalid if any of the checks below fails. For each instruction: <ol> <li>Check if the opcode is defined. The <code>INVALID</code> (0xfe) is considered defined.</li> <li>Check if all instructions' immediate bytes are present in the code (code does not end in the middle of instruction).</li> </ol> </li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="immediate-data">Immediate data</h3> <p>Allowing implicit zero immediate data for <code>PUSH</code> instructions introduces inefficiencies to EVM implementations without any practical use-case (the value of a <code>PUSH</code> instruction at the code end cannot be observed by EVM). This EIP requires all immediate bytes to be explicitly present in the code.</p> <h3 id="rejection-of-deprecated-instructions">Rejection of deprecated instructions</h3> <p>The deprecated instructions <code>CALLCODE</code> (0xf2) and <code>SELFDESTRUCT</code> (0xff) are removed from the <code>valid_opcodes</code> list to prevent their use in the future.</p> <h3 id="blockhash-instruction">BLOCKHASH instruction</h3> <p>The <code>BLOCKHASH</code> instruction is well replaced by the system contract introduced in <a href="https://wg-eips.ritovision.com/2935/">EIP-2935</a>. However, despite a replacement being introduced this opcode has not been deprecated. This opcode will remain valid in EOF not to differentiate from legacy bytecode.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change poses no risk to backwards compatibility, as it is introduced at the same time EIP-3540 is. The validation does not cover legacy bytecode (code which is not EOF formatted).</p> <h2 id="test-cases">Test Cases</h2> <h3 id="contract-creation">Contract creation</h3> <p>Each case should be tested by submitting an EOF container to EOF contract creation (as specced out in a separate EIP). Each case should be tested with code placed in code sections at different indices.</p> <h3 id="valid-codes">Valid codes</h3> <ul> <li>EOF code containing <code>INVALID</code></li> <li>EOF code with data section containing bytes that are undefined instructions</li> </ul> <h3 id="invalid-codes">Invalid codes</h3> <ul> <li>EOF code containing an undefined instruction</li> <li>EOF code ending with incomplete <code>PUSH</code> instruction</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> The ranges below are as specified by Execution Specs for Shanghai.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Note: range(s, e) excludes e, hence the +1</span></span> <span class="giallo-l"><span>shanghai_opcodes</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">00</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">0b</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">10</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">1d</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">20</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">30</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">3f</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">40</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">48</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">50</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">5b</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">5f</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">60</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">6f</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">70</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">7f</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">80</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">8f</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">90</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">9f</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-keyword"> *</span><span class="z-support">range</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">a0</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">a4</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Note: 0xfe is considered assigned.</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">f0</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">f1</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">f2</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">f3</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">f4</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">f5</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">fa</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">fd</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">fe</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">ff</span></span> <span class="giallo-l"><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Drop the opcodes deprecated and rejected in here and in EIP-3540</span></span> <span class="giallo-l"><span>rejected_in_eof</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span class="z-storage z-type"> 0x</span><span class="z-constant">38</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">39</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">3b</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">3c</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">3f</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">5a</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">f1</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">f2</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">f4</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">fa</span><span>,</span><span class="z-storage z-type"> 0x</span><span class="z-constant">ff</span></span> <span class="giallo-l"><span>]</span></span> <span class="giallo-l"><span>valid_opcodes</span><span class="z-keyword"> =</span><span> [</span><span>op</span><span class="z-keyword"> for</span><span> op</span><span class="z-keyword"> in</span><span> shanghai_opcodes</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> rejected_in_eof</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>immediate_sizes</span><span class="z-keyword"> =</span><span class="z-constant"> 256</span><span class="z-keyword"> *</span><span> [</span><span class="z-constant">0</span><span>]</span></span> <span class="giallo-l"><span>immediate_sizes</span><span>[</span><span class="z-storage z-type">0x</span><span class="z-constant">60</span><span>:</span><span class="z-storage z-type">0x</span><span class="z-constant">7f</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>]</span><span class="z-keyword"> =</span><span class="z-support"> range</span><span>(</span><span class="z-constant">1</span><span>,</span><span class="z-constant"> 32</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> PUSH1..PUSH32</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Raises ValidationException on invalid code</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> validate_instructions</span><span>(</span><span class="z-variable z-parameter z-function">code</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Note that EOF1 already asserts this with the code section requirements</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> pos</span><span class="z-keyword"> &lt;</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Ensure the opcode is valid</span></span> <span class="giallo-l"><span> opcode</span><span class="z-keyword"> =</span><span> code</span><span>[</span><span>pos</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> opcode</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> valid_opcodes</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> ValidationException</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">undefined opcode</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Skip immediate data</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span><span class="z-keyword"> +</span><span> immediate_sizes</span><span>[</span><span>opcode</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Ensure last instruction&#39;s immediate doesn&#39;t go over code end</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> pos</span><span class="z-keyword"> !=</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> raise</span><span> ValidationException</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">truncated immediate</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>See <a href="https://wg-eips.ritovision.com/3540/#security-considerations">Security Considerations of EIP-3540</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-06-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast Andrei Maiborodahttps://github.com/gumb0 https://wg-eips.ritovision.com/3690/

A special EOF section for storing the list of JUMPDESTs, which simplifies execution time analysis.

<h2 id="abstract">Abstract</h2> <p>Introduce a section in the EOF format (<a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>) for storing the list of <code>JUMPDEST</code>s, validate the correctness of this list at the time of contract creation, and remove the need for <code>JUMPDEST</code>-analysis at execution time. In EOF contracts, the <code>JUMPDEST</code> instruction is not needed anymore and becomes invalid. Legacy contracts are entirely unaffected by this change.</p> <h2 id="motivation">Motivation</h2> <p>Currently existing contracts require no validation of correctness, but every time they are executed, a list must be built containing all the valid jump-destinations. This is an overhead which can be avoided, albeit the effect of the overhead depends on the client implementation.</p> <p>With the structure provided by EIP-3540 it is easy to store and transmit a table of valid jump-destinations instead of using designated <code>JUMPDEST</code> (0x5b) opcodes in the code.</p> <p>The goal of this change is that we trade less complexity (and processing time) at execution time for more complexity at contract creation time. Through benchmarks we have identified that the mandatory execution preparation time is the same as before for extreme cases (i.e. deliberate edge cases), while it is ~10x faster for the average case.</p> <p>Finally, this change puts an implicit bound on "initcode analysis" which is now limited to jumpdests section loading of max size of 0xffff. The legacy code remains vulnerable.</p> <h2 id="specification">Specification</h2> <p>This feature is introduced on the very same block <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a> is enabled, therefore every EOF1-compatible bytecode MUST have a JUMPDEST-table if it uses jumps.</p> <p><em>Remark:</em> We rely on the notation of <em>initcode</em>, <em>code</em> and <em>creation</em> as defined by <a href="https://wg-eips.ritovision.com/3540/">EIP-3540</a>, and extend validation rules of <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a>.</p> <h3 id="eof-container-changes">EOF container changes</h3> <ol> <li> <p>A new EOF section called <code>jumpdests</code> (<code>section_kind = 3</code>) is introduced. It contains a sequence of <em>n</em> unsigned integers <em>jumploc_i</em>.</p> </li> <li> <p>The <em>jumploc_i</em> values are encoded with <a rel="external" href="https://en.wikipedia.org/wiki/LEB128#Unsigned_LEB128">unsigned LEB128</a>.</p> <table><thead><tr><th>description</th><th>encoding</th></tr></thead><tbody> <tr><td>jumploc₀</td><td>unsigned LEB128</td></tr> <tr><td>jumploc₁</td><td>unsigned LEB128</td></tr> <tr><td>...</td><td></td></tr> <tr><td>jumploc_n</td><td>unsigned LEB128</td></tr> </tbody></table> </li> <li> <p>The jump destinations represent the set of valid code positions as arguments to jump instructions. They are delta-encoded therefore partial sum must be performed to retrieve the absolute offsets.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> jumpdest</span><span>(</span><span class="z-variable z-parameter z-function">n</span><span>:</span><span class="z-support"> int</span><span>,</span><span class="z-variable z-parameter z-function"> jumpdests_table</span><span>:</span><span> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> sum</span><span>(</span><span>jumpdests_table</span><span>[</span><span>:</span><span>n</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>]</span><span>)</span></span></code></pre></li> </ol> <h3 id="validation-rules">Validation rules</h3> <blockquote> <p>This section extends contract creation validation rules (as defined in EIP-3540).</p> </blockquote> <ol start="4"> <li>The <code>jumpdests</code> section MUST be present if and only if the <code>code</code> section contains <code>JUMP</code> or <code>JUMPI</code> opcodes.</li> <li>If the <code>jumpdests</code> section is present it MUST directly precede the <code>code</code> section. In this case a valid EOF bytecode will have the form of <code>format, magic, version, [jumpdests_section_header], code_section_header, [data_section_header], 0, [jumpdests_section_contents], code_section_contents, [data_section_contents]</code>.</li> <li>The LEB128 encoding of a <code>jumploc</code> must be valid: the encoding must be complete and not read out of <code>jumpdests</code> section. As an additional constraint, the shortest possible encoding must be used.</li> <li>With an exception of the first entry, the value of <code>jumploc</code> MUST NOT be 0.</li> <li>Every <code>jumploc</code> MUST point to a valid opcode. They MUST NOT point into PUSH-data or outside of the code section.</li> <li>The <code>JUMPDEST</code> (0x5b) instruction becomes undefined (Note: According to rules of EIP-3670, deploying the code will fail if it contains <code>JUMPDEST</code>)</li> </ol> <h3 id="execution">Execution</h3> <ol start="10"> <li>When executing <code>JUMP</code> or <code>JUMPI</code> instructions, the jump destination MUST be in the <code>jumpdests</code> table. Otherwise, the execution aborts with <em>bad jump destination</em>. In case of <code>JUMPI</code>, the check is done only when the jump is to be taken (no change to the previous behaviour).</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="jumpdests-section-is-bounded">Jumpdests section is bounded</h3> <p>The length of the <code>jumpdests</code> section is bounded by the EOF maximum section size value 0xffff. Moreover, for deployed code this is additionally limited by the max bytecode size 0x6000. Then any valid <code>jumpdests</code> section may not be larger than 0x3000.</p> <h3 id="delta-encoding">Delta encoding</h3> <p>Delta-encoding is very efficient for this job. From a quick analysis of a small set of contracts <code>JUMPDEST</code> opcodes are relatively close to each other. In the delta-encoding the values almost never exceed 128. Combined with any form of variable-length quantity (VLQ) where values &lt; 128 occupy one byte, encoding of single jumpdest takes ~1 byte. We also remove <code>JUMPDEST</code> opcodes from the code section therefore the total bytecode length remains the same if extreme examples are ignored.</p> <p>By extreme examples we mean contracts having a distance between two subsequent JUMPDESTs larger than 128. Then the LEB128 encoding of such distance requires more than one byte and the total bytecode size will increase by the additional number of bytes used.</p> <h3 id="leb128-for-offsets">LEB128 for offsets</h3> <p>The LEB128 encoding is the most popular VLQ used in DWARF and WebAssembly.</p> <p>LEB128 allows encoding a fixed value with arbitrary number of bytes by having zero payloads for most significant bits of the value. To ensure there exists only single encoding of a given value, we additionally require the shortest possible LEB128 encoding to be used. This constraint is also required by WebAssembly.</p> <h3 id="size-prefix-for-offsets">Size-prefix for offsets</h3> <p>This is another option for encoding inspired by UTF-8. The benefit is that the number of following bytes is encoded in the first byte (the top two bits), so the expected length is known upfront.</p> <p>A simple decoder is the following:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> decode</span><span>(</span><span class="z-variable z-parameter z-function">input</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span> -&gt;</span><span class="z-support"> int</span><span>:</span></span> <span class="giallo-l"><span> size_prefix</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> &gt;&gt;</span><span class="z-constant"> 6</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> size_prefix</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> input</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> &amp;</span><span class="z-storage z-type"> 0x</span><span class="z-constant">3f</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> size_prefix</span><span class="z-keyword"> ==</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-support">input</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> &amp;</span><span class="z-storage z-type"> 0x</span><span class="z-constant">3f</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 8</span><span class="z-keyword"> |</span><span class="z-support"> input</span><span>[</span><span class="z-constant">1</span><span>]</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> size_prefix</span><span class="z-keyword"> ==</span><span class="z-constant"> 2</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-support">input</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> &amp;</span><span class="z-storage z-type"> 0x</span><span class="z-constant">3f</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 16</span><span class="z-keyword"> |</span><span> (</span><span class="z-support">input</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 8</span><span>)</span><span class="z-keyword"> |</span><span class="z-support"> input</span><span>[</span><span class="z-constant">2</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Do not support case 3</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span class="z-constant">False</span><span>)</span></span></code></pre><h3 id="empty-table">Empty table</h3> <p>In case code does not use jumps, an empty JUMPDEST table is represented by omitting <code>jumpdests</code> section as opposed to a section that is always present, but allowed to be empty. This is consistent with the requirement of EIP-3540 for section size to be non-zero. Additionally, omitting the section saves 3 bytes of code storage.</p> <h3 id="why-jumpdests-before-code">Why jumpdests before code?</h3> <p>The contents of <code>jumpdests</code> section are always needed to start EVM execution. For chunked and/or merkleized bytecode it is more efficient to have <code>jumpdests</code> just after the EOF header so they can share the same first chunk(s).</p> <h3 id="code-chunking-merkleization">Code chunking / merkleization</h3> <p>In code chunking the contract code is split into (fixed size) chunks. Due to the requirement of jumpdest-analysis, it must be known where the first instruction starts in a given chunk, in case the split happened within a PUSH-data. This is commonly accomplished with reserving the first byte of the chunk as the "first instruction offset" (FIO) field.</p> <p>With this EIP, code chunking does not need to have such a field. However, the jumpdest table must be provided instead (for all the chunks up until the last jump location used during execution).</p> <h3 id="benchmarks-performance-analysis">Benchmarks / performance analysis</h3> <p>We compared the performance of <code>jumpdests</code> section loading to JUMPDEST analysis in evmone/Baseline interpreter. In both cases a bitset of valid jumpdest positions is built.</p> <p>We used the worst case for <code>jumpdests</code> section as the benchmark baseline. This is the case where every position in the code section is valid jumpdest. I.e. the bytecode has as many jumpdests as possible making the jumpdests section as large as possible. The encoded representation is <code>0x00, 0x01, 0x01, 0x01, ...</code>.</p> <p>This also happen to be the worst case for the JUMPDEST analysis.</p> <p>Further, we picked 5 popular contracts from the Ethereum mainnet.</p> <table><thead><tr><th>case</th><th>size</th><th>num JUMPDESTs</th><th>JUMPDEST analysis (cycles/byte)</th><th>jumpdests load (cycles/byte)</th><th>performance change</th></tr></thead><tbody> <tr><td>worst</td><td>65535</td><td>65535</td><td>9.11</td><td>9.36</td><td>2.75%</td></tr> <tr><td>RoninBridge</td><td>1760</td><td>71</td><td>3.57</td><td></td><td>-89.41%</td></tr> <tr><td>UniswapV2ERC20</td><td>2319</td><td>61</td><td>2.10</td><td></td><td>-88.28%</td></tr> <tr><td>DepositContract</td><td>6358</td><td>123</td><td>1.86</td><td></td><td>-90.24%</td></tr> <tr><td>TetherToken</td><td>11075</td><td>236</td><td>1.91</td><td></td><td>-89.58%</td></tr> <tr><td>UniswapV2Router02</td><td>21943</td><td>468</td><td>2.26</td><td></td><td>-91.17%</td></tr> </tbody></table> <p>For the worst case the performance difference between JUMPDEST analysis and jumpdests section loading is very small. The performance very slow compared to memory copy (0.15 cycles/byte).</p> <p>However, the maximum length for the worst cases is different. For JUMPDEST analysis this is 24576 (0x6000) for deployed contracts and only limited by EVM memory cost in case of <em>initcode</em> (can be over 1MB). For jumpdests sections, the limit is 12288 for deployed contracts (the deployed bytecode length limit must be split equally between jumpdests and code sections). For <em>initcode</em> case, the limit is 65535 because this is the maximum section size allowed by EOF.</p> <p>For "popular" contracts the gained efficiency is ~10x because the jumpdests section is relatively small compared to the code section and therefore there is much less bytes to loop over than in JUMPDEST analysis.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>We extend the <code>validate_code()</code> function of <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a>:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> The same table as in EIP-3670</span></span> <span class="giallo-l"><span>valid_opcodes</span><span class="z-keyword"> =</span><span class="z-constant"> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Remove JUMPDEST from the list of valid opcodes</span></span> <span class="giallo-l"><span>valid_opcodes</span><span>.</span><span>remove</span><span>(</span><span class="z-storage z-type">0x</span><span class="z-constant">5b</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This helper decodes a single unsigned LEB128 encoded value</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This will abort on truncated (short) input</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> leb128u_decode</span><span>(</span><span class="z-variable z-parameter z-function">input</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span> -&gt;</span><span> (</span><span class="z-support">int</span><span>,</span><span class="z-support"> int</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> ret</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> shift</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> consumed_bytes</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span class="z-constant"> True</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Check for truncated input</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>consumed_bytes</span><span class="z-keyword"> &lt;</span><span class="z-support"> len</span><span>(</span><span class="z-support">input</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Only allow up to 4-byte long leb128 encodings</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>consumed_bytes</span><span class="z-keyword"> &lt;=</span><span class="z-constant"> 3</span><span>)</span></span> <span class="giallo-l"><span> input_byte</span><span class="z-keyword"> =</span><span class="z-support"> input</span><span>[</span><span>consumed_bytes</span><span>]</span></span> <span class="giallo-l"><span> consumed_bytes</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span> ret</span><span class="z-keyword"> |=</span><span> (</span><span>input_byte</span><span class="z-keyword"> &amp;</span><span class="z-storage z-type"> 0x</span><span class="z-constant">7f</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span> shift</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>input_byte</span><span class="z-keyword"> &amp;</span><span class="z-storage z-type"> 0x</span><span class="z-constant">80</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Do not allow additional leading zero bits.</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>input_byte</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span class="z-invalid z-illegal"> ||</span><span> consumed_bytes</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> break</span></span> <span class="giallo-l"><span> shift</span><span class="z-keyword"> +=</span><span class="z-constant"> 7</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>ret</span><span>,</span><span> consumed_bytes</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This helper parses the jumpdest table into a list of relative offsets</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This will abort on truncated (short) input</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> parse_table</span><span>(</span><span class="z-variable z-parameter z-function">input</span><span>:</span><span class="z-support"> bytes</span><span>)</span><span> -&gt;</span><span> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> jumpdests</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> pos</span><span class="z-keyword"> &lt;</span><span class="z-support"> len</span><span>(</span><span class="z-support">input</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> value</span><span>,</span><span> consumed_bytes</span><span class="z-keyword"> =</span><span> leb128u_decode</span><span>(</span><span class="z-support">input</span><span>[</span><span>pos</span><span>:</span><span>]</span><span>)</span></span> <span class="giallo-l"><span> jumpdests</span><span>.</span><span>append</span><span>(</span><span>value</span><span>)</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> +=</span><span> consumed_bytes</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> jumpdests</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This helper translates the delta offsets into absolute ones</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> This will abort on invalid 0-value entries</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> process_jumpdests</span><span>(</span><span class="z-variable z-parameter z-function">delta</span><span>:</span><span> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>)</span><span> -&gt;</span><span> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>:</span></span> <span class="giallo-l"><span> jumpdests</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> partial_sum</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span> first</span><span class="z-keyword"> =</span><span class="z-constant"> True</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> d</span><span class="z-keyword"> in</span><span> delta</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> first</span><span>:</span></span> <span class="giallo-l"><span> first</span><span class="z-keyword"> =</span><span class="z-constant"> False</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>d</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span> partial_sum</span><span class="z-keyword"> +=</span><span> d</span></span> <span class="giallo-l"><span> jumpdests</span><span>.</span><span>append</span><span>(</span><span>partial_sum</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> jumpdests</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Fails with assertion on invalid code</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Expects list of absolute jumpdest offsets</span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> validate_code</span><span>(</span><span class="z-variable z-parameter z-function">code</span><span>:</span><span class="z-support"> bytes</span><span>,</span><span class="z-variable z-parameter z-function"> jumpdests</span><span>:</span><span> list</span><span>[</span><span class="z-support">int</span><span>]</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> pos</span><span class="z-keyword"> &lt;</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Ensure the opcode is valid</span></span> <span class="giallo-l"><span> opcode</span><span class="z-keyword"> =</span><span> code</span><span>[</span><span>pos</span><span>]</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>opcode</span><span class="z-keyword"> in</span><span> valid_opcodes</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Remove touched offset</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span>:</span></span> <span class="giallo-l"><span> jumpdests</span><span>.</span><span>remove</span><span>(</span><span>pos</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> except</span><span class="z-support"> ValueError</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> pass</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Skip pushdata</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> opcode</span><span class="z-keyword"> &gt;=</span><span class="z-storage z-type"> 0x</span><span class="z-constant">60</span><span class="z-keyword"> and</span><span> opcode</span><span class="z-keyword"> &lt;=</span><span class="z-storage z-type"> 0x</span><span class="z-constant">7f</span><span>:</span></span> <span class="giallo-l"><span> pos</span><span class="z-keyword"> +=</span><span> opcode</span><span class="z-keyword"> -</span><span class="z-storage z-type"> 0x</span><span class="z-constant">60</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Ensure last PUSH doesn&#39;t go over code end</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>pos</span><span class="z-keyword"> ==</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> The table is invalid if there are untouched locations</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span class="z-support">len</span><span>(</span><span>jumpdests</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>)</span></span></code></pre><h2 id="test-cases">Test Cases</h2> <h4 id="valid-bytecodes">Valid bytecodes</h4> <ul> <li>No jumpdests</li> <li>Every byte is a jumpdest</li> <li>Distant jumpdests (0x7f and 0x3f01 bytes apart)</li> <li>Max number of jumpdests <ul> <li>1-byte offset encoding: initcode of max size (64K) with jumpdest at each byte - table contains 65536 1-byte offsets, first one is 0x00, all others equal 0x01</li> <li>2-byte offset encoding: inicode of max size with jumpdests 0x80 (128) bytes apart - table contains 512 offsets, first one is 0x7f (127), all others equal 0x8001</li> <li>3-byte offset encoding: inicode of max size with jumpdests 0x4000 (16384) bytes apart - table contains 4 offsets: 0xFF7F (16383), 0x808001, 0x808001, 0x808001</li> </ul> </li> </ul> <h4 id="invalid-bytecodes">Invalid bytecodes</h4> <ul> <li>Empty jumpdest section</li> <li>Multiple jumpdest sections</li> <li>jumpdest section after the code section</li> <li>jumpdest section after the data section</li> <li>Final jumploc in the table is truncated (not a valid LEB128)</li> <li>LEB128 encoding with extra 0s (non-minimal encoding)</li> <li>Jumpdest location pointing to PUSH data</li> <li>Jumpdest location out of code section bounds <ul> <li>pointing into data section</li> <li>pointing into jumpdest section</li> <li>pointing outside container bounds</li> </ul> </li> <li>Duplicate jumpdest locations (0 deltas in table other than 1st offset)</li> <li>Code containing <code>JUMP</code> but no jumpdest table</li> <li>Code containing <code>JUMPI</code> but no jumpdest table</li> <li>Code containing jumpdest table but not <code>JUMP</code>/<code>JUMPI</code></li> <li>Code containing <code>JUMPDEST</code></li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change poses no risk to backwards compatibility, as it is introduced at the same time EIP-3540 is. The requirement of a JUMPDEST table does not cover legacy bytecode.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The authors are not aware of any security or DoS risks posed by this change.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-05-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zhenyu Sunhttps://github.com/Ungigdu Xinqi Yanghttps://github.com/xinqiyang https://wg-eips.ritovision.com/3589/ <h2 id="simple-summary">Simple Summary</h2> <p>This standard defines a ERC-721 token called assembly token which can represent a combination of assets.</p> <h2 id="abstract">Abstract</h2> <p>The ERC-1155 multi-token contract defines a way to batch transfer tokens, but those tokens must be minted by the ERC-1155 contract itself. This EIP is an ERC-721 extension with ability to assemble assets such as ether, ERC-20 tokens, ERC-721 tokens and ERC-1155 tokens into one ERC-721 token whose token id is also the asset's signature. As assets get assembled into one, batch transfer or swap can be implemented very easily.</p> <h2 id="motivation">Motivation</h2> <p>As NFT arts and collectors rapidly increases, some collectors are not satisfied with traditional trading methods. When two collectors want to swap some of their collections, currently they can list their NFTs on the market and notify the other party to buy, but this is inefficient and gas-intensive. Instead, some collectors turn to social media or chat group looking for a trustworthy third party to swap NFTs for them. The third party takes NFTs from both collector A and B, and transfer A's collections to B and B's to A. This is very risky.</p> <p>The safest way to do batch swap, is to transform batch swap into atomic swap, i.e. one to one swap. But first we should "assemble" those ether, ERC-20 tokens, ERC-721 tokens and ERC-1155 tokens together, and this is the main purpose of this EIP.</p> <h2 id="specification">Specification</h2> <p>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> <p>ERC-721 compliant contracts MAY implement this ERC to provide a standard method to assemble assets.</p> <p><code>mint</code> and <code>safeMint</code> assemble assets into one ERC-721 token. <code>mint</code> SHOULD be implemented for normal ERC-20 tokens whose <code>_transfer</code> is lossless. <code>safeMint</code> MUST takes care for lossy token such as PIG token whose <code>_transfer</code> function is taxed.</p> <p><code>_salt</code> of <code>hash</code> function MAY be implemented other way, even provided as user input. But the token id MUST be generated by <code>hash</code> function.</p> <p>Implementations of the standard MAY supports different set of assets.</p> <p>Implementers of this standard MUST have all of the following functions:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.8.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface AssemblyNFTInterface {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> event AssemblyAsset(address indexed firstHolder,</span></span> <span class="giallo-l"><span> uint256 indexed tokenId,</span></span> <span class="giallo-l"><span> uint256 salt,</span></span> <span class="giallo-l"><span> address[] addresses,</span></span> <span class="giallo-l"><span> uint256[] numbers);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev hash function assigns the combination of assets with salt to bytes32 signature that is also the token id.</span></span> <span class="giallo-l"><span> * @param `_salt` prevents hash collision, can be chosen by user input or increasing nonce from contract.</span></span> <span class="giallo-l"><span> * @param `_addresses` concat assets addresses, e.g. [ERC-20_address1, ERC-20_address2, ERC-721_address_1, ERC-1155_address_1, ERC-1155_address_2]</span></span> <span class="giallo-l"><span> * @param `_numbers` describes how many eth, ERC-20 token addresses length, ERC-721 token addresses length, ERC-1155 token addresses length,</span></span> <span class="giallo-l"><span> * ERC-20 token amounts, ERC-721 token ids, ERC-1155 token ids and amounts.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function hash(uint256 _salt, address[] memory _addresses, uint256[] memory _numbers) external pure returns (uint256 tokenId);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev to assemble lossless assets</span></span> <span class="giallo-l"><span> /// @param `_to` the receiver of the assembly token</span></span> <span class="giallo-l"><span> function mint(address _to, address[] memory _addresses, uint256[] memory _numbers) payable external returns(uint256 tokenId);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev mint with additional logic that calculates the actual received value for tokens.</span></span> <span class="giallo-l"><span> function safeMint(address _to, address[] memory _addresses, uint256[] memory _numbers) payable external returns(uint256 tokenId);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev burn this token and releases assembled assets</span></span> <span class="giallo-l"><span> /// @param `_to` to which address the assets is released</span></span> <span class="giallo-l"><span> function burn(address _to, uint256 _tokenId, uint256 _salt, address[] calldata _addresses, uint256[] calldata _numbers) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <p>There are many reasons why people want to pack their NFTs together. For example, a collector want to pack a set of football players into a football team; a collector has hundreds of of NFTs with no categories to manage them; a collector wants to buy a full collection of NFTs or none of them. They all need a way a assemble those NFTs together.</p> <p>The reason for choosing ERC-721 standard as a wrapper is ERC-721 token is already widely used and well supported by NFT wallets. And assembly token itself can also be assembled again. Assembly token is easier for smart contract to use than a batch of assets, in scenarios like batch trade, batch swap or collections exchange.</p> <p>This standard has AssemblyAsset event which records the exact kinds and amounts of assets the assembly token represents. The wallet can easily display those NFTs to user just by the token id.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal combines already available 721 extensions and is backwards compatible with the ERC-721 standard.</p> <h2 id="implementation">Implementation</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.8.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>import &quot;@openzeppelin/contracts/token/ERC20/IERC20.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;@openzeppelin/contracts/token/ERC721/ERC721.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;@openzeppelin/contracts/token/ERC721/utils/ERC721Holder.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;@openzeppelin/contracts/token/ERC1155/ERC1155.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;@openzeppelin/contracts/token/ERC1155/utils/ERC1155Holder.sol&quot;;</span></span> <span class="giallo-l"><span>import &quot;./AssemblyNFTInterface.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>abstract contract AssemblyNFT is ERC721, ERC721Holder, ERC1155Holder, AssemblyNFTInterface{</span></span> <span class="giallo-l"><span> using SafeERC20 for IERC20;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function supportsInterface(bytes4 interfaceId) public view virtual override(ERC721, ERC1155Receiver) returns (bool) {</span></span> <span class="giallo-l"><span> return ERC721.supportsInterface(interfaceId) || ERC1155Receiver.supportsInterface(interfaceId);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> uint256 nonce;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * layout of _addresses:</span></span> <span class="giallo-l"><span> * erc20 addresses | erc721 addresses | erc1155 addresses</span></span> <span class="giallo-l"><span> * layout of _numbers:</span></span> <span class="giallo-l"><span> * eth | erc20.length | erc721.length | erc1155.length | erc20 amounts | erc721 ids | erc1155 ids | erc1155 amounts</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function hash(uint256 _salt, address[] memory _addresses, uint256[] memory _numbers) public pure override returns (uint256 tokenId){</span></span> <span class="giallo-l"><span> bytes32 signature = keccak256(abi.encodePacked(_salt));</span></span> <span class="giallo-l"><span> for(uint256 i=0; i&lt; _addresses.length; i++){</span></span> <span class="giallo-l"><span> signature = keccak256(abi.encodePacked(signature, _addresses[i]));</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> for(uint256 j=0; j&lt;_numbers.length; j++){</span></span> <span class="giallo-l"><span> signature = keccak256(abi.encodePacked(signature, _numbers[j]));</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> assembly {</span></span> <span class="giallo-l"><span> tokenId := signature</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function mint(address _to, address[] memory _addresses, uint256[] memory _numbers) payable external override returns(uint256 tokenId){</span></span> <span class="giallo-l"><span> require(_to != address(0), &quot;can&#39;t mint to address(0)&quot;);</span></span> <span class="giallo-l"><span> require(msg.value == _numbers[0], &quot;value not match&quot;);</span></span> <span class="giallo-l"><span> require(_addresses.length == _numbers[1] + _numbers[2] + _numbers[3], &quot;2 array length not match&quot;);</span></span> <span class="giallo-l"><span> require(_addresses.length == _numbers.length -4 - _numbers[3], &quot;numbers length not match&quot;);</span></span> <span class="giallo-l"><span> uint256 pointerA; //points to first erc20 address, if there is any</span></span> <span class="giallo-l"><span> uint256 pointerB =4; //points to first erc20 amount, if there is any</span></span> <span class="giallo-l"><span> for(uint256 i = 0; i&lt; _numbers[1]; i++){</span></span> <span class="giallo-l"><span> require(_numbers[pointerB] &gt; 0, &quot;transfer erc20 0 amount&quot;);</span></span> <span class="giallo-l"><span> IERC20(_addresses[pointerA++]).safeTransferFrom(_msgSender(), address(this), _numbers[pointerB++]);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> for(uint256 j = 0; j&lt; _numbers[2]; j++){</span></span> <span class="giallo-l"><span> IERC721(_addresses[pointerA++]).safeTransferFrom(_msgSender(), address(this), _numbers[pointerB++]);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> for(uint256 k =0; k&lt; _numbers[3]; k++){</span></span> <span class="giallo-l"><span> IERC1155(_addresses[pointerA++]).safeTransferFrom(_msgSender(), address(this), _numbers[pointerB], _numbers[_numbers[3] + pointerB++], &quot;&quot;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> tokenId = hash(nonce, _addresses, _numbers);</span></span> <span class="giallo-l"><span> super._mint(_to, tokenId);</span></span> <span class="giallo-l"><span> emit AssemblyAsset(_to, tokenId, nonce, _addresses, _numbers);</span></span> <span class="giallo-l"><span> nonce ++;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function safeMint(address _to, address[] memory _addresses, uint256[] memory _numbers) payable external override returns(uint256 tokenId){</span></span> <span class="giallo-l"><span> require(_to != address(0), &quot;can&#39;t mint to address(0)&quot;);</span></span> <span class="giallo-l"><span> require(msg.value == _numbers[0], &quot;value not match&quot;);</span></span> <span class="giallo-l"><span> require(_addresses.length == _numbers[1] + _numbers[2] + _numbers[3], &quot;2 array length not match&quot;);</span></span> <span class="giallo-l"><span> require(_addresses.length == _numbers.length -4 - _numbers[3], &quot;numbers length not match&quot;);</span></span> <span class="giallo-l"><span> uint256 pointerA; //points to first erc20 address, if there is any</span></span> <span class="giallo-l"><span> uint256 pointerB =4; //points to first erc20 amount, if there is any</span></span> <span class="giallo-l"><span> for(uint256 i = 0; i&lt; _numbers[1]; i++){</span></span> <span class="giallo-l"><span> require(_numbers[pointerB] &gt; 0, &quot;transfer erc20 0 amount&quot;);</span></span> <span class="giallo-l"><span> IERC20 token = IERC20(_addresses[pointerA++]);</span></span> <span class="giallo-l"><span> uint256 orgBalance = token.balanceOf(address(this));</span></span> <span class="giallo-l"><span> token.safeTransferFrom(_msgSender(), address(this), _numbers[pointerB]);</span></span> <span class="giallo-l"><span> _numbers[pointerB++] = token.balanceOf(address(this)) - orgBalance;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> for(uint256 j = 0; j&lt; _numbers[2]; j++){</span></span> <span class="giallo-l"><span> IERC721(_addresses[pointerA++]).safeTransferFrom(_msgSender(), address(this), _numbers[pointerB++]);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> for(uint256 k =0; k&lt; _numbers[3]; k++){</span></span> <span class="giallo-l"><span> IERC1155(_addresses[pointerA++]).safeTransferFrom(_msgSender(), address(this), _numbers[pointerB], _numbers[_numbers[3] + pointerB++], &quot;&quot;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> tokenId = hash(nonce, _addresses, _numbers);</span></span> <span class="giallo-l"><span> super._mint(_to, tokenId);</span></span> <span class="giallo-l"><span> emit AssemblyAsset(_to, tokenId, nonce, _addresses, _numbers);</span></span> <span class="giallo-l"><span> nonce ++;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> function burn(address _to, uint256 _tokenId, uint256 _salt, address[] calldata _addresses, uint256[] calldata _numbers) override external {</span></span> <span class="giallo-l"><span> require(_msgSender() == ownerOf(_tokenId), &quot;not owned&quot;);</span></span> <span class="giallo-l"><span> require(_tokenId == hash(_salt, _addresses, _numbers));</span></span> <span class="giallo-l"><span> super._burn(_tokenId);</span></span> <span class="giallo-l"><span> payable(_to).transfer(_numbers[0]);</span></span> <span class="giallo-l"><span> uint256 pointerA; //points to first erc20 address, if there is any</span></span> <span class="giallo-l"><span> uint256 pointerB =4; //points to first erc20 amount, if there is any</span></span> <span class="giallo-l"><span> for(uint256 i = 0; i&lt; _numbers[1]; i++){</span></span> <span class="giallo-l"><span> require(_numbers[pointerB] &gt; 0, &quot;transfer erc20 0 amount&quot;);</span></span> <span class="giallo-l"><span> IERC20(_addresses[pointerA++]).safeTransfer(_to, _numbers[pointerB++]);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> for(uint256 j = 0; j&lt; _numbers[2]; j++){</span></span> <span class="giallo-l"><span> IERC721(_addresses[pointerA++]).safeTransferFrom(address(this), _to, _numbers[pointerB++]);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> for(uint256 k =0; k&lt; _numbers[3]; k++){</span></span> <span class="giallo-l"><span> IERC1155(_addresses[pointerA++]).safeTransferFrom(address(this), _to, _numbers[pointerB], _numbers[_numbers[3] + pointerB++], &quot;&quot;);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>Before using <code>mint</code> or <code>safeMint</code> functions, user should be aware that some implementations of tokens are pausable. If one of the assets get paused after assembled into one NFT, the <code>burn</code> function may not be executed successfully. Platforms using this standard should make support lists or block lists to avoid this situation.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-05-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gajinder Singhhttps://github.com/g11in Piper Merriamhttps://github.com/pipermerriam https://wg-eips.ritovision.com/3584/ <h2 id="simple-summary">Simple Summary</h2> <p>A proposal to build a block's <code>access_list</code> and include its fingerprint <code>AccessListRoot</code> in the block header.</p> <h2 id="abstract">Abstract</h2> <p><a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>/<a href="https://wg-eips.ritovision.com/2930/">EIP-2930</a> centers around normalizing the (low) gas costs of data/storage accesses made by a transaction as well as providing for (and encouraging) a new transaction type format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x01 || rlp([chainId, nonce, gasPrice, gasLimit, to, value, data, access_list, yParity, senderR, senderS])</span></span></code></pre> <p>that makes upfront <code>access_list</code> declarations, where <code>access_list</code> is some <code>[[{20 bytes}, [{32 bytes}...]]...]</code> map of <code>AccessedAddress=&gt; AccessedStorageKeys</code>.</p> <p>The first <em>accesses</em> of these upfront <em>declarations</em> are charged at discounted price (roughly ~<code>10%</code>) and first accesses outside this list are charged higher price. Reason is upfront access declaration provides for a way to <em>preload/optimize/batch</em> loading these locations while executing the transaction. This inadvertently leads to generation of transaction <code>access_list</code> that has all (first) accesses (declared or not) made by a transaction. This proposal is to collate these <em>transaction</em> <code>access_list</code>s for all the transactions in a <strong>block</strong> <code>access_list</code> document and include its <em>fingerprint</em> in the block header.</p> <h2 id="motivation">Motivation</h2> <p>Motivation for collating the <em>transaction</em> <code>access_list</code>s for all the transactions in a <strong>block</strong>’s <code>access_list</code> is to have an <em>access index</em> of the block with following benefits:</p> <ol> <li>Block execution/validation optimizations/parallelization/cache warm-up by enabling construction of <em>a partial order</em> for access and hence execution (hint: <em>chains</em> in this <em>poset</em> can be parallelized).</li> <li>Enabling partial inspection and fetching/serving of a block data/state by <em>light sync</em> or <em>fast sync</em> protocols concerned with a subset of addresses.</li> <li>Possible future extension of this list to serve as index for bundling, serving and fetching witness data for <em>stateless</em> protocols.</li> </ol> <h2 id="specification">Specification</h2> <p>A block <code>access_list</code> represents:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Set [ </span></span> <span class="giallo-l"><span> AccessedAddress, </span></span> <span class="giallo-l"><span> List [AccessedStorageKeys] , </span></span> <span class="giallo-l"><span> Set [ AccessedInBlockTransactionNumber, List [ AccessedStorageKeys ]] </span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>A <strong>canonical</strong> construction of such an <code>access_list</code> is specified as below.</p> <h3 id="canonical-block-access-list">Canonical Block Access List</h3> <p>An <code>access_list</code> is defined to be comprised of many <code>access_list_entry</code> elements:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>access_list := [access_list_entry, ...]</span></span></code></pre> <p>An <code>access_list_entry</code> is a 3-tuple of:</p> <ul> <li>address</li> <li>sorted list of storage keys of the address accessed across the entire block</li> <li>sorted list of 2-tuples of: <ul> <li>transaction index in which the address or any of its storage keys were accessed</li> <li>sorted list of storage keys which were accessed</li> </ul> </li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>access_list := [access_list_entry, ...]</span></span> <span class="giallo-l"><span>access_list_entry := [address, storage_keys, accesses_by_txn_index]</span></span> <span class="giallo-l"><span>address := bytes20</span></span> <span class="giallo-l"><span>accesses_by_txn_index := [txn_index_and_keys, ...]</span></span> <span class="giallo-l"><span>txn_index_and_keys := [txn_index, storage_keys]</span></span> <span class="giallo-l"><span>txn_index := uint64 # or uint256 or whatever</span></span> <span class="giallo-l"><span>storage_keys := [storage_key, ...]</span></span> <span class="giallo-l"><span>storage_key := bytes32</span></span></code></pre> <p>Additional sorting rules for the above are that:</p> <ul> <li><code>access_list</code> is sorted by the <code>address</code></li> <li><code>storage_keys</code> is sorted</li> <li><code>accesses_by_txn_index</code> is sorted by <code>txn_index</code></li> </ul> <p>Additional validation rules for the above are that:</p> <ul> <li>Each unique <code>address</code> may only appear at most once in <code>access_list</code></li> <li>Each <code>storage_key</code> may only appear at most once in <code>storage_keys</code></li> <li>Each <code>txn_index</code> may only appear at most once in <code>txn_index_and_keys</code></li> </ul> <p>All sorting is in increasing order.</p> <h3 id="accesslistroot">AccessListRoot</h3> <p>An <code>AccessListRoot</code> is a URN <em>like</em> encoding <code>Hash/Commitment</code> of the canonical <code>access_list</code> as well as the construction type ( <code>sha256</code> ) and serialization type ( <code>json</code> ), i.e.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>AccessListRoot := &quot;urn:sha256:json:0x${ SHA256( access_list.toJSONString(&#39;utf8&#39;) ).toHexString() }&quot;</span></span></code></pre> <p>where <code>0x${ SHA256 (...)...}</code> is the <code>SHA256</code> hashed <code>32</code> bytes hex string as indicated by leading <code>0x</code>.</p> <h3 id="additional-block-validation">Additional Block Validation</h3> <p>Validating a new block requires an additional validation check that the block’s <code>AccessListRoot</code> matches the one generated by executing the block using the construction as defined by the <code>AccessListRoot</code> URN.</p> <h2 id="rationale">Rationale</h2> <h3 id="sorting-of-canonical-access-list">Sorting of canonical <code>access_list</code></h3> <p>It is specified to be sorted in lexicographic ordering or integer sorting wherever applicable and specified. Sorting with respect to access time was considered but didn't seem to provide any additional benefit at the cost of adding implementation complexity and bookkeeping.</p> <h3 id="accesslistroot-1"><code>AccessListRoot</code></h3> <p><code>AccessListRoot</code> is generated to prevent any <em>griefing</em> attacks and hence will need to be included (and validated) in the <em>block header</em>. Even though <code>AccessListRoot</code> is currently specified to be a simple <code>sha256</code> hash of the canonical <code>access_list</code>, it would be beneficial to consider other constructions</p> <ul> <li>a tree structure (<code>merkle</code>/<code>verkle</code>). It will be a bit more expensive but will enable partial downloading, inspection and validation of the <code>access_list</code>.</li> <li>a normal <code>kate</code> commitment can also be generated to enable this partial capability and is recommended as validating partial fetch of access list chunks would be very simple.</li> </ul> <p>Also serialization of the <code>access_list</code> is currently specified as a normal <code>JSON String</code> dump and these parameters could vary from construction to construction, but for the sake of simplicity, it can always be <code>sha256</code> hashed to get a consistent <code>32</code> bytes hex string root.</p> <p>So this AccessListRoot could evolve to <code>urn:merkle:ssz:...</code> or to <code>urn:kate:...</code> or to any other scheme as per requirement. And the idea of having the <code>AccessListRoot</code> as URN <em>like</em> structure is to enable upgradation to these paths without affecting block structure.</p> <h3 id="future-extensions-of-access-list">Future extensions of <code>access_list</code></h3> <p>We can extend the notion of a block’s <code>access_list</code> to include witnesses:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>access_list := Set[ </span></span> <span class="giallo-l"><span> Address,</span></span> <span class="giallo-l"><span> List [ AddressWitnesses ],</span></span> <span class="giallo-l"><span> Set [ AccessedStorageKey, List [ StorageKeyWitnesses] ], </span></span> <span class="giallo-l"><span> Set [ AccessedInBlockTransactionNumber, List [ AccessedStorageKeys ] ]</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>and then get to define the a canonical specification for building the fingerprint. This will allow an incremental path to partial or full statelessness, where it would be easy to bundle/request <strong>witnesses</strong> using this <code>access_list</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The extra block validation will only be mandatory post the block number this EIP comes into effect, but the clients can still provide a way to generate (and possibly store) this access list on request (via the <code>JSON/RPC</code> api). However this is optional and client dependent.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no known security issues as a result of this change.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-05-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sam Porterhttps://github.com/SamPorter1984 https://wg-eips.ritovision.com/3561/

proxy with a delay before specified upgrade goes live

<h2 id="abstract">Abstract</h2> <p>Removing trust from upgradeability proxy is necessary for anonymous developers. In order to accomplish this, instant and potentially malicious upgrades must be prevented. This EIP introduces additional storage slots for upgradeability proxy which are assumed to decrease trust in interaction with upgradeable smart contracts. Defined by the admin implementation logic can be made an active implementation logic only after Zero Trust Period allows.</p> <h2 id="motivation">Motivation</h2> <p>Anonymous developers who utilize upgradeability proxies typically struggle to earn the trust of the community.</p> <p>Fairer, better future for humanity absolutely requires some developers to stay anonymous while still attract vital attention to solutions they propose and at the same time leverage the benefits of possible upgradeability.</p> <h2 id="specification">Specification</h2> <p>The specification is an addition to the standard <a href="https://wg-eips.ritovision.com/1967/">EIP-1967</a> transparent proxy design. The specification focuses on the slots it adds. All admin interactions with trust minimized proxy must emit an event to make admin actions trackable, and all admin actions must be guarded with <code>onlyAdmin()</code> modifier.</p> <h3 id="next-logic-contract-address">Next Logic Contract Address</h3> <p>Storage slot <code>0x19e3fabe07b65998b604369d85524946766191ac9434b39e27c424c976493685</code> (obtained as <code>bytes32(uint256(keccak256('eip3561.proxy.next.logic')) - 1)</code>). Desirable implementation logic address must be first defined as next logic, before it can function as actual logic implementation stored in EIP-1967 <code>IMPLEMENTATION_SLOT</code>. Admin interactions with next logic contract address correspond with these methods and events:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Sets next logic contract address. Emits NextLogicDefined</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> If current implementation is address(0), then upgrades to IMPLEMENTATION_SLOT</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> immedeatelly, therefore takes data as an argument</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> proposeTo</span><span>(</span><span class="z-support">address</span><span class="z-variable"> implementation</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> IfAdmin</span></span> <span class="giallo-l"><span>// </span><span class="z-entity z-name">As</span><span class="z-entity z-name"> soon</span><span class="z-entity z-name"> UPGRADE_BLOCK_SLOT</span><span class="z-entity z-name"> allows</span><span>,</span><span class="z-entity z-name"> sets</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> stored</span><span class="z-entity z-name"> as</span><span class="z-entity z-name"> next</span><span class="z-entity z-name"> implementation</span></span> <span class="giallo-l"><span>// </span><span class="z-entity z-name">as</span><span class="z-entity z-name"> current</span><span class="z-entity z-name"> IMPLEMENTATION_SLOT</span><span class="z-entity z-name"> and</span><span class="z-entity z-name"> initializes</span><span class="z-entity z-name"> it</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> upgrade</span><span>(</span><span class="z-entity z-name">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-entity z-name"> data</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> IfAdmin</span></span> <span class="giallo-l"><span>// </span><span class="z-entity z-name">cancelling</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> possible</span><span class="z-keyword"> for</span><span class="z-entity z-name"> as</span><span class="z-entity z-name"> long</span><span class="z-entity z-name"> as</span><span class="z-entity z-name"> upgrade</span><span>(</span><span>)</span><span class="z-keyword"> for</span><span class="z-entity z-name"> given</span><span class="z-entity z-name"> next</span><span class="z-entity z-name"> logic</span><span class="z-entity z-name"> was</span><span class="z-entity z-name"> not</span><span class="z-entity z-name"> called</span></span> <span class="giallo-l"><span>// </span><span class="z-entity z-name">emits</span><span class="z-entity z-name"> NextLogicCanceled</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> cancelUpgrade</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyAdmin</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> NextLogicDefined</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> nextLogic</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> earliestArrivalBlock</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> important to have</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> NextLogicCanceled</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> oldLogic</span><span>)</span><span>;</span></span></code></pre><h3 id="upgrade-block">Upgrade Block</h3> <p>Storage slot <code>0xe3228ec3416340815a9ca41bfee1103c47feb764b4f0f4412f5d92df539fe0ee</code> (obtained as <code>bytes32(uint256(keccak256('eip3561.proxy.next.logic.block')) - 1)</code>). On/after this block next logic contract address can be set to EIP-1967 <code>IMPLEMENTATION_SLOT</code> or, in other words, <code>upgrade()</code> can be called. Updated automatically according to Zero Trust Period, shown as <code>earliestArrivalBlock</code> in the event <code>NextLogicDefined</code>.</p> <h3 id="propose-block">Propose Block</h3> <p>Storage slot <code>0x4b50776e56454fad8a52805daac1d9fd77ef59e4f1a053c342aaae5568af1388</code> (obtained as <code>bytes32(uint256(keccak256('eip3561.proxy.propose.block')) - 1)</code>). Defines after/on which block <em>proposing</em> next logic is possible. Required for convenience, for example can be manually set to a year from given time. Can be set to maximum number to completely seal the code. Admin interactions with this slot correspond with this method and event:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> prolongLock</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> b</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyAdmin</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ProposingUpgradesRestrictedUntil</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> block</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> nextProposedLogicEarliestArrival</span><span>)</span><span>;</span></span></code></pre><h3 id="zero-trust-period">Zero Trust Period</h3> <p>Storage slot <code>0x7913203adedf5aca5386654362047f05edbd30729ae4b0351441c46289146720</code> (obtained as <code>bytes32(uint256(keccak256('eip3561.proxy.zero.trust.period')) - 1)</code>). Zero Trust Period in amount of blocks, can only be set higher than previous value. While it is at default value(0), the proxy operates exactly as standard EIP-1967 transparent proxy. After zero trust period is set, all above specification is enforced. Admin interactions with this slot should correspond with this method and event:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setZeroTrustPeriod</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> blocks</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyAdmin</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ZeroTrustPeriodSet</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> blocks</span><span>)</span><span>;</span></span></code></pre><h3 id="implementation-example">Implementation Example</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> &gt;=0.8.0</span><span>;</span><span class="z-comment"> //</span><span class="z-comment">important</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> EIP-3561 trust minimized proxy implementation https://github.com/ethereum/EIPs/blob/master/EIPS/./03561.md</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Based on EIP-1967 upgradeability proxy: https://github.com/ethereum/EIPs/blob/master/EIPS/./01967.md</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> TrustMinimizedProxy</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Upgraded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> toLogic</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AdminChanged</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> previousAdmin</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newAdmin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NextLogicDefined</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> nextLogic</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> earliestArrivalBlock</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ProposingUpgradesRestrictedUntil</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> block</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> nextProposedLogicEarliestArrival</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NextLogicCanceled</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ZeroTrustPeriodSet</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> blocks</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> constant</span><span> ADMIN_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> constant</span><span> LOGIC_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> constant</span><span> NEXT_LOGIC_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0x19e3fabe07b65998b604369d85524946766191ac9434b39e27c424c976493685</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> constant</span><span> NEXT_LOGIC_BLOCK_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0xe3228ec3416340815a9ca41bfee1103c47feb764b4f0f4412f5d92df539fe0ee</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> constant</span><span> PROPOSE_BLOCK_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0x4b50776e56454fad8a52805daac1d9fd77ef59e4f1a053c342aaae5568af1388</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> constant</span><span> ZERO_TRUST_PERIOD_SLOT </span><span class="z-keyword">=</span><span class="z-constant"> 0x7913203adedf5aca5386654362047f05edbd30729ae4b0351441c46289146720</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span> payable </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> ADMIN_SLOT </span><span class="z-keyword">==</span><span class="z-support"> bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&#39;eip1967.proxy.admin&#39;</span><span>)</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> &amp;&amp;</span></span> <span class="giallo-l"><span> LOGIC_SLOT </span><span class="z-keyword">==</span><span class="z-support"> bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&#39;eip1967.proxy.implementation&#39;</span><span>)</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> &amp;&amp;</span></span> <span class="giallo-l"><span> NEXT_LOGIC_SLOT </span><span class="z-keyword">==</span><span class="z-support"> bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&#39;eip3561.proxy.next.logic&#39;</span><span>)</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> &amp;&amp;</span></span> <span class="giallo-l"><span> NEXT_LOGIC_BLOCK_SLOT </span><span class="z-keyword">==</span><span class="z-support"> bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&#39;eip3561.proxy.next.logic.block&#39;</span><span>)</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> &amp;&amp;</span></span> <span class="giallo-l"><span> PROPOSE_BLOCK_SLOT </span><span class="z-keyword">==</span><span class="z-support"> bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&#39;eip3561.proxy.propose.block&#39;</span><span>)</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> &amp;&amp;</span></span> <span class="giallo-l"><span> ZERO_TRUST_PERIOD_SLOT </span><span class="z-keyword">==</span><span class="z-support"> bytes32</span><span>(</span><span class="z-support">uint256</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-string">&#39;eip3561.proxy.zero.trust.period&#39;</span><span>)</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setAdmin</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> IfAdmin</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span class="z-entity z-name"> _admin</span><span>(</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-constant"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _fallback</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _logic</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> logic</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> logic </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>LOGIC_SLOT</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _nextLogic</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> nextLogic</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> nextLogic </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>NEXT_LOGIC_SLOT</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _proposeBlock</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> b</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> b </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>PROPOSE_BLOCK_SLOT</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _nextLogicBlock</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> b</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> b </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>NEXT_LOGIC_BLOCK_SLOT</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _zeroTrustPeriod</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> ztp</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> ztp </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>ZERO_TRUST_PERIOD_SLOT</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _admin</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> adm</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> adm </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>ADMIN_SLOT</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _setAdmin</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newAdm</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span>ADMIN_SLOT</span><span>,</span><span> newAdm</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> changeAdmin</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newAdm</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> IfAdmin</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> AdminChanged</span><span>(</span><span class="z-entity z-name">_admin</span><span>(</span><span>)</span><span>,</span><span> newAdm</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setAdmin</span><span>(</span><span>newAdm</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> upgrade</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> IfAdmin</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>number </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-entity z-name"> _nextLogicBlock</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &#39;too soon&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> logic</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> logic </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>NEXT_LOGIC_SLOT</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span>LOGIC_SLOT</span><span>,</span><span> logic</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span> )</span><span class="z-keyword"> =</span><span> logic</span><span>.</span><span class="z-entity z-name">delegatecall</span><span>(</span><span>data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>success</span><span>,</span><span class="z-string"> &#39;failed to call&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Upgraded</span><span>(</span><span>logic</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> fallback</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _fallback</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> receive</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _fallback</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _fallback</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> !=</span><span class="z-entity z-name"> _admin</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _delegate</span><span>(</span><span class="z-entity z-name">_logic</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelUpgrade</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> IfAdmin</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> logic</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> logic </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>LOGIC_SLOT</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span>NEXT_LOGIC_SLOT</span><span>,</span><span> logic</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> NextLogicCanceled</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> prolongLock</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> b</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> IfAdmin</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>b </span><span class="z-keyword">&gt;</span><span class="z-entity z-name"> _proposeBlock</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &#39;can be only set higher&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span>PROPOSE_BLOCK_SLOT</span><span>,</span><span> b</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ProposingUpgradesRestrictedUntil</span><span>(</span><span>b</span><span>,</span><span> b </span><span class="z-keyword">+</span><span class="z-entity z-name"> _zeroTrustPeriod</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setZeroTrustPeriod</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> blocks</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> IfAdmin</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> before this set at least once acts like a normal eip 1967 transparent proxy</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> ztp</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> ztp </span><span class="z-keyword">:=</span><span class="z-entity z-name"> sload</span><span>(</span><span>ZERO_TRUST_PERIOD_SLOT</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>blocks </span><span class="z-keyword">&gt;</span><span> ztp</span><span>,</span><span class="z-string"> &#39;can be only set higher&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span>ZERO_TRUST_PERIOD_SLOT</span><span>,</span><span> blocks</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> _updateNextBlockSlot</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ZeroTrustPeriodSet</span><span>(</span><span>blocks</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _updateNextBlockSlot</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> nlb </span><span class="z-keyword">=</span><span class="z-variable z-language"> block</span><span>.</span><span>number </span><span class="z-keyword">+</span><span class="z-entity z-name"> _zeroTrustPeriod</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span>NEXT_LOGIC_BLOCK_SLOT</span><span>,</span><span> nlb</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _setNextLogic</span><span>(</span><span class="z-support">address</span><span class="z-variable"> nl</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>number </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-entity z-name"> _proposeBlock</span><span>(</span><span>)</span><span>,</span><span class="z-string"> &#39;too soon&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _updateNextBlockSlot</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span>NEXT_LOGIC_SLOT</span><span>,</span><span> nl</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> NextLogicDefined</span><span>(</span><span>nl</span><span>,</span><span class="z-variable z-language"> block</span><span>.</span><span>number </span><span class="z-keyword">+</span><span class="z-entity z-name"> _zeroTrustPeriod</span><span>(</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> proposeTo</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newLogic</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span class="z-entity z-name"> IfAdmin</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-entity z-name">_zeroTrustPeriod</span><span>(</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span class="z-entity z-name"> _logic</span><span>(</span><span>)</span><span class="z-keyword"> ==</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _updateNextBlockSlot</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span>LOGIC_SLOT</span><span>,</span><span> newLogic</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> (</span><span class="z-support">bool</span><span> success</span><span>,</span><span> )</span><span class="z-keyword"> =</span><span> newLogic</span><span>.</span><span class="z-entity z-name">delegatecall</span><span>(</span><span>data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>success</span><span>,</span><span class="z-string"> &#39;failed to call&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Upgraded</span><span>(</span><span>newLogic</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setNextLogic</span><span>(</span><span>newLogic</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _delegate</span><span>(</span><span class="z-support">address</span><span class="z-variable"> logic_</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> calldatacopy</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> calldatasize</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span> result </span><span class="z-keyword">:=</span><span class="z-entity z-name"> delegatecall</span><span>(</span><span class="z-entity z-name">gas</span><span>(</span><span>)</span><span>,</span><span> logic_</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> calldatasize</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> returndatacopy</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-entity z-name"> returndatasize</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> switch result</span></span> <span class="giallo-l"><span> case </span><span class="z-constant">0</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> revert</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> returndatasize</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> default </span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> returndatasize</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>An argument "just don't make such contracts upgadeable at all" fails when it comes to complex systems which do or do not heavily rely on human factor, which might manifest itself in unprecedented ways. It might be impossible to model some systems right on first try. Using decentralized governance for upgrade management coupled with EIP-1967 proxy might become a serious bottleneck for certain protocols before they mature and data is at hand.</p> <p>A proxy without a time delay before an actual upgrade is obviously abusable. A time delay is probably unavoidable, even if it means that inexperienced developers might not have confidence using it. Albeit this is a downside of this EIP, it's a critically important option to have in smart contract development today.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Users must ensure that a trust-minimized proxy they interact with does not allow overflows, ideally represents the exact copy of the code in implementation example above, and also they must ensure that Zero Trust Period length is reasonable(at the very least two weeks if upgrades are usually being revealed beforehand, and in most cases at least a month).</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-05-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Sean Papanikolashttps://github.com/pizzarob https://wg-eips.ritovision.com/3569/ <h2 id="simple-summary">Simple Summary</h2> <p>The Sealed NFT Metadata Extension provides a mechanism to immortalize NFT metadata in a cost-effective manner.</p> <h2 id="abstract">Abstract</h2> <p>This standard accomplishes three things; it provides a way for potential collectors to verify that the NFT metadata will not change, allows creators to immortalize metadata for multiple tokens at one time, and allows metadata for many NFTs to be read and cached from one file. A creator can call the <code>seal</code> function for a range of one or many sequential NFTs. Included as an argument is a URI which points to a decentralized storage service like IPFS and will be stored in the smart contract. The URI will return a JSON object in which the keys are token IDs and the values are either a string which is a URI pointing to a metadata file stored on a decentralized file system, or raw metadata JSON for each token ID. The token ID(s) will then be marked as sealed in the smart contract and cannot be sealed again. The <code>seal</code> function can be called after NFT creation, or during the NFT creation process.</p> <h2 id="motivation">Motivation</h2> <p>In the original ERC-721 standard, the metadata extension specifies a <code>tokenURI</code> function which returns a URI for a single token ID. This may be hosted on IPFS or might be hosted on a centralized server. There's no guarantee that the NFT metadata will not change. This is the same for the ERC-1155 metadata extension. In addition to that - if you want to update the metadata for many NFTs you would need to do so in O(n) time, which as we know is not financially feasible at scale. By allowing for a decentralized URI to point to a JSON object of many NFT IDs we can solve this issue by providing metadata for many tokens at one time rather than one at a time. We can also provide methods which give transparency into whether the NFT has be explicitly "sealed" and that the metadata is hosted on a decentralized storage space.</p> <p>There is not a way for the smart contract layer to communicate with a storage layer and as such we need a solution which provides a way for potential NFT collectors on Ethereum to verify that their NFT will not be "rug pulled". This standard provides a solution for that. By allowing creators to seal their NFTs during or after creation, they are provided with full flexibility when it comes to creating their NFTs. Decentralized storage means permanence - in the fast-moving world of digital marketing campaigns, or art projects mistakes can happen. As such, it is important for creators to have flexibility when creating their projects. Therefore, this standard allows creators to opt in at a time of their choosing. Mistakes do happen and metadata should be flexible enough so that creators can fix mistakes or create dynamic NFTs (see Beeple's CROSSROAD NFT). If there comes a time when the NFT metadata should be immortalized, then the creator can call the <code>seal</code> method. Owners, potential owners, or platforms can verify that the NFT was sealed and can check the returned URI. If the <code>sealedURI</code> return value is not hosted on a decentralized storage platform, or the <code>isSealed</code> method does not return <code>true</code> for the given NFT ID then it can be said that one cannot trust that these NFTs will not change at a future date and can then decide if they want to proceed with collecting the given NFT.</p> <h2 id="specification">Specification</h2> <p>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> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface SealedMetadata {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> @notice This function is used to set a sealed URI for the given range of tokens.</span></span> <span class="giallo-l"><span> @dev</span></span> <span class="giallo-l"><span> - If the sealed URI is being set for one token then the fromTokenId and toTokenId</span></span> <span class="giallo-l"><span> values MUST be the same.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> - If any token within the range of tokens specified has already</span></span> <span class="giallo-l"><span> been sealed then this function MUST throw.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> - This function MAY be called at the time of NFT creation, or after the NFTs have been created.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> - It is RECOMMENDED that this function only be executable by either the creator of the smart contract,</span></span> <span class="giallo-l"><span> or the creator of the NFTs, but this is OPTIONAL and should be implemented based on use case.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> - This function MUST emit the Sealed event</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> - The URI argument SHOULD point to a JSON file hosted within a decentralized file system like IPFS</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> @param fromTokenId The first token in a consecutive range of tokens</span></span> <span class="giallo-l"><span> @param toTokenId The ending token in a consecutive range of tokens</span></span> <span class="giallo-l"><span> @param uri A URI which points to a JSON file hosted on a decentralized file system.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function seal(uint256 fromTokenId, uint256 toTokenId, string memory uri) external;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> @notice This function returns the URI which the sealed metadata can be found for the given token ID</span></span> <span class="giallo-l"><span> @dev</span></span> <span class="giallo-l"><span> - This function MUST throw if the token ID does not exist, or is not sealed</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> @param tokenId Token ID to retrieve the sealed URI for</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> @return The sealed URI in which the metadata for the given token ID can be found</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function sealedURI(uint256 tokenId) external view returns (string);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> @notice This function returns a boolean stating if the token ID is sealed or not</span></span> <span class="giallo-l"><span> @dev This function should throw if the token ID does not exist</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> @param tokenId The token ID that will be checked if sealed or not</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> @return Boolean stating if token ID is sealed</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function isSealed(uint256 tokenId) external view returns (bool)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// @dev This emits when a range of tokens is sealed</span></span> <span class="giallo-l"><span> event Sealed(uint256 indexed fromTokenId, uint256 indexed toTokenId, string memory uri);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="sealed-metadata-json-format">Sealed Metadata JSON Format</h3> <p>The sealed metadata JSON file MAY contain metadata for many different tokens. The top level keys of the JSON object MUST be token IDs.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"></span> <span class="giallo-l"><span>type ERC721Metadata = {</span></span> <span class="giallo-l"><span> name?: string;</span></span> <span class="giallo-l"><span> image?: string;</span></span> <span class="giallo-l"><span> description?: string;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>type SealedMetaDataJson = {</span></span> <span class="giallo-l"><span> [tokenId: string]: string | ERC721Metadata;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>const sealedMetadata: SealedMetaDataJson = {</span></span> <span class="giallo-l"><span> &#39;1&#39;: {</span></span> <span class="giallo-l"><span> name: &#39;Metadata for token with ID 1&#39;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> &#39;2&#39;: {</span></span> <span class="giallo-l"><span> name: &#39;Metadata for token with ID 2&#39;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> // Example pointing to another file</span></span> <span class="giallo-l"><span> &#39;3&#39;: &#39;ipfs://SOME_HASH_ON_IPFS&#39;</span></span> <span class="giallo-l"><span>};</span></span></code></pre><h2 id="rationale">Rationale</h2> <p><strong>Rationale for rule not explicitly requiring that sealed URI be hosted on decentralized filestorage</strong></p> <p>In order for this standard to remain future proof there is no validation within the smart contract that would verify the sealed URI is hosted on IPFS or another decentralized file storage system. The standard allows potential collectors and platforms to validate the URI on the client.</p> <p><strong>Rationale to include many NFT metadata objects, or URIs in one JSON file</strong></p> <p>By including metadata for many NFTs in one JSON file we can eliminate the need for many transactions to set the metadata for multiple NFTs. Given that this file should not change NFT platforms, or explorers can cache the metadata within the file.</p> <p><strong>Rationale for emitting <code>Sealed</code> event</strong></p> <p>Platforms and explorers can use the <code>Sealed</code> event to automatically cache metadata, or update information regarding specified NFTs.</p> <p><strong>Rationale for allowing URIs as values in the JSON file</strong></p> <p>If a token's metadata is very large, or there are many tokens you can save file space by referencing another URI rather than storing the metadata JSON within the top level metadata file.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There is no backwards compatibility with existing standards. This is an extension which could be added to existing NFT standards.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no security considerations related directly to the implementation of this standard.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-04-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nathan Ginneverhttps://github.com/nginnever https://wg-eips.ritovision.com/3440/ <h2 id="simple-summary">Simple Summary</h2> <p>This standard addresses an extension to the <a href="https://wg-eips.ritovision.com/721/">ERC-721 specification</a> by allowing signatures on NFTs representing works of art. This provides improved provenance by creating functionality for an artist to designate an original and signed limited-edition prints of their work.</p> <h2 id="abstract">Abstract</h2> <p>ERC-3440 is an ERC-721 extension specifically designed to make NFTs more robust for works of art. This extends the original ERC-721 spec by providing the ability to designate the original and limited-edition prints with a specialized enumeration extension similar to the <a rel="external" href="https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC721/extensions/ERC721Enumerable.sol">original 721 extension</a> built-in. The key improvement of this extension is allowing artists to designate the limited nature of their prints and provide a signed piece of data that represents their unique signature to a given token Id, much like an artist would sign a print of their work.</p> <h2 id="motivation">Motivation</h2> <p>Currently the link between a NFT and the digital work of art is only enforced in the token metadata stored in the shared <code>tokenURI</code> state of a NFT. While the blockchain provides an immutable record of history back to the origin of an NFT, often the origin is not a key that an artist maintains as closely as they would a hand written signature.</p> <p>An edition is a printed replica of an original piece of art. ERC-721 is not specifically designed to be used for works of art, such as digital art and music. ERC-721 (NFT) was originally created to handle deeds and other contracts. Eventually ERC-721 evolved into gaming tokens, where metadata hosted by servers may be sufficient. This proposal takes the position that we can create a more tangible link between the NFT, digital art, owner, and artist. By making a concise standard for art, it will be easier for an artist to maintain a connection with the Ethereum blockchain as well as their fans that purchase their tokens.</p> <p>The use cases for NFTs have evolved into works of digital art, and there is a need to designate an original NFT and printed editions with signatures in a trustless manner. ERC-721 contracts may or may not be deployed by artists, and currently, the only way to understand that something is uniquely touched by an artist is to display it on 3rd party applications that assume a connection via metadata that exists on servers, external to the blockchain. This proposal helps remove that distance with readily available functionality for artists to sign their work and provides a standard for 3rd party applications to display the uniqueness of a NFT for those that purchase them. The designation of limited-editions combined with immutable signatures, creates a trustlessly enforced link. This signature is accompanied by view functions that allow applications to easily display these signatures and limited-edition prints as evidence of uniqueness by showing that artists specifically used their key to designate the total supply and sign each NFT.</p> <h2 id="specification">Specification</h2> <p>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> <p>ERC-721 compliant contracts MAY implement this ERC for editions to provide a standard method for designating the original and limited-edition prints with signatures from the artist.</p> <p>Implementations of ERC-3440 MUST designate which token Id is the original NFT (defaulted to Id 0), and which token Id is a unique replica. The original print SHOULD be token Id number 0 but MAY be assigned to a different Id. The original print MUST only be designated once. The implementation MUST designate a maximum number of minted editions, after which new Ids MUST NOT be printed / minted.</p> <p>Artists MAY use the signing feature to sign the original or limited edition prints but this is OPTIONAL. A standard message to sign is RECOMMENDED to be simply a hash of the integer of the token Id.</p> <p>Signature messages MUST use the <a rel="external" href="https://eips.ethereum.org/EIPS/eip-712">EIP-712</a> standard.</p> <p>A contract that is compliant with ERC-3440 shall implement the following abstract contract (referred to as ERC3440.sol):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC721/extensions/ERC721URIStorage.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/utils/cryptography/ECDSA.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> ERC721 token with editions extension.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">abstract</span><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> ERC3440</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721URIStorage</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> eip-712</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> EIP712Domain</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> version</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> chainId</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> verifyingContract</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Contents of message to be signed</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Signature</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> verificationAddress</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> ensure the artists signs only address(this) for each piece</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> artist</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> wallet</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> contents</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> type hashes</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> EIP712DOMAIN_TYPEHASH </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span> SIGNATURE_TYPEHASH </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;Signature(address verifyAddress,string artist,address wallet, string contents)&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span> DOMAIN_SEPARATOR</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Optional mapping for signatures</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span> (</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bytes</span><span>)</span><span class="z-storage z-type"> private</span><span> _signatures</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> A view to display the artist&#39;s address</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> artist</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> A view to display the total number of prints created</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span> editionSupply </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> A view to display which ID is the original copy</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span> originalId </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> A signed token event</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Signed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Sets `artist` as the original artist.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `address _artist` the wallet of the signing artist (</span><span class="z-keyword">TODO</span><span class="z-comment"> consider multiple</span></span> <span class="giallo-l"><span class="z-comment"> * signers and contract signers (non-EOA)</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _designateArtist</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _artist</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>artist </span><span class="z-keyword">==</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: the artist has already been set&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If there is no special designation for the artist, set it.</span></span> <span class="giallo-l"><span> artist </span><span class="z-keyword">=</span><span> _artist</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Sets `tokenId as the original print` as the tokenURI of `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `uint256 tokenId` the nft id of the original print</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _designateOriginal</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> artist</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: only the artist may designate originals&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_exists</span><span>(</span><span>_tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: Original query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>originalId </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: Original print has already been designated as a different Id&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If there is no special designation for the original, set it.</span></span> <span class="giallo-l"><span> originalId </span><span class="z-keyword">=</span><span> _tokenId</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Sets total number printed editions of the original as the tokenURI of `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `uint256 _maxEditionSupply` max supply</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _setLimitedEditions</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _maxEditionSupply</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> artist</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: only the artist may designate max supply&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>editionSupply </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: Max number of prints has already been created&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If there is no max supply of prints, set it. Leaving supply at 0 indicates there are no prints of the original</span></span> <span class="giallo-l"><span> editionSupply </span><span class="z-keyword">=</span><span> _maxEditionSupply</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Creates `tokenIds` representing the printed editions.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `string memory _tokenURI` the metadata attached to each nft</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _createEditions</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _tokenURI</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> artist</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: only the artist may create prints&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>editionSupply </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: the edition supply is not set to more than 0&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span>(</span><span class="z-support">uint</span><span> i</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> editionSupply</span><span>;</span><span> i</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _mint</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> i</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setTokenURI</span><span>(</span><span>i</span><span>,</span><span> _tokenURI</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> internal hashing utility </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `Signature memory _message` the signature message struct to be signed</span></span> <span class="giallo-l"><span class="z-comment"> * the address of this contract is enforced in the hashing</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _hash</span><span>(</span><span class="z-storage z-type">Signature</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _message</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;\x19\x01&quot;</span><span>,</span></span> <span class="giallo-l"><span> DOMAIN_SEPARATOR</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span></span> <span class="giallo-l"><span> SIGNATURE_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> _message</span><span>.</span><span>artist</span><span>,</span></span> <span class="giallo-l"><span> _message</span><span>.</span><span>wallet</span><span>,</span></span> <span class="giallo-l"><span> _message</span><span>.</span><span>contents</span></span> <span class="giallo-l"><span> )</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Signs a `tokenId` representing a print.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `uint256 _tokenId` id of the NFT being signed</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `Signature memory _message` the signed message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `bytes memory _signature` signature bytes created off-chain</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` must exist.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {Signed} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _signEdition</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span><span class="z-storage z-type"> Signature</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _message</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _signature</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> virtual</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> artist</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: only the artist may sign their work&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_signatures</span><span>[</span><span>_tokenId</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: this token is already signed&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> digest </span><span class="z-keyword">=</span><span class="z-entity z-name"> hash</span><span>(</span><span>_message</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> recovered </span><span class="z-keyword">=</span><span> ECDSA</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>digest</span><span>,</span><span> _signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>recovered </span><span class="z-keyword">==</span><span> artist</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: artist signature mismatch&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _signatures</span><span>[</span><span>_tokenId</span><span>]</span><span class="z-keyword"> =</span><span> _signature</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Signed</span><span>(</span><span>artist</span><span>,</span><span> _tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> displays a signature from the artist.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `uint256 _tokenId` NFT id to verify isSigned</span></span> <span class="giallo-l"><span class="z-comment"> * @returns `bytes` gets the signature stored on the token</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getSignature</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_signatures</span><span>[</span><span>_tokenId</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span>,</span><span class="z-string"> &quot;ERC721Extensions: no signature exists for this Id&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _signatures</span><span>[</span><span>_tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> returns `true` if the message is signed by the artist.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `Signature memory _message` the message signed by an artist and published elsewhere</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `bytes memory _signature` the signature on the message</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-comment"> `uint _tokenId` id of the token to be verified as being signed</span></span> <span class="giallo-l"><span class="z-comment"> * @returns `bool` true if signed by artist</span></span> <span class="giallo-l"><span class="z-comment"> * The artist may broadcast signature out of band that will verify on the nft</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isSigned</span><span>(</span><span class="z-storage z-type">Signature</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _message</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _signature</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> virtual</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> messageHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> hash</span><span>(</span><span>_message</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _artist </span><span class="z-keyword">=</span><span> ECDSA</span><span>.</span><span class="z-entity z-name">recover</span><span>(</span><span>messageHash</span><span>,</span><span> _signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>_artist </span><span class="z-keyword">==</span><span> artist </span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name"> _equals</span><span>(</span><span>_signatures</span><span>[</span><span>_tokenId</span><span>]</span><span>,</span><span> _signature</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Utility function that checks if two `bytes memory` variables are equal. This is done using hashing,</span></span> <span class="giallo-l"><span class="z-comment"> * which is much more gas efficient then comparing each byte individually.</span></span> <span class="giallo-l"><span class="z-comment"> * Equality means that:</span></span> <span class="giallo-l"><span class="z-comment"> * - &#39;self.length == other.length&#39;</span></span> <span class="giallo-l"><span class="z-comment"> * - For &#39;n&#39; in &#39;[0, self.length)&#39;, &#39;self[n] == other[n]&#39;</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> _equals</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _self</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _other</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> equal</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_self</span><span>.</span><span>length </span><span class="z-keyword">!=</span><span> _other</span><span>.</span><span>length</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> addr</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> addr2</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> len </span><span class="z-keyword">=</span><span> _self</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> addr </span><span class="z-keyword">:=</span><span class="z-entity z-name"> add</span><span>(</span><span>_self</span><span>,</span><span class="z-comment"> /*</span><span class="z-comment">BYTES_HEADER_SIZE</span><span class="z-comment">*/</span><span class="z-constant">32</span><span>)</span></span> <span class="giallo-l"><span> addr2 </span><span class="z-keyword">:=</span><span class="z-entity z-name"> add</span><span>(</span><span>_other</span><span>,</span><span class="z-comment"> /*</span><span class="z-comment">BYTES_HEADER_SIZE</span><span class="z-comment">*/</span><span class="z-constant">32</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> equal </span><span class="z-keyword">:=</span><span class="z-entity z-name"> eq</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span>addr</span><span>,</span><span> len</span><span>)</span><span>,</span><span class="z-support"> keccak256</span><span>(</span><span>addr2</span><span>,</span><span> len</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>A major role of NFTs is to display uniqueness in digital art. Provenance is a desired feature of works of art, and this standard will help improve a NFT by providing a better way to verify uniqueness. Taking this extra step by an artist to explicitly sign tokens provides a better connection between the artists and their work on the blockchain. Artists can now retain their private key and sign messages in the future showing that the same signature is present on a unique NFT.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal combines already available 721 extensions and is backwards compatible with the ERC-721 standard.</p> <h2 id="test-cases">Test Cases</h2> <p>An example implementation including tests can be found <a rel="external" href="https://github.com/nginnever/NFT-editions">here</a>.</p> <h2 id="reference-implementation">Reference Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: MIT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ERC3440.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> ERC721 token with editions extension.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ArtToken</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC3440</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Sets `address artist` as the original artist to the account deploying the NFT.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _name</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _symbol</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _numberOfEditions</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenURI</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _originalId</span></span> <span class="giallo-l"><span> )</span><span class="z-entity z-name"> ERC721</span><span>(</span><span>_name, _symbol) </span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> _designateArtist</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _setLimitedEditions</span><span>(</span><span>_numberOfEditions</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _createEditions</span><span>(</span><span>tokenURI</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _designateOriginal</span><span>(</span><span>_originalId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> DOMAIN_SEPARATOR </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span></span> <span class="giallo-l"><span> EIP712DOMAIN_TYPEHASH</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span class="z-string">&quot;Artist&#39;s Editions&quot;</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-support">bytes</span><span>(</span><span class="z-string">&quot;1&quot;</span><span>)</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Signs a `tokenId` representing a print.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> sign</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span><span class="z-storage z-type"> Signature</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _message</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _signature</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _signEdition</span><span>(</span><span>_tokenId</span><span>,</span><span> _message</span><span>,</span><span> _signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This extension gives an artist the ability to designate an original edition, set the maximum supply of editions as well as print the editions and uses the <code>tokenURI</code> extension to supply a link to the art work. To minimize the risk of an artist changing this value after selling an original piece this function can only happen once. Ensuring that these functions can only happen once provides consistency with uniqueness and verifiability. Due to this, the reference implementation handles these features in the constructor function. An edition may only be signed once, and care should be taken that the edition is signed correctly before release of the token/s.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-04-20T00:00:00+00:00 2026-02-11T14:49:28+00:00 Isaac Ardishttps://github.com/whilei https://wg-eips.ritovision.com/3534/ <h2 id="simple-summary">Simple Summary</h2> <p>Defines a new transaction type with constraints on ancestor block hash, block author, and/or block timestamp.</p> <h2 id="abstract">Abstract</h2> <p>We introduce a new EIP-2718 transaction type with the format <code>0x4 || rlp([chainId, chainContext, nonce, gasPrice, gasLimit, to, value, data, access_list, yParity, senderR, senderS])</code>.</p> <p>This proposed <code>chainContext</code> element adds a constraint on the validity of a transaction to a chain segment meeting the referenced value(s). Four contexts are defined as subclasses of this type:</p> <ul> <li><code>segmentId</code></li> <li><code>eligibleMinerList</code></li> <li><code>ineligibleMinerList</code></li> <li><code>expiry</code></li> </ul> <p>These contexts can be used in arbitrary combinations. Annotated context value combinations are referenced by a composite integer prefix on the annotation.</p> <h2 id="motivation">Motivation</h2> <p>Establish a protocol-based mechanism with which transactions are able to articulate constraints on eligible chain contexts. Generally, these constraints give the consumer (the transactor) an ability to express requirements about the transaction's relationship to blockchain data and its provenance.</p> <ul> <li>Restrict transaction applicability to a chain context that is currently available and reasoned about under some subjective view. <ul> <li>Introduces a way for transactions to describe a dependency on their current view of a chain.</li> </ul> </li> <li>Restrict transaction applicability to a chain context following some foregoing block (and its transactions). <ul> <li>Introduces a way for transactions to describe ancestral dependencies at a "macro" (block) level. Indirectly, this offers a way for a transaction to depend on the presence of another, so long as the dependent transaction is in a different block.</li> </ul> </li> <li>Restrict transaction applicability to blocks benefitting, or <em>not</em> benefitting, a preferred/spurned miner address or addresses. <ul> <li>Introduces an opportunity/market for miners to compete for consumers' transactions; under the status quo, the current miner-transaction processing service is almost perfectly homogeneous from the consumer perspective.</li> </ul> </li> <li>Restrict transaction applicability time span. <ul> <li>Introduces an alternative (to the status quo) way for consumers/transactors to have transactions invalidated/ejected from the transaction pool.</li> </ul> </li> </ul> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <ul> <li><code>FORK_BLOCK_NUMBER</code> <code>TBD</code></li> <li><code>TRANSACTION_TYPE_NUMBER</code> <code>0x4</code>. See EIP-2718.</li> </ul> <p>As of <code>FORK_BLOCK_NUMBER</code>, a new EIP-2718 transaction is introduced with <code>TransactionType</code> <code>TRANSACTION_TYPE_NUMBER</code>.</p> <p>The EIP-2718 <code>TransactionPayload</code> for this transaction is <code>rlp([chainId, chainContext, nonce, gasPrice, gasLimit, to, value, data, access_list, yParity, senderR, senderS])</code>.</p> <p>The EIP-2718 <code>ReceiptPayload</code> for this transaction is <code>rlp([status, cumulativeGasUsed, logsBloom, logs])</code>.</p> <h3 id="definitions">Definitions</h3> <ul> <li><code>chainContext</code>. The transaction is only valid for blockchain data satisfying ALL OF the annotations.</li> <li><code>ANNOTATION_COMPOSITE_PREFIX</code>. A positive integer between <code>1</code> and <code>0xff</code> that represents the set of subclass annotations in the <code>chainContext</code> (<em>ie.</em> <em>which</em> chain context subclasses should the provided values be applied to). This value should be the sum of the subclass' <code>ANNOTATION_PREFIX</code>s.</li> <li><code>ANNOTATION_PREFIX</code>s are defined for Subclasses as octal-derived positive integers, limited to the set <code>2^0,2^1,2^2,2^3,2^4,2^5,2^6,2^7</code>.</li> </ul> <p>The <code>chainContext</code> value should be of the form <code>ANNOTATION_COMPOSITE_PREFIX || [{subclass value}...]</code>, where</p> <ul> <li><code>...</code> means "zero or more of the things to the left," and</li> <li><code>||</code> denotes the byte/byte-array concatenation operator.</li> </ul> <p>The <code>chainContext</code> value should be encoded as <code>ANNOTATION_COMPOSITE_PREFIX || rlp[{subclass value}...]</code>.</p> <h3 id="validation">Validation</h3> <p>The values defined as subclasses below acts as constraints on transaction validity for specific chain contexts. Transactions defining constraints which are not satisfied by their chain context should be rejected as invalid. Blocks containing invalid transactions should be rejected as invalid themselves, per the <em>status quo</em>.</p> <h3 id="subclass-combination">Subclass Combination</h3> <p><code>chainContext</code> values annotating more than one subclass reference should provide those values in the following sequential order:</p> <ol> <li><code>ANCESTOR_ID</code></li> <li><code>ELIGIBLE_MINER_LIST</code></li> <li><code>INELIGIBLE_MINER_LIST</code></li> <li><code>EXPIRY</code></li> </ol> <p>As above, the <code>ANNOTATION_COMPOSITE_PREFIX</code> should be the sum of the designated subclass' <code>ANNOTATION_PREFIX</code>s.</p> <h3 id="subclasses">Subclasses</h3> <ul> <li>An <code>ANNOTATION_PREFIX</code> value is used to represent each of the available context subclasses.</li> </ul> <h4 id="ancestorid"><code>ancestorId</code></h4> <ul> <li><code>ANNOTATION_PREFIX</code> <code>1</code>.</li> <li><code>ANCESTOR_ID</code> <code>bytes</code>. A byte array between 4 and 12 bytes in length.</li> </ul> <p>The <code>ANCESTOR_ID</code> is a reference to a specific block by concatenating the byte representation of a block number and the first 4 bytes of its hash. The block number's should be encoded as a big endian value and should have left-padding 0's removed. The block number value may be omitted in case of reference to the genesis block.</p> <p>The <code>ANCESTOR_ID</code> value should be RLP encoded as a byte array for hashing and transmission.</p> <h4 id="eligibleminerlist"><code>eligibleMinerList</code></h4> <ul> <li><code>ANNOTATION_PREFIX</code> <code>2</code>.</li> <li><code>ELIGIBLE_MINER_LIST</code> <code>[address...]</code>. A list of addresses.</li> <li><code>MAX_ELEMENTS</code> <code>3</code>. The maximum number of addresses that can be provided.</li> </ul> <p>The <code>ELIGIBLE_MINER_LIST</code> value is an array of unique, valid addresses. Any block containing a transaction using this value must have a block beneficiary included in this set.</p> <p>The <code>ELIGIBLE_MINER_LIST</code> value should be of the type <code>[{20 bytes}+]</code>, where <code>+</code> means "one or more of the thing to the left." Non-unique values are not permitted.</p> <p>The <code>ELIGIBLE_MINER_LIST</code> value should be RLP encoded for hashing and transmission.</p> <p>An <code>ELIGIBLE_MINER_LIST</code> value may NOT be provided adjacent to an <code>INELIGIBLE_MINER_LIST</code> value.</p> <h4 id="ineligibleminerlist"><code>ineligibleMinerList</code></h4> <ul> <li><code>ANNOTATION_PREFIX</code> <code>4</code>.</li> <li><code>INELIGIBLE_MINER_LIST</code> <code>[address...]</code>. A list of addresses.</li> <li><code>MAX_ELEMENTS</code> <code>3</code>. The maximum number of addresses that can be provided.</li> </ul> <p>The <code>INELIGIBLE_MINER_LIST</code> value is an array of unique, valid addresses. Any block containing a transaction using this value must not have a block beneficiary included in this set.</p> <p>The <code>INELIGIBLE_MINER_LIST</code> value should be of the type <code>[{20 bytes}+]</code>, where <code>+</code> means "one or more of the thing to the left." Non-unique values are not permitted.</p> <p>The <code>INELIGIBLE_MINER_LIST</code> value should be RLP encoded for hashing and transmission.</p> <p>An <code>INELIGIBLE_MINER_LIST</code> value may NOT be provided adjacent to an <code>ELIGIBLE_MINER_LIST</code> value.</p> <h4 id="expiry"><code>expiry</code></h4> <ul> <li><code>ANNOTATION_PREFIX</code> <code>8</code>.</li> <li><code>EXPIRY</code> <code>integer</code>. A positive, unsigned scalar.</li> </ul> <p>The <code>EXPIRY</code> value is a scalar equal to the maximum valid block <code>timestamp</code> for a block including this transaction.</p> <p>The <code>EXPIRY</code> value should be RLP encoded as an integer for hashing and transmission.</p> <h2 id="rationale">Rationale</h2> <h3 id="subclasses-1">Subclasses</h3> <p>Subclasses are defined with a high level of conceptual independence, and can be modified and/or extended independently from this EIP. Their specification definitions allow arbitrary mutual (<code>AND</code>) combinations.</p> <p>This design is intended to form a proposal which offers a concrete set of specifics while doing so with enough flexibility for extension or modification later.</p> <h4 id="annotation-prefix"><code>ANNOTATION_PREFIX</code></h4> <p><code>ANNOTATION_PREFIX</code> values' use of octal-derived values, ie. <code>1, 2, 4, 8, 16, 32, 64, 128</code>, follows a conventional pattern of representing combinations from a limited set uniquely and succinctly, eg. Unix-style file permissions. This EIP defines four of the eight possible context subclasses; this seems to leave plenty of room for future growth in this direction if required. If this limit is met or exceeded, doing so will require a hard fork <em>de facto</em> (by virtue of making consensus protocol facing changes to transaction validation schemes), so revising this scheme as needed should be only incidental and trivial.</p> <h4 id="ancestorid-1"><code>ancestorId</code></h4> <p>Constrains the validity of a transaction by referencing a prior canonical block by number and hash. The transaction is only valid when included in a block which has the annotated block as an ancestor.</p> <p>Practically, the "designated allowable chain segment" can be understood as the segment of blocks from <code>0..ancestorId</code> inclusive.</p> <h5 id="redundancy-to-chainid">Redundancy to <code>chainId</code></h5> <p>This pattern can be understood as a correlate of <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>'s <code>chainId</code> specification. EIP155 defines the restriction of transactions between chains; limiting the applicability of any EIP-155 transaction to a chain with the annotated ChainID. <code>ancestorId</code> further restricts transaction application to one subsection ("segment") of one chain.</p> <p>From this constraint hierarchy, we note that an implementation of <code>ancestorId</code> can make <code>chainId</code> conceptually redundant.</p> <h5 id="so-why-keep-chainid">So why keep <code>chainId</code>?</h5> <p><code>chainId</code> is maintained as an invariant because:</p> <ul> <li>The use of the transaction type proposed by this EIP is optional, implying the continued necessity of <code>chainId</code> in the protocol infrastructure and tooling for legacy and other transaction types.</li> <li>The presence of <code>ancestorId</code> in the transaction type proposed by this EIP is optional. If the value is not filled by an RCC transaction, the demand for <code>chainId</code> remains.</li> <li>A <code>chainId</code> value is not necessarily redundant to <code>ancestorId</code>, namely in cases where forks result in living chains. For example, an <code>ancestorId</code> reference to block <code>1_919_999</code> would be ambiguous between Ethereum and Ethereum Classic.</li> <li>It would be possible to specify the omission of <code>chainId</code> in case of <code>ancestorId</code>'s use. This would add infrastructural complexity for the sake of removing the few bytes <code>chainId</code> typically requires; we do not consider this trade-off worth making. <ul> <li><code>chainId</code> is used as the <code>v</code> value (of <code>v,r,s</code>) in the transaction signing scheme; removing or modifying this incurs complexity at a level below encoded transaction fields, demanding additional infrastructural complexity for implementation.</li> </ul> </li> <li>The proposed design for <code>ancestorId</code> does not provide perfect precision (at the benefit of byte-size savings). In the small chance that the value is ambiguous, the <code>chainId</code> maintains an infallible guarantee for a transaction's chain specificity.</li> </ul> <h4 id="eligibleminerlist-1"><code>eligibleMinerList</code></h4> <p>The transaction is only valid when included in a block having an <code>etherbase</code> contained in the annotated list of addresses. The use of "whitelist" (<code>eligibleMinerList</code>) in conjunction with a "blacklist" (<code>ineligibleMinerList</code>) is logically inconsistent; their conjunction is not allowed.</p> <p>A <code>MAX_ELEMENTS</code> limit of <code>3</code> is chosen to balance the interests of limiting the potential size of transactions, and to provide a sufficient level of articulation for the user. At the time of writing, the top 3 miners of Ethereum (by block, measured by known public addresses) account for 52% of all blocks produced.</p> <h4 id="ineligibleminerlist-1"><code>ineligibleMinerList</code></h4> <p>The transaction is only valid when included in a block having an <code>etherbase</code> <em>not</em> contained in the annotated list of addresses. The use of "blacklist" (<code>ineligibleMinerList</code>) in conjunction with a "whitelist" (<code>eligibleMinerList</code>) is logically inconsistent; their conjunction is not allowed.</p> <p>A <code>MAX_ELEMENTS</code> limit of <code>3</code> is chosen to balance the interests of limiting the potential size of transactions, and to provide a sufficient level of articulation for the user. At the time of writing, the top 3 miners of Ethereum (by block, measured by known public addresses) account for 52% of all blocks produced.</p> <h4 id="expiry-1"><code>expiry</code></h4> <p>The transaction is only valid when included in a block having a <code>timestamp</code> less than the value annotated. A positive integer is used because that corresponds to the specified type of block <code>timestamp</code> header values.</p> <h3 id="subclass-combination-1">Subclass Combination</h3> <p>Since subclasses use octal-based values for <code>ANNOTATION_PREFIX</code>, they can be distinguishably combined as sums, provided as we assume annotation cardinality (ie ordering). For example:</p> <ul> <li><code>ANNOTATION_PREFIX</code> <code>1</code> signals <code>ancestorId</code> exclusively.</li> <li><code>ANNOTATION_PREFIX</code> <code>2</code> signals <code>eligibleMinerList</code> exclusively.</li> <li><code>ANNOTATION_PREFIX</code> <code>4</code> signals <code>ineligibleMinerList</code> exclusively.</li> <li><code>ANNOTATION_PREFIX</code> <code>8</code> signals <code>expiry</code> exclusively.</li> <li><code>ANNOTATION_PREFIX</code> <code>1+2=3</code> combines <code>ancestorId</code> and <code>eligibleMinerList</code>.</li> <li><code>ANNOTATION_PREFIX</code> <code>1+4=5</code> combines <code>ancestorId</code> and <code>ineligibleMinerList</code>.</li> <li><code>ANNOTATION_PREFIX</code> <code>1+8=9</code> combines <code>ancestorId</code> and <code>expiry</code>.</li> <li><code>ANNOTATION_PREFIX</code> <code>1+2+8=11</code> combines <code>ancestorId</code> and <code>eligibleMinerList</code> and <code>expiry</code>.</li> <li><code>ANNOTATION_PREFIX</code> <code>1+4+8=13</code> combines <code>ancestorId</code> and <code>ineligibleMinerList</code> and <code>expiry</code>.</li> <li><code>ANNOTATION_PREFIX</code> <code>2+4=6</code> is NOT PERMITTED. It would combine <code>eligibleMinerList</code> and <code>ineligibleMinerList</code>.</li> <li><code>ANNOTATION_PREFIX</code> <code>1+2+4+8=15</code> is NOT PERMITTED. It would combine <code>eligibleMinerList</code> and <code>ineligibleMinerList</code> (and <code>ancestorId</code> and <code>expiry</code>).</li> </ul> <p>Since ordering is defined and demanded for multiple values, annotated references remain distinguishable. For example:</p> <ul> <li><code>chainContext</code> <code>3[e4e1c0e78b1ec3,[Df7D7e053933b5cC24372f878c90E62dADAD5d42]]</code> - Transaction can only be included in a block having a canonical ancestor block numbered <code>15_000_000</code> and with a hash prefixed with the bytes <code>e78b1ec3</code>, and if the containing block uses <code>Df7D7e053933b5cC24372f878c90E62dADAD5d42</code> as the beneficiary.</li> <li><code>chainContext</code> <code>10[[Df7D7e053933b5cC24372f878c90E62dADAD5d42],1619008030]</code> - Transaction can only be included in a block naming <code>Df7D7e053933b5cC24372f878c90E62dADAD5d42</code> as the <code>etherbase</code> beneficiary, and which has a timestamp greater than <code>1619008030</code> (Wed Apr 21 07:27:10 CDT 2021).</li> </ul> <h3 id="eip-2930-inheritance">EIP-2930 Inheritance</h3> <p>The <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2930">EIP-2930 Optional Access List Type Transaction</a> is used as an assumed "base" transaction type for this proposal. However, this is NOT a conceptual dependency; the included <code>accessList</code> portion of this proposal (the only differential from post-EIP-155 legacy transaction fields) can readily be removed. Standing on the shoulders of EIP-2930 is only intended to support and further the adoption of next-generation transactions.</p> <h3 id="signature-target">Signature target</h3> <p>The signature signs over the transaction type as well as the transaction data. This is done to ensure that the transaction cannot be “re-interpreted” as a transaction of a different type.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no known backward compatibility issues.</p> <h2 id="test-cases">Test Cases</h2> <table><thead><tr><th>Segment ID</th><th>Block Number</th><th>Canonical Block Hash</th></tr></thead><tbody> <tr><td><code>e78b1ec3</code></td><td><code>0</code></td><td><code>0xe78b1ec31bcb535548ce4b6ef384deccad1e7dc599817b65ab5124eeaaee3e58</code></td></tr> <tr><td><code>01e78b1ec3</code></td><td><code>1</code></td><td><code>0xe78b1ec31bcb535548ce4b6ef384deccad1e7dc599817b65ab5124eeaaee3e58</code></td></tr> <tr><td><code>e4e1c0e78b1ec3</code></td><td><code>15_000_000</code></td><td><code>0xe78b1ec31bcb535548ce4b6ef384deccad1e7dc599817b65ab5124eeaaee3e58</code></td></tr> <tr><td><code>e8d4a50fffe78b1ec3</code></td><td><code>999_999_999_999</code></td><td><code>0xe78b1ec31bcb535548ce4b6ef384deccad1e7dc599817b65ab5124eeaaee3e58</code></td></tr> <tr><td><code>7fffffffffffffffe78b1ec3</code></td><td><code>9223372036854775807</code></td><td><code>0xe78b1ec31bcb535548ce4b6ef384deccad1e7dc599817b65ab5124eeaaee3e58</code></td></tr> </tbody></table> <p>Further test cases, TODO.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="why-4-bytes-of-a-block-hash-is-safe-enough-for-the-ancestorid">Why 4 bytes of a block hash is "safe enough" for the <code>ancestorId</code></h3> <p><strong>TL;DR</strong>: The chance of an ineffectual <code>ancestorId</code> is about 1 in between ~4 billion and ~40 billion, with the greater chance for intentional duplication scenarios, eg. malicious reorgs.</p> <p><strong>If a collision <em>does</em> happen</strong>, that means the transaction will be valid on both segments (as is the case under the status quo).</p> <p>Four bytes, instead of the whole hash (32 bytes), was chosen only to reduce the amount of information required to cross the wire to implement this value. Using the whole hash would result in a "perfectly safe" implementation, and every additional byte reduces the chance of collision exponentially.</p> <p>The goal of the <code>ancestorId</code> is to disambiguate one chain segment from another, and in doing so, enable a transaction to define with adequate precision which chain it needs to be on. When a transaction's <code>ancestorId</code> references a block, we want to be pretty sure that that reference won't get confused with a different block than the one the author of the transaction had in mind.</p> <p>We assume the trait of collision resistance is uniformly applicable to all possible subsets of the block hash value, so our preference of using the <em>first</em> 4 bytes is arbitrary and functionally equivalent to any other subset of equal length.</p> <p>For the sake of legibility and accessibility, the following arguments will reference the hex representation of 4 bytes, which is 8 characters in length, eg. <code>e78b1ec3</code>.</p> <p>The chance of a colliding <code>ancestorId</code> is <code>1/(16^8=4_294_967_296)</code> times whatever we take the chance of the existence of an equivalently-numbered block (on an alternative chain) to be. Assuming a generous ballpark chance of 10% (<code>1/10</code>) for any given block having a public uncle, this yields <code>(1/(16^8=4_294_967_296) * 1/10</code>. Note that this ballpark assumes "normal" chain and network behavior. In the case of an enduring competing chain segment, this value rises to 100% (<code>1</code>).</p> <h3 id="eligibleminerlist-2"><code>eligibleMinerList</code></h3> <p>Miners who do not find themselves listed in an annotated <code>eligibleMinerList</code> should be expected to immediately remove the transaction from their transaction pool.</p> <p>In a pessimistic outlook, we should also expect that these ineligible nodes would not offer rebroadcasts of these transactions, potentially impacting the distribution (and availability) of the transactions to their intended miners. On the other hand, miners are incentivized to make themselves available for reception of such transactions, and there are many ways this is feasible both on-network and off-.</p> <p>The author of a transaction using the <code>eligibleMinerList</code> must assume that the "general availability" of the blockchain state database for such a transaction will be lower than a nonrestrictive transaction (since only a subset of miners will be able to process the transaction).</p> <p>A final consideration is the economics of a whitelisted miner concerning the processing order of transactions in which they are whitelisted and those without whitelists. Transactions without whitelists would appear at first glean to be more competitive, and thus should be processed with priority. However, miners following such a strategy may find their reputation diminished, and, in the worst case, see the assertive preferences of transaction authors shift to their competitors and beyond their reach.</p> <h3 id="ineligibleminerlist-2"><code>ineligibleMinerList</code></h3> <p>In addition to the concerns and arguments presented by <code>eligibleMinerList</code> above, there is a unique concern for <code>ineligibleMinerList</code>: in order for a miner entity to avoid ineligibility by a blacklist, they only need to use an alternative adhoc address as the block beneficiary. In principle, this is ineluctable.</p> <p>However, there are associated costs to the "dodging" miner that should be considered.</p> <ul> <li>The creation of an account requires time and energy. But indeed, this work can be done at any convenient time and circumstance. Probably marginal, but non-zero.</li> <li>The transfer of funds from multiple accounts requires a commensurate number of transactions. Block rewards are applied after transactions are processed, so the miner is unable to simultaneously shift funds from an adhoc account to a target account in the same block they mine (which would otherwise be a "free" transaction).</li> <li>In using an adhoc address to dodge a blacklist, the miner may also cause their ineligibility from contemporary whitelist transactions.</li> </ul> <h3 id="validation-costs">Validation costs</h3> <p>Miner lists and expiry depend on easily cached and contextually available conditions (ie. the containing block header). The infrastructural overhead costs for enforcing these validations are expected to be nominal.</p> <p>Validation of <code>ancestorId</code> demands the assertion of a positive database hit by block number (thereby cross-referencing a stored block's hash). This necessary lookup can be (and maybe already is) cached, but we must expect less than 100% hits on cached values, since the lookup value is arbitrary. With that in mind, however, the value provided to a transaction using a deep <code>ancestorId</code> is increasingly marginal, so we should expect most transactions using this field to use a relatively small set of common, shallow, cache-friendly values.</p> <h3 id="transaction-size-increase">Transaction size increase</h3> <p>The proposed additional fields potentially increase transaction size. The proposed fields are not associated with any gas costs, establishing no protocol-defined economic mitigation for potential spam. However, transactions which are considered by a miner to be undesirable can be simply dropped from the transaction pool and ignored.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waved via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-04-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alexihttps://github.com/alexi https://wg-eips.ritovision.com/5050/

Action messaging and discovery protocol for interactions on and between NFTs

<h2 id="abstract">Abstract</h2> <p>This standard defines a broadly applicable action messaging protocol for the transmission of user-initiated actions between tokens. Modular statefulness is achieved with optional state controller contracts (i.e. environments) that manage shared state, and provide arbitration and settlement of the action process.</p> <h2 id="motivation">Motivation</h2> <p>Tokenized item standards such as <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> and <a href="https://wg-eips.ritovision.com/1155/">EIP-1155</a> serve as the objects of the Ethereum computing environment. A growing number of projects are seeking to build interactivity and <em>"digital physics"</em> into NFTs, especially in the contexts of gaming and decentralized identity. A standard action messaging protocol will allow this physics layer to be developed in the same open, Ethereum-native way as the objects they operate on.</p> <p>The messaging protocol outlined defines how an action is initiated and transmitted between tokens and (optional) shared state environments. It is paired with a common interface for defining functionality that allows off-chain services to aggregate and query supported contracts for functionality and interoperability; creating a discoverable, human-readable network of interactive token contracts. Not only can contracts that implement this standard be automatically discovered by such services, their <em>policies for interaction</em> can be as well. This allows clients to easily discover compatible senders and receivers, and allowed actions.</p> <p>Aggregators can also parse action event logs to derive analytics on new action types, trending/popular/new interactive contracts, which token and state contract pairs users are likely to interact with, and other discovery tools to facilitate interaction.</p> <h3 id="benefits">Benefits</h3> <ol> <li>Make interactive token contracts <strong>discoverable and usable</strong> by applications</li> <li>Create a decentralized "digital physics" layer for gaming and other applications</li> <li>Provide developers a simple solution with viable validity guarantees to make dynamic NFTs and other tokens</li> <li>Allow for generalized action bridges to transmit actions between chains (enabling actions on L1 assets to be saved to L2s, L1 assets to interact with L2 assets, and L2 actions to be "rolled-up"/finalized on L1).</li> </ol> <h2 id="specification">Specification</h2> <p>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> <p>Smart contracts implementing this EIP standard MUST implement the <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> supportsInterface function and MUST return the constant value <code>true</code> if the <code>IERC5050Sender</code> interface ID <code>0xc8c6c9f3</code> and/or the <code>IERC5050Receiver</code> interface ID <code>0x1a3f02f4</code> is passed through the <code>interfaceID</code> argument (depending on which interface(s) the contract implements).</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> The address of the interactive object</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The token that is interacting (optional)</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Object</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _address</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> _tokenId</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> selector</span><span class="z-comment"> The bytes4(keccack256()) encoding of the action string</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> user</span><span class="z-comment"> The address of the sender</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> from</span><span class="z-comment"> The initiating object</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> to</span><span class="z-comment"> The receiving object</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> state</span><span class="z-comment"> The state controller contract</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> data</span><span class="z-comment"> Additional data with no specified format</span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Action</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span> selector</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> user</span><span>;</span></span> <span class="giallo-l"><span> Object from</span><span>;</span></span> <span class="giallo-l"><span> Object to</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> state</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> data</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-5050 Interactive NFTs with Modular Environments</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5050Sender</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Send an action to the target address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The action&#39;s `fromContract` is automatically set to `address(this)`,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and the `from` parameter is set to `msg.sender`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> action</span><span class="z-comment"> The action to send</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> sendAction</span><span>(</span><span class="z-storage z-type">Action</span><span class="z-storage z-type"> memory</span><span class="z-variable"> action</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Check if an action is valid based on its hash and nonce</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> When an action passes through all three possible contracts</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> (`fromContract`, `to`, and `state`) the `state` contract validates the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> action with the initiating `fromContract` using a nonced action hash.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This hash is calculated and saved to storage on the `fromContract` before</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> action handling is initiated. The `state` contract calculates the hash</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and verifies it and nonce with the `fromContract`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _hash</span><span class="z-comment"> The hash to validate</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _nonce</span><span class="z-comment"> The nonce to validate</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isValid</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _hash</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _nonce</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve list of actions that can be sent.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Intended for use by off-chain applications to query compatible contracts,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and to advertise functionality in human-readable form.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> sendableActions</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Change or reaffirm the approved address for an action</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The zero address indicates there is no approved address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws unless `msg.sender` is the `_account`, or an authorized</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> operator of the `_account`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _account</span><span class="z-comment"> The account of the account-action pair to approve</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _action</span><span class="z-comment"> The action of the account-action pair to approve</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _approved</span><span class="z-comment"> The new approved account-action controller</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approveForAction</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _account</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-variable z-parameter z-function"> _action</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _approved</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Enable or disable approval for a third party (&quot;operator&quot;) to conduct</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> all actions on behalf of `msg.sender`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emits the ApprovalForAll event. The contract MUST allow</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> an unbounded number of operators per owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> Address to add to the set of authorized operators</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _approved</span><span class="z-comment"> True if the operator is approved, false to revoke approval</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setApprovalForAllActions</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _approved</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the approved address for an account-action pair</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if `_tokenId` is not a valid NFT.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _account</span><span class="z-comment"> The account of the account-action to find the approved address for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _action</span><span class="z-comment"> The action of the account-action to find the approved address for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> approved address for this account-action, or the zero address if</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> there is none</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getApprovedForAction</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _account</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable z-parameter z-function"> _action</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Query if an address is an authorized operator for another address</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _account</span><span class="z-comment"> The address on whose behalf actions are performed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> The address that acts on behalf of the account</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if `_operator` is an approved operator for `_account`, false otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isApprovedForAllActions</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _account</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when an action is sent (`sendAction()`)</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> SendAction</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> name</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> _from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _fromContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _toTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> _state</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> _data</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when the approved address for an account-action pair</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> is </span><span class="z-keyword">changed</span><span class="z-comment"> or reaffirmed. The zero address indicates there is no</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> approved address.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ApprovalForAction</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _account</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _action</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _approved</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when an operator is enabled or disabled for an account.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The operator can conduct all actions on behalf of the account.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ApprovalForAllActions</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _account</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _operator</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> _approved</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5050Receiver</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Handle an action</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Both the `to` contract and `state` contract are called via</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `onActionReceived()`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> action</span><span class="z-comment"> The action to handle</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> onActionReceived</span><span>(</span><span class="z-storage z-type">Action</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> action</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _nonce</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieve list of actions that can be received.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Intended for use by off-chain applications to query compatible contracts,</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and to advertise functionality in human-readable form.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> receivableActions</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a valid action is received.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ActionReceived</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> name</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> _from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _fromContract</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _tokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> _toTokenId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> _state</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> _data</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="action-naming">Action Naming</h3> <p>Actions SHOULD use dot-separation for namespacing (e.g. <code>"spells.cast"</code> specifies the <code>"cast"</code> action with namespace <code>"spells"</code>), and arrow-separation for sequence specification (e.g. <code>"settle&gt;build"</code> indicating <code>"settle"</code> must be received before <code>"build"</code>).</p> <h3 id="how-state-contracts-work">How State Contracts Work</h3> <p>Actions do not require that a state contract be used. Actions can be transmitted from one token contract (<code>Object</code>) to another, or from a user to a single token contract. In these cases, the sending and receiving contracts each control their own state.</p> <p>State contracts allow arbitrary senders and receivers to share a user-specified state environment. Each <code>Object</code> MAY define its own action handling, which MAY include reading from the state contract during, but the action MUST be finalized by the state contract. This means the state contract serves as ground truth.</p> <p>The intended workflow is for state contracts to define stateful game environments, typically with a custom <code>IState</code> interface for use by other contracts. <code>Objects</code> register with state contracts to initialize their state. Then, users commit actions using a specific state contract to make things happen in the game.</p> <p>The modularity of state contracts allows multiple copies of the same or similar "game environment" to be created and swapped in or out by the client. There are many ways this modularity can be used:</p> <ul> <li>Aggregator services can analyze action events to determine likely state contracts for a given sender/receiver</li> <li>Sender/receiver contracts can require a specific state contract</li> <li>Sender/receiver contracts can allow any state contract, but set a default. This is important for NFTs that change their render based on state. This default can also be configurable by the token holder.</li> <li>State contracts can be bridges to state contracts on another chain, allowing for L1-verification, L2-storage usage pattern (validate action with layer-1 assets, save on l2 where storage is cheaper).</li> </ul> <h4 id="example">Example</h4> <p>State Contract <code>FightGame</code> defines a fighting game environment. Token holders call <code>FightGame.register(contract, tokenId)</code> to randomly initialize their stats (strength/hp/etc.). An account which holds a registered token A of contract <code>Fighters</code>, calls <code>Fighters.sendAction(AttackAction)</code>, specifying token A from <code>Fighters</code> as the sender, token B from <code>Pacifists</code> contract as the receiver, and <code>FightGame</code> as the state contract.</p> <p>The action is passed to token B, which may handle the action in whatever way it wants before passing the action to the <code>FightGame</code> state contract. The state contract can verify the stored action hash with the <code>Fighters</code> contract to validate the action is authentic before updating the stats if the tokens, dealing damage to token B.</p> <p>Tokens A and B may update their metadata based on stats in the <code>FightGame</code> state contract, or based on their own stored data updated in response to sending/receiving actions.</p> <h3 id="extensions">Extensions</h3> <h4 id="interactive">Interactive</h4> <p>Some contracts may have custom user interfaces that facilitate interaction.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-5050 Interactive NFTs with Modular Environments</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC5050Interactive</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> interfaceURI</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable z-parameter z-function"> _action</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="action-proxies">Action Proxies</h4> <p>Action proxies can be used to support backwards compatibility with non-upgradeable contracts, and potentially for cross-chain action bridging.</p> <p>They can be implemented using a modified version of <a href="https://wg-eips.ritovision.com/1820/#erc-1820-registry-smart-contract">EIP-1820</a> that allows <a href="https://wg-eips.ritovision.com/173/">EIP-173</a> contract owners to call <code>setManager()</code>.</p> <h4 id="controllable">Controllable</h4> <p>Users of this standard may want to allow trusted contracts to control the action process to provide security guarantees, and support action bridging. Controllers step through the action chain, calling each contract individually in sequence.</p> <p>Contracts that support Controllers SHOULD ignore require/revert statements related to action verification, and MUST NOT pass the action to the next contract in the chain.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-5050 Action Controller</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IControllable</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Enable or disable approval for a third party (&quot;controller&quot;) to force</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> handling of a given action without performing EIP-5050 validity checks.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emits the ControllerApproval event. The contract MUST allow</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> an unbounded number of controllers per action.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _controller</span><span class="z-comment"> Address to add to the set of authorized controllers</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _action</span><span class="z-comment"> Selector of the action for which the controller is approved / disapproved</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _approved</span><span class="z-comment"> True if the controller is approved, false to revoke approval</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setControllerApproval</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _controller</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable z-parameter z-function"> _action</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _approved</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Enable or disable approval for a third party (&quot;controller&quot;) to force</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> action handling without performing EIP-5050 validity checks. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Emits the ControllerApproval event. The contract MUST allow</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> an unbounded number of controllers per action.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _controller</span><span class="z-comment"> Address to add to the set of authorized controllers</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _approved</span><span class="z-comment"> True if the controller is approved, false to revoke approval</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setControllerApprovalForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _controller</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _approved</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Query if an address is an authorized controller for a given action.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _controller</span><span class="z-comment"> The trusted third party address that can force action handling</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _action</span><span class="z-comment"> The action selector to query against</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if `_controller` is an approved operator for `_account`, false otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isApprovedController</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _controller</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable z-parameter z-function"> _action</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a controller is enabled or disabled for the given</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> action. The controller can force `action` handling on the emitting contract, </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> bypassing the standard EIP-5050 validity checks.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ControllerApproval</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _controller</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _action</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> _approved</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a controller is enabled or disabled for all actions.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Disabling all action approval for a controller does not override explicit action</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> action approvals. Controller&#39;s approved for all actions can force action handling </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> on the emitting contract for any action.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ControllerApprovalForAll</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _controller</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> _approved</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="metadata-update">Metadata Update</h4> <p>Interactive NFTs are likely to update their metadata in response to certain actions and developers MAY want to implement <a href="https://wg-eips.ritovision.com/4906/">EIP-4906</a> event emitters.</p> <h2 id="rationale">Rationale</h2> <p>The critical features of this interactive token standard are that it 1) creates a common way to define, advertise, and conduct object interaction, 2) enables optional, brokered statefulness with <em>useful</em> validity assurances at minimum gas overhead, 3) is easy for developers to implement, and 4) is easy for end-users to use.</p> <h3 id="action-names-selectors">Action Names &amp; Selectors</h3> <p>Actions are advertised using human-readable strings, and processed using function selectors (<code>bytes4(keccack256(action_key))</code>). Human-readable strings allow end-users to easily interpret functionality, while function selectors allow efficient comparison operations on arbitrarily long action keys. This scheme also allows for simple namespacing and sequence specification.</p> <p>Off-chain services can easily convert the strings to <code>bytes4</code> selector encoding when interacting with contracts implementing this EIP or parsing <code>SendAction</code> and <code>ActionReceived</code> event logs.</p> <h3 id="validation">Validation</h3> <p>Validation of the initiating contract via a hash of the action data was satisfactory to nearly everyone surveyed and was the most gas efficient verification solution explored. We recognize that this solution does not allow the receiving and state contracts to validate the initiating <code>user</code> account beyond using <code>tx.origin</code>, which is vulnerable to phishing attacks.</p> <p>We considered using a signed message to validate user-intiation, but this approach had two major drawbacks:</p> <ol> <li><strong>UX</strong> users would be required to perform two steps to commit each action (sign the message, and send the transaction)</li> <li><strong>Gas</strong> performing signature verification is computationally expensive</li> </ol> <p>Most importantly, the consensus among the developers surveyed is that strict user validation is not necessary because the concern is only that malicious initiating contracts will phish users to commit actions <em>with</em> the malicious contract's assets. <strong>This protocol treats the initiating contract's token as the prime mover, not the user.</strong> Anyone can tweet at Bill Gates. Any token can send an action to another token. Which actions are accepted, and how they are handled is left up to the contracts. High-value actions can be reputation-gated via state contracts, or access-gated with allow/disallow-lists. <a href="https://wg-eips.ritovision.com/5050/#controllable"><code>Controllable</code></a> contracts can also be used via trusted controllers as an alternative to action chaining.</p> <p><em>Alternatives considered: action transmitted as a signed message, action saved to reusable storage slot on initiating contract</em></p> <h3 id="state-contracts">State Contracts</h3> <p>Moving state logic into dedicated, parameterized contracts makes state an action primitive and prevents state management from being obscured within the contracts. Specifically, it allows users to decide which "environment" to commit the action in, and allows the initiating and receiving contracts to share state data without requiring them to communicate.</p> <p>The specifics of state contract interfaces are outside the scope of this standard, and are intended to be purpose-built for unique interactive environments.</p> <h3 id="gas-and-complexity-regarding-action-chaining">Gas and Complexity (regarding action chaining)</h3> <p>Action handling within each contract can be arbitrarily complex, and there is no way to eliminate the possibility that certain contract interactions will run out of gas. However, developers SHOULD make every effort to minimize gas usage in their action handler methods, and avoid the use of for-loops.</p> <p><em>Alternatives considered: multi-request action chains that push-pull from one contract to the next.</em></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Non-upgradeable, already deployed token contracts will not be compatible with this standard unless a proxy registry extension is used.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>A reference implementation is included in <code>../assets/eip-5050</code> with a simple stateless example <a href="https://wg-eips.ritovision.com/5050/./assets/ExampleToken2Token.sol"><code>ExampleToken2Token.sol</code></a>, and a stateful example <a href="https://wg-eips.ritovision.com/5050/./assets/ExampleStateContract.sol"><code>ExampleStateContract.sol</code></a></p> <h2 id="security-considerations">Security Considerations</h2> <p>The core security consideration of this protocol is action validation. Actions are passed from one contract to another, meaning it is not possible for the receiving contract to natively verify that the caller of the initiating contract matches the <code>action.from</code> address. One of the most important contributions of this protocol is that it provides an alternative to using signed messages, which require users to perform two operations for every action committed.</p> <p>As discussed in <a href="https://wg-eips.ritovision.com/5050/#validation">Validation</a>, this is viable because the initiating contract / token is treated as the prime mover, not the user.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-04-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Papageorgiouhttps://github.com/alex-ppg https://wg-eips.ritovision.com/3508/ <h2 id="simple-summary">Simple Summary</h2> <p>Provide access to original transaction data.</p> <h2 id="abstract">Abstract</h2> <p>This EIP introduces the following three EVM instructions: <code>ORIGINDATALOAD</code>, <code>ORIGINDATASIZE</code>, and <code>ORIGINDATACOPY</code>.</p> <p>These three instructions are meant to provide access to the original transaction's <code>data</code> payload, enabling a gas-efficient way of accessing large data payloads in cross-contract calls.</p> <h2 id="motivation">Motivation</h2> <p>As the Ethereum development scene matures, more ambitious and complex features are introduced into smart contracts more often than not requiring the utilization of complex and at times large data structures. Given the inherent limits of the EVM, however, transporting large data structures in between contracts is a costly task that can at times lead to even futile scenarios whereby the gas consumption of such an operation is impossible to execute within the gas limit bounds as well as without sacrificing a large chunk of ETH to facilitate its gas cost.</p> <p>The purpose of this EIP is to render these features viable by introducing a way via which multi-contract systems are able to access the same in-memory data source without necessarily transmitting the full payload between them.</p> <p>This EIP enables elaborate smart contract features to become part of a larger call-chain by efficiently reading data from the original transaction payload rather than requiring the data to be passed in as call-level data. Its inclusion will mainly benefit advanced trustless schemes to manifest, such as efficient verification of Merkle Patricia trees validating the storage value of a particular Ethereum block or EVM-based layer 2 solutions.</p> <p>A side-effect of this change is that smart contract systems relying entirely on origin data inherently guarantee that the data they receive has not been malformed by an intermediate smart contract call.</p> <h2 id="specification">Specification</h2> <h3 id="origindataload-0x47-origindatasize-0x48-and-origindatacopy-0x49">ORIGINDATALOAD (<code>0x47</code>), ORIGINDATASIZE (<code>0x48</code>) and ORIGINDATACOPY (<code>0x49</code>)</h3> <p>These instructions are meant to operate similarly to their call-prefixed counterparts with the exception that they instead operate on the original <code>data</code> of a transaction instead of the current call's data. In detail:</p> <ul> <li>ORIGINDATALOAD (<code>0x47</code>) performs similarly to CALLDATALOAD (<code>0x35</code>)</li> <li>ORIGINDATASIZE (<code>0x48</code>) performs similarly to CALLDATASIZE (<code>0x36</code>)</li> <li>ORIGINDATACOPY (<code>0x49</code>) performs similarly to CALLDATACOPY (<code>0x37</code>)</li> </ul> <p>As the data is retrieved once again from the execution environment, the costs for the three instructions will be <code>G_verylow</code>, <code>G_base</code> and <code>G_base + G_verylow * (number of words copied, rounded up)</code> respectively.</p> <p>The transaction data the <code>ORIGINDATA*</code> opcodes operate on will be equivalent to the <code>calldata</code> specified in the <code>args*</code> parameter to the nearest <code>AUTHCALL</code> (<code>0xf7</code>) up the stack. If there is no <code>AUTHCALL</code> in the stack then <code>ORIGINDATA*</code> will operate on the transaction's original <code>data</code> field.</p> <p>This interaction ensures full compatibility with <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a> and ensures that no form of discrimination is introduced back into the system by this EIP e.g. by contracts entirely relying on <code>ORIGINDATA*</code> and thus allowing only EOAs to supply data to them.</p> <h2 id="rationale">Rationale</h2> <h3 id="authcall-0xf7-interaction">AUTHCALL (<code>0xf7</code>) Interaction</h3> <p>The <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a> that will be part of the London fork has introduced a new call instruction called <code>AUTHCALL</code> (<code>0xf7</code>) that will replace a transaction's <code>ORIGIN</code> (<code>0x32</code>) with the context variable <code>authorized</code>. The intention of <code>AUTHCALL</code> is to prevent discrimination between smart contracts and EOAs which <code>ORIGIN</code> initially facilitated and as a result, it is sensible also replace the values retrieved by the <code>ORIGINDATA*</code> opcodes to the ones used in the <code>AUTHCALL</code>.</p> <h3 id="naming-conventions">Naming Conventions</h3> <p>The <code>ORIGIN</code>-prefixed instructions attempted to conform to the existing naming convention of <code>CALL</code>-prefixed instructions given the existence of the <code>ORIGIN</code> (<code>0x32</code>) instruction which is equivalent to the <code>CALLER</code> (<code>0x33</code>) instruction but on the original transaction's context.</p> <h3 id="instruction-address-space">Instruction Address Space</h3> <p>The instruction address space of the <code>0x30-0x3f</code> has been exhausted by calls that already provide information about the execution context of a call so a new range had to be identified that is suitable for the purposes of the EIP.</p> <p>Given that the <a href="https://wg-eips.ritovision.com/1344/">EIP-1344</a> <code>CHAINID</code> opcode was included at <code>0x46</code>, it made sense to include additional transaction-related data beyond it since the Chain ID is also included in transaction payloads apart from the blocks themselves, rendering the <code>0x46-0x4f</code> address space reserved for more transaction-related data that may be necessary in the future, such as the EOA's nonce.</p> <h3 id="gas-costs">Gas Costs</h3> <p>The opcodes ORIGINDATALOAD (<code>0x47</code>), ORIGINDATASIZE (<code>0x48</code>), and ORIGINDATACOPY (<code>0x49</code>) essentially perform the same thing as opcodes CALLDATALOAD (<code>0x35</code>), CALLDATASIZE (<code>0x36</code>), and CALLDATACOPY (<code>0x37</code>) respectively and thus share the exact same gas costs.</p> <h3 id="instruction-space-pollution">Instruction Space Pollution</h3> <p>One can argue that multiple new EVM instructions pollute the EVM instruction address space and could cause issues in assigning sensible instruction codes to future instructions. This particular issue was assessed and a methodology via which the raw RLP encoded transaction may be accessible to the EVM was ideated. This would <em>future-proof</em> the new instruction set as it would be usable for other members of the transaction that may be desired to be accessible on-chain in the future, however, it would also cause a redundancy in the <code>ORIGIN</code> opcode.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The EIP does not alter or adjust existing functionality provided by the EVM and as such, no known issues exist.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="introspective-contracts">Introspective Contracts</h3> <p>Atomically, the <code>ORIGINDATALOAD</code> and <code>ORIGINDATACOPY</code> values should be considered insecure as they can easily be spoofed by creating an entry smart contract with the appropriate function signature and arguments that consequently invokes other contracts within the call chain. In brief, one should always assume that <code>tx.data != calldata</code> and these instructions should not be used as an introspection tool alone.</p> <h3 id="denial-of-service-attack">Denial-of-Service Attack</h3> <p>An initial concern that may arise from this EIP is the additional contextual data that must be provided at the software level of nodes to the EVM in order for it to be able to access the necessary data via the <code>ORIGINDATALOAD</code> and <code>ORIGINDATACOPY</code> instructions.</p> <p>This would lead to an increase in memory consumption, however, this increase should be negligible if at all existent given that the data of a transaction should already exist in memory as part of its execution process; a step in the overall inclusion of a transaction within a block.</p> <h3 id="multi-contract-system-gas-reduction">Multi-Contract System Gas Reduction</h3> <p>Given that most complex smart contract systems deployed on Ethereum today rely on cross-contract interactions whereby values are passed from one contract to another via function calls, the <code>ORIGIN</code>-prefixed instruction set would enable a way for smart contract systems to acquire access to the original transaction data at any given step in the call chain execution which could result in cross-contract calls ultimately consuming less gas if the data passed between them is reduced as a side-effect of this change.</p> <p>The gas reduction, however, would be an implementation-based optimization that would also be solely applicable for rudimentary memory arguments rather than storage-based data, the latter of which is most commonly utilized in these types of calls. As a result, the overall gas reduction observed by this change will be negligible for most implementations.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-04-16T00:00:00+00:00 2026-02-11T14:49:28+00:00 Alex Papageorgiouhttps://github.com/alex-ppg https://wg-eips.ritovision.com/3520/ <h2 id="simple-summary">Simple Summary</h2> <p>Provide access to the original recipient of a transaction.</p> <h2 id="abstract">Abstract</h2> <p>This EIP introduces the following EVM instruction: <code>ENTRYPOINT</code>.</p> <p>This instruction is meant to provide access to the original recipient of the transaction, the <code>to</code> address, enabling new ways of introspection to be applied in conjunction with <a href="https://wg-eips.ritovision.com/3508/">EIP-3508</a>.</p> <h2 id="motivation">Motivation</h2> <p>It is undeniable that smart contracts are becoming more interconnected than ever. Up until this point, smart contracts have entirely relied on compliant interfaces and introspection to introduce a new step in the call chain of a complex multi-contract interaction. However, this presents a forwards-only approach which limits the types of interactions that can manifest.</p> <p>The purpose of this EIP is to provide a way via which a contract is able to identify the entry-point of a transaction on the blockchain and deduce what was the original intention of the transaction by applying introspection on the original transaction data itself.</p> <p>This EIP enables the development of new types of smart contracts as it can open new pathways for <a href="https://wg-eips.ritovision.com/721/">EIP-721</a> NFTs and <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> tokens to detect which action their transaction is part of, such as detecting a liquidity provision to a decentralized exchange or a loan within a collateralized lending protocol.</p> <h2 id="specification">Specification</h2> <h3 id="entrypoint-0x4a">ENTRYPOINT (<code>0x4a</code>)</h3> <p>The <code>ENTRYPOINT</code> instruction uses 0 stack arguments and pushes the original <code>to</code> member of the transaction onto the stack. The address yielded by the instruction is a 160-bit value padded to 256-bits. The operation costs <code>G_base</code> to execute, similarly to <code>ORIGIN</code> (<code>0x32</code>).</p> <p>The address returned by the <code>ENTRYPOINT</code> opcode will be equivalent to the <code>to</code> address parameter specified in the nearest <code>AUTHCALL</code> up the stack. If there is no <code>AUTHCALL</code> in the stack then <code>ENTRYPOINT</code> will retrieve the original transaction's <code>to</code> field.</p> <h2 id="rationale">Rationale</h2> <h3 id="authcall-0xf7-interaction">AUTHCALL (<code>0xf7</code>) Interaction</h3> <p>The <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a> introduced a new call instruction called <code>AUTHCALL</code> (<code>0xf7</code>) that will replace a transaction's <code>ORIGIN</code> (<code>0x32</code>) with the context variable <code>authorized</code>. The intention of <code>AUTHCALL</code> is to prevent discrimination between smart contracts and EOAs which <code>ORIGIN</code> initially facilitated. The <code>ENTRYPOINT</code> opcode by itself re-introduces discrimination into the system as it indirectly allows one to evaluate whether the smart contract code being executed is done so by an EOA by validating that <code>ENTRYPOINT == ADDRESS</code> where <code>ADDRESS</code> (<code>0x30</code>) retrieves the currently executing account address. Therefore, it is sensible also replace the values retrieved by the <code>ENTRYPOINT</code> opcode to the target of an <code>AUTHCALL</code>.</p> <p>This interaction ensures full compatibility with <a href="https://wg-eips.ritovision.com/3074/">EIP-3074</a> and ensures that no form of discrimination is introduced back into the system by this EIP.</p> <h3 id="naming-conventions">Naming Conventions</h3> <p>The <code>ENTRYPOINT</code> instruction came to be by defining a sensible name that immediately and clearly depicts what it is meant to achieve by signaling the first interaction of a particular call, i.e. the entry-point.</p> <h3 id="instruction-address-space">Instruction Address Space</h3> <p>Equivalent to <a href="https://wg-eips.ritovision.com/3508/">EIP-3508</a>.</p> <h3 id="gas-cost">Gas Cost</h3> <p>The opcode ENTRYPOINT (<code>0x4a</code>) essentially performs the same thing as the opcode ORIGIN (<code>0x32</code>) and thus shares the exact same gas cost.</p> <h3 id="dependency-on-eip-3508">Dependency on EIP-3508</h3> <p>The <code>ENTRYPOINT</code> (<code>0x4a</code>) instruction alone has no perceivable benefit as it can be replaced by the <code>AUTHCALL</code> (<code>0xf7</code>) instruction and as such should solely be introduced to the system in conjunction with the <code>ORIGINDATA*</code> opcodes defined in <a href="https://wg-eips.ritovision.com/3508/">EIP-3508</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The EIP does not alter or adjust existing functionality provided by the EVM and as such, no known issues exist.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="introspective-contracts">Introspective Contracts</h3> <p>The <code>ENTRYPOINT</code> instruction allows the association of the <code>ORIGINDATALOAD</code> and <code>ORIGINDATACOPY</code> values with a particular smart contract address and interface, enabling introspection to be applied based on the function signature invoked and the arguments provided to reliably deduce the call-path via which a particular smart contract was invoked and allowing a more granular level of interaction to be defined in such special cases.</p> <p>However, this type of introspection should solely be applied on pre-approved contracts rather than user-defined ones as the value stemming from this type of introspection entirely relies on a contract's code immutability and proper function, both of which a user supplied contract can easily bypass.</p> <h3 id="caller-discrimination">Caller Discrimination</h3> <p>The instructions of this EIP should not be utilized as a way to discriminate between EOA callers and smart contracts, as this type of differentiation can be broken by an <code>AUTHCALL</code> as defined in the specification chapter.</p> <h3 id="contract-creation-behaviour">Contract Creation Behaviour</h3> <p>The behaviour of the <code>ENTRYPOINT</code> opcode during a contract creation will result in the opcode yielding the zero-address as the first address interacted with in the transaction. This should be taken into account by contract implementations in a similar fashion to how <code>ecrecover</code> invalid signatures are handled to prevent software misbehaviours from arising.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-04-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Matt Garnetthttps://github.com/lightclient https://wg-eips.ritovision.com/3521/ <h2 id="simple-summary">Simple Summary</h2> <p>Reduce the cost of declaring <code>tx.to</code> storage keys in access lists.</p> <h2 id="motivation">Motivation</h2> <p>Currently, a transaction must read at least 25 distinct storage slots in <code>tx.to</code> before it's more expensive to forego an access list.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ACCESS_LIST_ADDRESS_COST + (ACCESS_LIST_STORAGE_KEY_COST + WARM_STORAGE_READ_COST) * x = COLD_SLOAD_COST * x</span></span> <span class="giallo-l"><span>x = 24</span></span></code></pre> <p>EIP-2930 requires the address under which the storage keys reside be declared explicitly, since it must be added to the EIP-2929 <code>accessed_addresses</code> list. However, <code>tx.to</code> is a special case that is added by default, so paying <code>ACCESS_LIST_ADDRESS_COST</code> for <code>tx.to</code> is essentially paying twice for the same address. Avoiding overpayment here will reduce the differential to just 5 unique reads before using an access list is cheaper -- making them a more attractive option.</p> <h2 id="specification">Specification</h2> <p>Treat the first occurrence of <code>tx.to</code> in an access list as <code>calldata</code> for gas accounting purposes. Do not charge <code>ACCESS_LIST_ADDRESS_COST</code> for it. Storage keys underneath the address are unaffected.</p> <p>If <code>tx.to == nil</code>, <code>tx.to</code> is defined be the derived contract address created by the transaction.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-charge-at-all">Why charge at all?</h3> <p>EIP-2930 is specifically written to make access lists simple to reason about and validate. It may be possible to modify the structure of the access list to avoid including <code>tx.to</code> explicitly, but this would renege on the spirit of EIP-2930.</p> <h3 id="why-charge-as-calldata">Why charge as <code>calldata</code>?</h3> <p>The cost of <code>calldata</code> was thoroughly analyzed in EIP-2028 to determine a fair value that is not susceptible to denial-of-service attacks. We consider this the lower bound on how much transaction data should cost. Since there is no computation burden imposed for adding <code>tx.to</code> to the <code>accessed_addresses</code> map (it's added by default by <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a>), there is no reason to charge more than the absolute minimum for the data.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;0xffffffffffffffffffffffffffffffffffffffff&quot;: []</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>cost = 320</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;0x00ffffffffffffffffffffffffffffffffffffff&quot;: []</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>cost = 308</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;0xffffffffffffffffffffffffffffffffffffffff&quot;: []</span></span> <span class="giallo-l"><span> &quot;0xffffffffffffffffffffffffffffffffffffffff&quot;: []</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>cost = 2720</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;0xffffffffffffffffffffffffffffffffffffffff&quot;: [</span></span> <span class="giallo-l"><span> &quot;0x00&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> &quot;0xffffffffffffffffffffffffffffffffffffffff&quot;: []</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>cost = 4620</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;0xffffffffffffffffffffffffffffffffffffffff&quot;: [</span></span> <span class="giallo-l"><span> &quot;0x00&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> &quot;0xffffffffffffffffffffffffffffffffffffffff&quot;: [</span></span> <span class="giallo-l"><span> &quot;0x00&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>cost = 6520</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No issues.</p> <h2 id="security-considerations">Security Considerations</h2> <p>None.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-04-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Morrisshttps://github.com/wjmelements Baptiste Vautheyhttps://github.com/thabaptiser https://wg-eips.ritovision.com/3455/

A new opcode is introduced to allow calling from an arbitrary sender address.

<h2 id="abstract">Abstract</h2> <p>A new opcode, <code>SUDO</code>, is introduced with the same parameters as <code>CALL</code>, plus another parameter to specify the sender address.</p> <h2 id="motivation">Motivation</h2> <p>There are many use cases for being able to set the sender.</p> <p>Many tokens are stuck irretrievably because nobody has the key for the owner address. In particular, at address zero there is approximately 17 billion USD in tokens and ether, according to etherscan. With <code>SUDO</code>, anyone could free that value, leading to an economic boom that would end poverty and world hunger. Instead it is sitting there idle like the gold in Fort Knox. <code>SUDO</code> fixes this.</p> <p>It is a common mistake to send <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to the token address instead of the intended recipient. This happens because users paste the token address into the recipient fields. Currently there is no way to recover these tokens. <code>SUDO</code> fixes this.</p> <p>Many scammers have fraudulently received tokens and ETH via trust-trading. Their victims currently have no way to recover their funds. <code>SUDO</code> fixes this.</p> <p>Large amounts of users have accidentally locked up tokens and ether by losing their private keys. This is inefficient and provides a bad user experience. To accommodate new and inexperienced users, there needs to be a way to recover funds after the private key has been lost. <code>SUDO</code> fixes this.</p> <p>Finally, there are many tokens and ether sitting in smart contracts locked due to a bug. We could finally close EIP issue #156. We cannot currently reclaim ether from stuck accounts. <code>SUDO</code> fixes this.</p> <h2 id="specification">Specification</h2> <p>Adds a new opcode (<code>SUDO</code>) at <code>0xf8</code>. <code>SUDO</code> pops 8 parameters from the stack. Besides the sender parameter, the parameters shall match <code>CALL</code>.</p> <ol> <li>Gas: Integer; Maximum gas allowance for message call, safely using current gas counter if the counter is lower</li> <li>Sender: Address, truncated to lower 40 bytes; Sets <code>CALLER</code> inside the call frame</li> <li>To: Address, truncated to lower 40 bytes; sets <code>ADDRESS</code></li> <li>Value: Integer, raises exception amount specified is less than the value in Sender account; transferred with call to recipient balance, sets <code>CALLVALUE</code></li> <li>InStart: Integer; beginning of memory to use for <code>CALLDATA</code></li> <li>InSize: Integer; length of memory to use for <code>CALLDATA</code></li> <li>OutStart: Integer; beginning of memory to replace with <code>RETURNDATA</code></li> <li>OutSize: Integer; maximum <code>RETURNDATA</code> to place in memory</li> </ol> <p>Following execution, <code>SUDO</code> pushes a result value to the stack, indicating success or failure. If the call ended with <code>STOP</code>, <code>RETURN</code>, or <code>SELFDESTRUCT</code>, <code>1</code> is pushed. If the call ended with <code>REVERT</code>, <code>INVALID</code>, or an EVM assertion, <code>0</code> is pushed.</p> <h2 id="rationale">Rationale</h2> <p>The <code>GAS</code> parameter is first so that callers can tediously compute how much of their remaining gas to send at the last possible moment. The remaining parameters inherited from <code>CALL</code> are in the same order, with sender inserted between.</p> <h2 id="security-considerations">Security Considerations</h2> <p>It will be fine.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Daniel Streithttps://github.com/danielstreit https://wg-eips.ritovision.com/3450/ <h2 id="simple-summary">Simple Summary</h2> <p>A standardized algorithm for applying Shamir's Secret Sharing Scheme to BIP-39 mnemonics.</p> <h2 id="abstract">Abstract</h2> <p>A standardized approach to splitting a BIP-39 mnemonic into <em>N</em> BIP-39 mnemonics, called shares, so that <em>T</em> shares are required to recover the original mnemonic and no information about the original mnemonic, other than its size, is leaked with less than <em>T</em> shares.</p> <h2 id="motivation">Motivation</h2> <p>We'd like to make it easier for less-technical users to store keys securely.</p> <p>Currently, many users use BIP-39 mnemonics to store entropy values underlying their keys. These mnemonics are a single point of failure. If lost, the user may never regain access to the assets locked by the keys. If stolen, a malicious actor can steal the assets.</p> <p>Shamir's Secret Sharing Scheme addresses this concern directly. It creates "shares" of the secret, such that a subset can be used to recover the secret, but only if a minimum threshold of shares is reached. Without the minimum, no information about the original secret is leaked.</p> <p>One concern with Shamir's Secret Sharing Scheme is there is no canonical, standard implementation. This puts recovery at risk, as tooling may change over time.</p> <p>Here, we propose a standardized implementation of Shamir's Secret Sharing Scheme applied specifically to BIP-39 mnemonics, so users can easily create shares of their mnemonic, destroy the original, store the shares appropriately, and confidently recover the original mnemonic at a later date.</p> <h2 id="specification">Specification</h2> <h3 id="shamir-s-secret-sharing-scheme">Shamir's Secret Sharing Scheme</h3> <p>Shamir's Secret Sharing Scheme is a cryptographic method to split a secret into <em>N</em> unique parts, where any <em>T</em> of them are required to reconstruct the secret.</p> <p>First, a polynomial <em>f</em> of degree <em>T</em> − 1 is constructed. Then, each share is a point on the polynomial's curve: an integer <em>x</em>, and its corresponding <em>y</em> point <em>f</em>(<em>x</em>).</p> <p>With any set of <em>T</em> shares (or points), the initial polynomial can be recovered using polynomial interpolation.</p> <p>When constructing the initial polynomial, the secret is stored as the coefficient of x⁰ and the rest of the coefficients are randomly generated.</p> <h3 id="bip-39-mnemonics">BIP-39 Mnemonics</h3> <p>BIP-39 is a common standard for storing entropy as a list of words. It is easier to work with for human interactions than raw binary or hexadecimal representations of entropy.</p> <p>BIP-39 mnemonics encode two pieces of data: the original entropy and a checksum of that entropy. The checksum allows the mnemonic to be validated, ensuring that the user entered it correctly.</p> <h4 id="generating-the-mnemonic">Generating the Mnemonic</h4> <p>The mnemonic must encode entropy in a multiple of 32 bits. With more entropy security is improved but the sentence length increases. We refer to the initial entropy length as ENT. The allowed size of ENT is 128-256 bits.</p> <p>First, an initial entropy of ENT bits is generated. A checksum is generated by taking the first <code>ENT / 32</code> bits of its SHA256 hash. This checksum is appended to the end of the initial entropy. Next, these concatenated bits are split into groups of 11 bits, each encoding a number from 0-2047, serving as an index into a word list. Finally, we convert these numbers into words and use the joined words as a mnemonic sentence.</p> <p>The following table describes the relation between the initial entropy length (ENT), the checksum length (CS), and the length of the generated mnemonic sentence (MS) in words.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>CS = ENT / 32</span></span> <span class="giallo-l"><span>MS = (ENT + CS) / 11</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>| ENT | CS | ENT+CS | MS |</span></span> <span class="giallo-l"><span>+-------+----+--------+------+</span></span> <span class="giallo-l"><span>| 128 | 4 | 132 | 12 |</span></span> <span class="giallo-l"><span>| 160 | 5 | 165 | 15 |</span></span> <span class="giallo-l"><span>| 192 | 6 | 198 | 18 |</span></span> <span class="giallo-l"><span>| 224 | 7 | 231 | 21 |</span></span> <span class="giallo-l"><span>| 256 | 8 | 264 | 24 |</span></span></code></pre><h4 id="recovering-the-entropy">Recovering the Entropy</h4> <p>The initial entropy can be recovered by reversing the process above. The mnemonic is converted to bits, where each word is converted to 11 bits representing its index in the word list. The entropy portion is defined in the table above, based on the size of the mnemonic.</p> <h4 id="word-list">Word List</h4> <p>This specification only supports the BIP-39 English word list, but this may be expanded in the future.</p> <p>See <a href="https://wg-eips.ritovision.com/3450/./assets/wordlist.txt">word list</a>.</p> <h3 id="applying-shamir-s-scheme-to-bip-39-mnemonics">Applying Shamir's Scheme to BIP-39 Mnemonics</h3> <p>To ensure that the shares are valid BIP-39 mnemonics, we:</p> <ol> <li>Convert the target BIP-39 mnemonic to its underlying entropy</li> <li>Apply Shamir's Scheme to the entropy</li> <li>Convert each resulting share's <em>y</em> value to a BIP-39 mnemonic</li> </ol> <p>By converting to entropy before applying Shamir's Scheme, we omit the checksum from the initial secret, allowing us to calculate a new checksum for each share when converting the share <em>y</em> values to mnemonics, ensuring that they are valid according to BIP-39.</p> <p>When applying Shamir's Scheme to the entropy, we apply it separately to each byte of the entropy and GF(256) is used as the underlying finite field. Bytes are interpreted as elements of GF(256) using polynomial representation with operations modulo the Rijndael irreducible polynomial <em>x</em>⁸ + <em>x</em>⁴ + <em>x</em>³ + <em>x</em> + 1, following AES.</p> <h3 id="share-format">Share Format</h3> <p>A share represents a point on the curve described by the underlying polynomial used to split the secret. It includes two pieces of data:</p> <ul> <li>An ID: the <em>x</em> value of the share</li> <li>A BIP-39 mnemonic: the <em>y</em> value of the share represented by a mnemonic</li> </ul> <h3 id="creating-shares">Creating Shares</h3> <p>Inputs: BIP-39 mnemonic, number of shares (<em>N</em>), threshold (<em>T</em>)</p> <p>Output: N Shares, each share including an ID, { <em>x</em> | 0 &lt; <em>x</em> &lt; 256 }, and a BIP-39 mnemonic of the same length as the input one</p> <ol> <li>Check the following conditions: <ul> <li>1 &lt; T &lt;= N &lt; 256</li> <li>The mnemonic is valid according to <a href="https://wg-eips.ritovision.com/3450/#generating-the-mnemonic">BIP-39</a></li> </ul> </li> <li><a href="https://wg-eips.ritovision.com/3450/#recovering-the-entropy">Recover the underlying entropy of the mnemonic</a> as a vector of bytes</li> <li>Define values: <ul> <li>Let <em>E</em> be the byte-vector representation of the mnemonic's entropy</li> <li>Let <em>n</em> be the length of <em>E</em></li> <li>Let <em>coeff₁</em>, ... , <em>coeff_{T - 1}</em> be byte-vectors belonging to GF(256)<em>ⁿ</em> generated randomly, independently with uniform distribution from a source suitable for generating cryptographic keys</li> </ul> </li> <li>Evaluate the polynomial for each share <ul> <li>For each <em>x</em> from 1 to <em>N</em>, evaluate the polynomial <em>f(x)</em> = <em>E</em> + <em>coeff₁x¹</em> + ... + <em>coeff_{T - 1}x^{T - 1}</em>, where <em>x</em> is the share ID and <em>f(x)</em> is the share value (as a vector of bytes)</li> </ul> </li> <li>Using <em>f(x)</em> as the underlying entropy, <a href="https://wg-eips.ritovision.com/3450/#generating-the-mnemonic">generate a mnemonic</a> for each share</li> <li>Return the ID and mnemonic for each share</li> </ol> <h3 id="recovering-the-mnemonic">Recovering the Mnemonic</h3> <p>To recover the original mnemonic, we interpolate a polynomial <em>f</em> from the given set of shares (or points on the polynomial) and evaluate <em>f(0)</em>.</p> <h4 id="polynomial-interpolation">Polynomial Interpolation</h4> <p>Given a set of <em>m</em> points (<em>x_i</em>, <em>y_i</em>), 1 ≤ <em>i</em> ≤ <em>m</em>, such that no two <em>x_i</em> values equal, there exists a polynomial that assumes the value <em>y_i</em> at each point <em>x_i</em>. The polynomial of lowest degree that satisfies these conditions is uniquely determined and can be obtained using the Lagrange interpolation formula given below.</p> <p>Since Shamir's Secret Sharing Scheme is applied separately to each of the <em>n</em> bytes of the shared mnemonic's entropy, we work with <em>y_i</em> as a vector of <em>n</em> values, where <em>y_i</em>[<em>k</em>] = <em>f_k</em>(<em>x_i</em>), 1 ≤ <em>k</em> ≤ <em>n</em>, and <em>f_k</em> is the polynomial in the <em>k</em>-th instance of the scheme.</p> <h4 id="interpolate-x-xi-yi-1-i-m">Interpolate(<em>x</em>, {(<em>x_i</em>, <em>y_i</em>), 1 ≤ <em>i</em> ≤ <em>m</em>})</h4> <p>Input: the desired index <em>x</em>, a set of index/value-vector pairs {(<em>x_i</em>, <em>y</em>_<em>i</em>), 1 ≤ <em>i</em> ≤ <em>m</em>} ⊆ GF(256) × GF(256)^<em>n</em></p> <p>Output: the value-vector (<em>f</em>₁(<em>x</em>), ... , <em>f_n</em>(<em>x</em>))</p> <p><img src="https://wg-eips.ritovision.com/3450/./assets/lagrange.gif" alt="f_k(x) = \sum_{i=1}^m y_i[k] \prod_{\underset{j \neq i}{j=1}}^m \frac{x - x_j}{x_i - x_j}" /></p> <h4 id="recover-the-mnemonic">Recover the Mnemonic</h4> <p>Input: A set of <em>m</em> Shares</p> <p>Output: The original mnemonic</p> <ol> <li><a href="https://wg-eips.ritovision.com/3450/#recovering-the-entropy">Recover the underlying entropy of each share's mnemonic</a> as a vector of bytes</li> <li>Calculate <em>E</em> = Interpolate(0, [(<em>x₁</em>, <em>y₁</em>),...,(<em>x_m</em>, <em>y_m</em>)]), where <em>x</em> is the share ID and <em>y</em> is the byte-vector of the share's mnemonic's entropy</li> <li>Using <em>E</em> as the underlying entropy, <a href="https://wg-eips.ritovision.com/3450/#generating-the-mnemonic">generate a mnemonic</a> and return it</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="choice-of-field">Choice of Field</h3> <p>The field GF(256) was chosen, because the field arithmetic is easy to implement in any programming language and many implementations are already available since it is used in the AES cipher. Although using GF(256) requires that we convert the mnemonic to its underlying entropy as a byte-vector, this is also easy to implement and many implementations of it exist in a variety of programming languages.</p> <p>GF(2048) was also considered. Using GF(2048), we could have applied Shamir's Scheme directly to the mnemonic, using the word indexes as the values. This would have allowed us to avoid converting the mnemonic to its underlying entropy. But, the resulting shares would not have been valid BIP-39 mnemonics - the checksum portion would not be a valid checksum of the entropy. And, working around this would add considerable complexity.</p> <p>Another option was GF(2^<em>n</em>) where <em>n</em> is the size of the entropy in bits. We'd still convert the mnemonic to entropy, but then apply Shamir's Scheme over the entire entropy rather than on a vector of values. The downside of this approach is we'd need a different field for each mnemonic strength along with an associated irreducible polynomial. Additionally, this would require working with very large numbers that can be cumbersome to work with in some languages.</p> <h3 id="valid-share-mnemonics-and-share-ids">Valid Share Mnemonics and Share IDs</h3> <p>The shares produced by the specification include an ID, in addition to the BIP-39 mnemonic.</p> <p>Other options could have encoded the share ID into the mnemonic, simplifying storage - only the mnemonic would need to be stored.</p> <p>One possibility would be to store the ID instead of the checksum in the mnemonic. The downside of this approach is that the shares would not be <em>valid</em> BIP-39 mnemonics because the "checksum" section of the mnemonic would not match the "entropy" section. Shares with valid BIP-39 mnemonics are useful because they are indistinguishable from any other. And users could store the ID in a variety of ways that obscure it.</p> <h3 id="validation-on-recovery">Validation on Recovery</h3> <p>We decided <em>not</em> to include a validation mechanism on recovering the original mnemonic. This leaks less information to a potential attacker. There is no indication they've gotten the requisite number of shares until they've obtained <em>T</em> + 1 shares.</p> <p>We could provide recovery validation by replacing one of the random coefficients with a checksum of the original mnemonic. Then, when recovering the original mnemonic and the polynomial, we could validate that the checksum coefficient is the valid checksum of recovered mnemonic.</p> <h2 id="test-cases">Test Cases</h2> <p>Coming soon.</p> <p>All implementations must be able to:</p> <ul> <li>Split and recover each <code>mnemonic</code> with the given <code>numShares</code> and <code>threshold</code>.</li> <li>Recover the <code>mnemonic</code> from the given <code>knownShares</code>.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The shares produced by the specification include an ID in addition to the BIP-39 mnemonic. This raises two security concerns:</p> <p>Users <strong>must</strong> keep this ID in order to recover the original mnemonic. If the ID is lost, or separated from the share mnemonic, it may not be possible to recover the original. (Brute force recovery may or may not be possible depending on how much is known about the number of shares and threshold)</p> <p>The additional data may hint to an attacker of the existence of other keys and the scheme under which they are stored. Therefore, the ID should be stored in a way that obscures its use.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/3436/ <h2 id="simple-summary">Simple Summary</h2> <p>Add a four step block rule to Clique that should reduce block production deadlocks</p> <h2 id="abstract">Abstract</h2> <p>The current specification of Clique allows for multiple competing blocks from producers but does not provide any strategies to pick blocks aside from the current "highest total difficulty" rule. This EIP proposes a four step choice rule of highest total difficulty, shortest chain, most recently in-turn, and lowest hash. This would prevent deadlocks that have occurred in production systems.</p> <h2 id="motivation">Motivation</h2> <p>There has been more than one deadlock in the Goerli multi-client Clique network. The number of active validators was greater than 1/2 of the available validators so a chain halt should not have occurred. The halt was resolved by an inactive validator coming back on line. The state of the chain was in one of two configurations of 8 validators that can result in a chain halt. Three of the four clients observed a choice sequence of lowest total difficulty followed by first observed block. Geth added one extra rule of preferring the shortest chain before preferring the first observed block. This fork would have resolved itself with Geth's rule, but there is still a configuration where the chain can halt with a shortest chain rule.</p> <h2 id="specification">Specification</h2> <p>When a Clique validator is arbitrating the canonical status between two different chain head blocks, they should choose the canonical block with the following ordered priorities.</p> <ol> <li>Choose the block with the most total difficulty.</li> <li>Then choose the block with the lowest block number.</li> <li>Then choose the block whose validator had the least recent in-turn block assignment.</li> <li>Then choose the block with the lowest hash.</li> </ol> <p>When resolving rule 3 clients should use the following formula, where <code>validator_index</code> is the integer index of the validator that signed the block when sorted as per epoch checkpointing, <code>header_number</code> is the number of the header, and <code>validator_count</code> is the count of the current validators. Clients should choose the block with the <strong>largest</strong> value. Note that an in-turn block is considered to be the most recent in-turn block.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(header_number - validator_index) % validator_count</span></span></code></pre> <p>When resolving rule 4 the hash should be converted into an unsigned 256 bit integer.</p> <h2 id="rationale">Rationale</h2> <p>Two scenarios of a halted chain are known based on the current total difficulty then first observed rule. One of the scenarios is also resistant to the shortest chain rule.</p> <p>For the first scenario where chains of different lengths can halt consider a block with 8 validators, whose addresses sort to the same order as their designation in this example. A fully in-order chain exists and validator number 8 has just produced an in-turn block and then validators 5, 7 and 8 go offline, leaving validators 1 to 6 to produce blocks. Two forks form, one with an in-order block from validator 1 and then an out of order block from validator 3. The second fork forms from validators 2, 4, and 6 in order. Both have a net total difficulty of 3 more than the common ancestor. So in this case if both forks become aware of the other fork then both are considered equally viable and neither set of validators should switch to the newly observed fork. In this case, adding a shortest chain rule would break the deadlock as the even numbered validators would adopt the shorter chain.</p> <p>For the second scenario with the same validator set and in-order chain with validator 7 having just produced an in order block, then validators 7 and 8 go offline. Two forks form, 1,3,5 on one side and 2,4,6 on the other. Both forks become aware of the other fork after producing their third block. In this case both forks have equal total difficulty and equal length. So Geth's rule would not break the tie and only the arrival of one of the missing validators fix the chain. In a worst case scenario the odd and even chains would produce a block for 7 and 8 respectively, and chain halt would result with no validators that have not chosen a fork. Only a manual rollback would fix this.</p> <p>One consideration when formulating the rules is that the block choice should be chosen so that it would encourage the maximum amount of in-order blocks. Selecting a chain based on shortest chain implicitly prefers the chain with more in-order blocks. When selecting between competing out of order chains the validator who is closest to producing an in-order block in the future should have their chain declined so that they are available to produce an in-order block sooner.</p> <p>At least one client has been observed producing multiple blocks at the same height with the same difficulty, so a final catch-all standard of lowest block hash should break any remaining ties.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The current block choice rules are a mix of most total difficulty and most total difficulty plus shortest chain.</p> <p>As long as the majority of the active validators implement the block choice rules then a client who only implements the existing difficulty based rule will eventually align with the chain preferred by these rules. If less than a majority implement these rules then deadlocks can still occur, and depend on the first observation of problematic blocks, which is no worse than the current situation.</p> <p>If clients only partially implement the rule as long as every higher ranked rule is also implemented then the situation will be no worse than today.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Malicious and motivated attackers who are participating in the network can force the chain to halt with well crafted block production. With a fully deterministic choice rule the opportunity to halt is diminished. Attackers still have the same opportunities to flood the network with multiple blocks at the same height. A deterministic rule based on the lowest hash reduces the impact of such a flooding attack. A malicious validator could exploit this deterministic rule to produce a replacement block. Such an attack exists in current implementations but a deterministic hash rule makes such replacements more likely. However the impact of such an attack seems low to trivial at this time.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 HexZorrohttps://github.com/hexzorro Mojtaba Tefaghhttps://github.com/mtefagh https://wg-eips.ritovision.com/3416/ <h2 id="simple-summary">Simple Summary</h2> <p>A transaction pricing mechanism with a fixed-per-block network fee and a median inclusion fee with additive updates.</p> <h2 id="abstract">Abstract</h2> <p>There is a base fee per gas in protocol, which can move up or down by a maximum of 1/8 in each block. The base fee per gas is adjusted by the protocol to target an average gas usage per block instead of an absolute gas usage per block. The base fee is increased when blocks are over the gas limit target and decreases when blocks are under the gas limit target. Transaction senders specify their fees by providing <em>only one value</em>:</p> <ul> <li>The fee cap which represents the maximum total (base fee + gas premium) that the transaction sender would be willing to pay to get their transaction included, resembles the current maximum gas price specified by senders but in this protocol change proposal the final gas price paid, most of the time, will be lower than the proposed by the transaction sender.</li> </ul> <p>Then there is a gas premium that is directly computed as 50% of (fee cap - base fee). This gas premium gets added onto the base fee to calculate the gas price that will be used in the weighted median computation. The gas premium, determined directly by a specified fee cap, can either be set to a fairly low value to compensate miners for uncle rate risk only with the base fee, or to a high value to compete during sudden bursts of activity. Using all transactions that the miner wants to include in the block, a <strong>weighted median gas premium</strong> is computed, not considering in the computation 5% of gas price outliers on the upper-side for extra robustness against miner manipulation.</p> <h2 id="motivation">Motivation</h2> <p>We target the following goals:</p> <ul> <li>Gas prices spikes are mathematically smoothed out. EIP1559 does not seems to really tackle gas premium volatility and UX.</li> <li>Maintain gas price preference, i.e. transaction senders willing to pay extra in fees will be rewarded with early preferential inclusion in the blocks, because the miners want to maximize their profits and include transactions with higher fee caps first to maximize the median.</li> <li>Final gas price paid by the sender is, most of the time, smaller than the maximum gas price specified by sender.</li> <li>Gas pricing is more robust to sender manipulation or miner manipulation.</li> </ul> <p>Ethereum currently prices transaction fees using a simple auction mechanism, where users send transactions with bids ("gasprices") and miners choose transactions with the highest bids, and transactions that get included pay the bid that they specify. This leads to several large sources of inefficiency:</p> <ul> <li><strong>Current extreme volatility of gas prices is hurting user experience</strong>: if you observe online gas price metrics, the current trends in recommended gas prices can change substantially by the minute, making the user experience in the network very awkward. Also, gas volatility makes the mining business more unpredictable and costly, because miners need to spend money hedging the risks.</li> <li><strong>Mismatch between volatility of transaction fee levels and social cost of transactions</strong>: bids to include transactions on mature public blockchains, that have enough usage so that blocks are full, tend to be extremely volatile. On Ethereum, minimum bids range between 1 nanoeth (10^9 nanoeth = 1 ETH), but sometimes go over 100 nanoeth and have reached over 200 nanoeth. This clearly creates many inefficiencies, because it's absurd to suggest that the cost incurred by the network from accepting one more transaction into a block actually is 200x more when gas prices are 200 nanoeth than when they are 1 nanoeth; in both cases, it's a difference between 8 million gas and 8.02 million gas.</li> <li><strong>Needless delays for users</strong>: because of the hard per-block gas limit coupled with natural volatility in transaction volume, transactions often wait for several blocks before getting included, but this is socially unproductive; no one significantly gains from the fact that there is no "slack" mechanism that allows one block to be bigger and the next block to be smaller to meet block-by-block differences in demand.</li> <li><strong>Inefficiencies of first price auctions</strong>: The current approach, where transaction senders publish a transaction with a bid a maximum fee, miners choose the highest-paying transactions, and everyone pays what they bid. This is well-known in mechanism design literature to be highly inefficient, and so complex fee estimation algorithms are required. But even these algorithms often end up not working very well, leading to frequent fee overpayment. We need a more stable fee metric that is computed inside the protocol.</li> </ul> <p>The proposal in this EIP is to start with a base fee amount which is adjusted up and down by the protocol based on how congested the network is. When the network exceeds the target per-block gas usage, the base fee increases slightly and when capacity is below the target, it decreases slightly. Because these base fee changes are constrained, the maximum difference in base fee from block to block is predictable. This then allows wallets to auto-set the gas fees for users in a highly reliable fashion. It is expected that most users will not have to manually adjust gas fees, even in periods of high network activity. For most users the base fee will be estimated by their wallet and a small gas premium related to the urgency and the priority they want to instill into the transaction.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <p>This is a classic fork without a long migration time.</p> <ul> <li><code>FORK_BLOCK_NUMBER</code>: TBD. Block number at or after which EIP-3416 transactions are valid.</li> <li><code>GAS_TARGET_MAX_CHANGE</code>: <code>1 // 1024</code>.</li> <li><code>BLOCK_GAS_USED</code>: total gas consumed by transaction included in the block.</li> <li><code>PARENT_GAS_USED</code>: same as <code>BLOCK_GAS_USED</code> for parent block.</li> <li><code>CURRENT_BLOCK</code>: The current block that is being worked with (either being validated, or being produced).</li> <li><code>BASE_FEE</code>: 16th item in the block header. Represents the amount of attoeth burned for every unit of gas a transaction uses.</li> <li><code>PARENT_BASE_FEE</code>: same as <code>BASE_FEE</code> for parent block.</li> <li><code>BASE_FEE_MAX_CHANGE</code>: <code>1 // 8</code></li> <li><code>INITIAL_BASE_FEE</code> : Median gas price in <code>FORK_BLOCK_NUMBER - 1</code>.</li> </ul> <h3 id="process">Process</h3> <ul> <li>At <code>block.number == FORK_BLOCK_NUMBER</code> we set <code>BASE_FEE = INITIAL_BASE_FEE</code></li> <li><code>BASE_FEE</code> is set, from <code>FORK_BLOCK_NUMBER + 1</code>, as follows <ul> <li>Let <code>GAS_DELTA = (PARENT_GAS_USED - PARENT_GAS_TARGET) // PARENT_GAS_TARGET</code> (possibly negative).</li> <li>Set <code>BASE_FEE = PARENT_BASE_FEE + GAS_DELTA * BASE_FEE_MAX_CHANGE</code></li> </ul> </li> <li>Transactions since <code>FORK_BLOCK_NUMBER</code> are encoded the same as the current ones <code>rlp([nonce, gasPrice, gasLimit, to, value, data, v, r, s])</code> where <code>v,r,s</code> is a signature of <code>rlp([nonce, gasPrice, gasLimit, to, value, data])</code> and <code>gasPrice</code> is the <code>FEE_CAP</code> specified by the sender according to this proposal.</li> <li>To produce transactions since <code>FORK_BLOCK_NUMBER</code>, the new <code>FEE_CAP</code> field (maintaining legacy name of <code>gasPrice</code> in the transaction) is set as follows (and the <code>GAS_PREMIUM</code> is computed as specified): <ul> <li><code>FEE_CAP</code>: <code>tx.gasPrice</code>, serves as the absolute maximum that the transaction sender is willing to pay.</li> <li><code>GAS_PREMIUM = (FEE_CAP - BASE_FEE) / 2</code> serves as a sender-preferred median premium to the miner, beyond the base fee.</li> <li>If <code>FEE_CAP &lt; BASE_FEE</code> then the transaction is considered invalid and cannot be included in the current block, but might be included in future blocks.</li> </ul> </li> <li>During transaction execution, for EIP3416 transactions we calculate the cost to the <code>tx.origin</code> and the gain to the <code>block.coinbase</code> as follows: <ul> <li>Set <code>GASPRICE = BASE_FEE + median((tx_i.gasPrice - BASE_FEE) / 2)</code> among all transactions <code>tx_i</code> included in the same block, <em>weighted by gas consumed</em> and not including the top 5% of outlier gas price in calculation. By weighted median without 5% of the upper-side outliers, we mean that each gas unit spent is ordered according to the corresponding transaction by <code>BASE_FEE + tx.gasPrice / 2</code> and then the value chosen will be the one separating the lower 95% in two parts.</li> <li>Let <code>GASUSED</code> be the gas used during the transaction execution/state transition.</li> <li>The <code>tx.origin</code> initially pays <code>GASPRICE * tx.gasLimit</code>, and gets refunded <code>GASPRICE * (tx.gasLimit - GASUSED)</code>.</li> </ul> </li> </ul> <p>The miners can still use a <code>greedy</code> strategy to include new transactions in the proposed blocks by adding the transactions ordered by larger <code>FEE_CAP</code> first. This is similar to how current blocks are filled, and is a consequence of <code>FEE_CAP</code> and <code>GAS_PREMIUM</code> being a positive linear function of each other.</p> <h2 id="rationale">Rationale</h2> <p>The rationale behind the premium being 50% of (fee cap - base fee) is that at any given point the average network sender has an average fee cap, and we assume that between base fee and fee cap the sender has no specific preference, as long as the transaction is included in some block. Then, the sender is happy with a median premium among this uniform range. Another justification can be that the user also knows that this new version of the pricing protocol for the complete block uses a median, then is fair for him to apply a median within his preferential range, assuming an uniform sampling there. Simulations (<a rel="external" href="https://hackmd.io/c6kyRNMuTnKf_SlolmevRg#An-improvement-for-the-premium">here</a>) with Ethereum gas data shows indeed that median one of the most robust metric.s</p> <p>The 5% top outliers removal, not considered in the median, or similar number, is to give extra robustness against miner manipulation, because as current network utilization has been around 97% for the last 6 months the miners can include their own transactions on the empty 3% to try to manipulate and increase the median price (even this manipulation effect will be very small on the final price).</p> <p>The rationale for the <code>BASE_FEE</code> update formula is that we are using an additive version (<code>PARENT_BASE_FEE + GAS_DELTA * BASE_FEE_MAX_CHANGE</code>) to avoid an attack of senders sending this fee to zero. This attack was simulated and observed for multiplicative formula proposed in previous version (<code>PARENT_BASE_FEE + PARENT_BASE_FEE * GAS_DELTA * BASE_FEE_MAX_CHANGE</code>). See an article about the attack and the simulation <a rel="external" href="https://mtefagh.github.io/fee/">here</a>.</p> <p>Another rationale for the additive <code>BASE_FEE</code> update formula is that it guarantees (see <a rel="external" href="https://pdfs.semanticscholar.org/3d2d/773983c5201b58586af463f045befae5bbf2.pdf">this</a> article) that the optimal execution strategy (scheduling broadcasts in order to pay less fee) for a batch of nonurgent transactions is to spread the transactions across different blocks which in turn helps to avoid network congestion and lowers volatility. For the multiplicative formula, it is exactly the reverse, that is, spikes (dumping all your transactions at once) are incentivized as described <a rel="external" href="https://ethresear.ch/t/path-dependence-of-eip-1559-and-the-simulation-of-the-resulting-permanent-loss/8964">here</a>.</p> <p>The rationale for the <code>BASE_FEE_MAX_CHANGE</code> being <code>1 // 8</code> is that the <code>BASE_FEE</code> is designed to be very adaptative to block utilization changes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The backward compatibility is very straightforward because there are no new fields added to the transactions. Pricing of the gas per block on the miner/validator side is still fast to compute but a little more complex. Changes only affect miners/validators. Wallets are no affected by this proposal.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Senders cannot manipulate the minimum fee because the minimum <code>BASE_FEE</code> is controlled by the miners with small increments or decrements on each new block proposed.</li> <li>Above the <code>BASE_FEE</code> the senders have a very limited ability to manipulate and lower the final gas price they pay because they have to move the weighted median close to <code>BASE_FEE</code> and, as we know, this is a very robust statistic.</li> <li>Miners have a very limited ability to manipulate and raise the final gas price paid by senders above <code>BASE_FEE</code> because to influence the final gas price they have to stuff fake transactions beyond the top 5% of the blocks. In average and currently, only the top 3% of the block is empty, so to fill-up 5% of the block they need to start dropping profitable transactions to reach 5%. Only beyond 5% of the top block gas they can start moving the median a little and the median is still a very robust statistic, not liable to being easily manipulated.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Martin Swendehttps://github.com/holiman https://wg-eips.ritovision.com/3403/ <h2 id="simple-summary">Simple Summary</h2> <p>Remove gas refunds for SELFDESTRUCT, and restrict gas refunds for SSTORE to one specific case.</p> <h2 id="motivation">Motivation</h2> <p>Gas refunds for SSTORE and SELFDESTRUCT were originally introduced to motivate application developers to write applications that practice "good state hygiene", clearing storage slots and contracts that are no longer needed. However, they are not widely used for this, and poor state hygiene continues to be the norm. It is now widely accepted that the only solution to state growth is some form of statelessness or state expiry, and if such a solution is implemented, then disused storage slots and contracts would start to be ignored automatically.</p> <p>Gas refunds additionally have multiple harmful consequences:</p> <ul> <li>Refunds give rise to GasToken. GasToken has benefits in moving gas space from low-fee periods to high-fee periods, but it also has downsides to the network, particularly in exacerbating state size (as state slots are effectively used as a "battery" to save up gas) and inefficiently clogging blockchain gas usage</li> <li>Refunds increase block size variance. The theoretical maximum amount of actual gas consumed in a block is nearly twice the on-paper gas limit (as refunds add gas space for subsequent transactions in a block, though refunds are capped at 50% of a transaction's gas used). This is not fatal, but is still undesirable, especially given that refunds can be used to maintain 2x usage spikes for far longer than EIP 1559 can.</li> </ul> <h3 id="the-mutex-usecase">The mutex usecase</h3> <p>There are two typical ways to implement mutexes: '0-1-0' and '1-2-1. Let's see how they differ</p> <ul> <li>'0-1-0': <ul> <li>Istanbul: 1612</li> <li>Berlin: 212</li> <li>NoRefund: 20112</li> <li>EIP-3403: 1112</li> </ul> </li> <li>'1-2-1': <ul> <li>Istanbul: 1612</li> <li>Berlin: 212</li> <li>NoRefund: 3012</li> <li>EIP-3403: 3012</li> </ul> </li> </ul> <p><strong>Note</strong>: In reality, there are never a negative gas cost, since the refund is capped at 0.5 * gasUsed. However, these tables show the negative values, since a more real-world scenario would likely spend the extra gas on other operations.'</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLOCK</code></td><td>TBD</td></tr> <tr><td><code>SSTORE_REFUND_GAS</code></td><td>19000</td></tr> </tbody></table> <p>For blocks where <code>block.number &gt;= FORK_BLOCK</code>, the following changes apply.</p> <ol> <li>Remove the <code>SELFDESTRUCT</code> refund.</li> <li>Remove the <code>SSTORE</code> refund in all cases except for one specific case: if the <em>new value</em> and <em>original value</em> of the storage slot both equal 0 but the <em>current value</em> does not (those terms being defined as in <a rel="external" href="https://eips.ethereum.org/EIPS/eip-1283">EIP-1283</a>), refund <code>SSTORE_REFUND_GAS</code> gas.</li> </ol> <h2 id="rationale">Rationale</h2> <p>Preserving refunds in the <code>new = original = 0 != current</code> case ensures that a few key use cases that deserve favorable gas cost treatment continue to receive favorable gas cost treatment, particularly:</p> <ul> <li>Anti-reentrancy locks (typically flipped from 0 to 1 right before a child call begins, and then flipped back to 0 when the child call ends)</li> <li>ERC20 approve-and-send (the "approved value" goes from zero to nonzero when the token transfer is approved, and then back to zero when the token transfer processes)</li> </ul> <p>It also preserves two key goals of EIP 3298:</p> <ol> <li>Gas tokens continue to be non-viable, because each 19000 refund is only possible because of 19000 extra gas that was paid for flipping that storage slot from zero to nonzero earlier in the same transaction, so you can't clear some storage slots and use that saved gas to fill others.</li> <li>The total amount of gas <em>spent on execution</em> is capped at the gas limit. Every 19000 refund for flipping a storage slot non from zero -&gt; zero is only possible because of 19000 extra gas paid for flipping that slot from zero -&gt; nonzero earlier in the same transaction; that gas paid for a storage write and expansion that were both reverted and so do not actually need to be applied to the Merkle tree. Hence, this extra gas does not contribute to risk.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Refunds are currently only applied <em>after</em> transaction execution, so they cannot affect how much gas is available to any particular call frame during execution. Hence, removing them will not break the ability of any code to execute, though it will render some applications economically nonviable.</p> <p>Gas tokens in particular will become valueless. DeFi arbitrage bots, which today frequently use either established gas token schemes or a custom alternative to reduce on-chain costs, would benefit from rewriting their code to remove calls to these no-longer-functional gas storage mechanisms.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="2929-gas-costs">2929 Gas Costs</h3> <p>Note, there is a difference between 'hot' and 'cold' slots. This table shows the values as of <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> assuming that all touched storage slots were already 'hot' (the difference being a one-time cost of <code>2100</code> gas).</p> <table><thead><tr><th>Code</th><th>Used Gas</th><th>Refund</th><th>Original</th><th>1st</th><th>2nd</th><th>3rd</th><th>Effective gas (after refund)</th></tr></thead><tbody> <tr><td><code>0x60006000556000600055</code></td><td>212</td><td>0</td><td>0</td><td>0</td><td>0</td><td></td><td>212</td></tr> <tr><td><code>0x60006000556001600055</code></td><td>20112</td><td>0</td><td>0</td><td>0</td><td>1</td><td></td><td>20112</td></tr> <tr><td><code>0x60016000556000600055</code></td><td>20112</td><td>19900</td><td>0</td><td>1</td><td>0</td><td></td><td>212</td></tr> <tr><td><code>0x60016000556002600055</code></td><td>20112</td><td>0</td><td>0</td><td>1</td><td>2</td><td></td><td>20112</td></tr> <tr><td><code>0x60016000556001600055</code></td><td>20112</td><td>0</td><td>0</td><td>1</td><td>1</td><td></td><td>20112</td></tr> <tr><td><code>0x60006000556000600055</code></td><td>3012</td><td>15000</td><td>1</td><td>0</td><td>0</td><td></td><td>-11988</td></tr> <tr><td><code>0x60006000556001600055</code></td><td>3012</td><td>2800</td><td>1</td><td>0</td><td>1</td><td></td><td>212</td></tr> <tr><td><code>0x60006000556002600055</code></td><td>3012</td><td>0</td><td>1</td><td>0</td><td>2</td><td></td><td>3012</td></tr> <tr><td><code>0x60026000556000600055</code></td><td>3012</td><td>15000</td><td>1</td><td>2</td><td>0</td><td></td><td>-11988</td></tr> <tr><td><code>0x60026000556003600055</code></td><td>3012</td><td>0</td><td>1</td><td>2</td><td>3</td><td></td><td>3012</td></tr> <tr><td><code>0x60026000556001600055</code></td><td>3012</td><td>2800</td><td>1</td><td>2</td><td>1</td><td></td><td>212</td></tr> <tr><td><code>0x60026000556002600055</code></td><td>3012</td><td>0</td><td>1</td><td>2</td><td>2</td><td></td><td>3012</td></tr> <tr><td><code>0x60016000556000600055</code></td><td>3012</td><td>15000</td><td>1</td><td>1</td><td>0</td><td></td><td>-11988</td></tr> <tr><td><code>0x60016000556002600055</code></td><td>3012</td><td>0</td><td>1</td><td>1</td><td>2</td><td></td><td>3012</td></tr> <tr><td><code>0x60016000556001600055</code></td><td>212</td><td>0</td><td>1</td><td>1</td><td>1</td><td></td><td>212</td></tr> <tr><td><code>0x600160005560006000556001600055</code></td><td>40118</td><td>19900</td><td>0</td><td>1</td><td>0</td><td>1</td><td>20218</td></tr> <tr><td><code>0x600060005560016000556000600055</code></td><td>5918</td><td>17800</td><td>1</td><td>0</td><td>1</td><td>0</td><td>-11882</td></tr> </tbody></table> <h3 id="with-eip-3403-partial-refunds">With EIP-3403 partial refunds</h3> <p>If refunds were to be partially removed, as specified <a rel="external" href="https://github.com/ethereum/EIPs/pull/3403/">here</a>, this would be the comparative table. <strong>This table also assumes touched storage slots were already 'hot'</strong>.</p> <table><thead><tr><th>Code</th><th>Used Gas</th><th>Refund</th><th>Original</th><th>1st</th><th>2nd</th><th>3rd</th><th>Effective gas (after refund)</th></tr></thead><tbody> <tr><td><code>0x60006000556000600055</code></td><td>212</td><td>0</td><td>0</td><td>0</td><td>0</td><td></td><td>212</td></tr> <tr><td><code>0x60006000556001600055</code></td><td>20112</td><td>0</td><td>0</td><td>0</td><td>1</td><td></td><td>20112</td></tr> <tr><td><code>0x60016000556000600055</code></td><td>20112</td><td>19000</td><td>0</td><td>1</td><td>0</td><td></td><td>1112</td></tr> <tr><td><code>0x60016000556002600055</code></td><td>20112</td><td>0</td><td>0</td><td>1</td><td>2</td><td></td><td>20112</td></tr> <tr><td><code>0x60016000556001600055</code></td><td>20112</td><td>0</td><td>0</td><td>1</td><td>1</td><td></td><td>20112</td></tr> <tr><td><code>0x60006000556000600055</code></td><td>3012</td><td>0</td><td>1</td><td>0</td><td>0</td><td></td><td>3012</td></tr> <tr><td><code>0x60006000556001600055</code></td><td>3012</td><td>0</td><td>1</td><td>0</td><td>1</td><td></td><td>3012</td></tr> <tr><td><code>0x60006000556002600055</code></td><td>3012</td><td>0</td><td>1</td><td>0</td><td>2</td><td></td><td>3012</td></tr> <tr><td><code>0x60026000556000600055</code></td><td>3012</td><td>0</td><td>1</td><td>2</td><td>0</td><td></td><td>3012</td></tr> <tr><td><code>0x60026000556003600055</code></td><td>3012</td><td>0</td><td>1</td><td>2</td><td>3</td><td></td><td>3012</td></tr> <tr><td><code>0x60026000556001600055</code></td><td>3012</td><td>0</td><td>1</td><td>2</td><td>1</td><td></td><td>3012</td></tr> <tr><td><code>0x60026000556002600055</code></td><td>3012</td><td>0</td><td>1</td><td>2</td><td>2</td><td></td><td>3012</td></tr> <tr><td><code>0x60016000556000600055</code></td><td>3012</td><td>0</td><td>1</td><td>1</td><td>0</td><td></td><td>3012</td></tr> <tr><td><code>0x60016000556002600055</code></td><td>3012</td><td>0</td><td>1</td><td>1</td><td>2</td><td></td><td>3012</td></tr> <tr><td><code>0x60016000556001600055</code></td><td>212</td><td>0</td><td>1</td><td>1</td><td>1</td><td></td><td>212</td></tr> <tr><td><code>0x600160005560006000556001600055</code></td><td>40118</td><td>19000</td><td>0</td><td>1</td><td>0</td><td>1</td><td>21118</td></tr> <tr><td><code>0x600060005560016000556000600055</code></td><td>5918</td><td>0</td><td>1</td><td>0</td><td>1</td><td>0</td><td>5918</td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <p>Refunds are not visible to transaction execution, so this should not have any impact on transaction execution logic.</p> <p>The maximum amount of gas that can be spent on execution in a block is limited to the gas limit, if we do not count zero-to-nonzero SSTOREs that were later reset back to zero. It is okay to not count those, because if such an SSTORE is reset, storage is not expanded and the client does not need to actually adjust the Merke tree; the gas consumption is refunded, but the effort normally required by the client to process those opcodes is also cancelled. <strong>Clients should make sure to not do a storage write if <code>new_value = original_value</code>; this was a prudent optimization since the beginning of Ethereum but it becomes more important now.</strong></p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast Andrei Maiborodahttps://github.com/gumb0 Matt Garnetthttps://github.com/lightclient Piotr Dobaczewskihttps://github.com/pdobacz https://wg-eips.ritovision.com/3540/

EOF is an extensible and versioned container format for EVM bytecode with a once-off validation at deploy time.

<h2 id="abstract">Abstract</h2> <p>We introduce an extensible and versioned container format for the EVM with a once-off validation at deploy time. The version described here brings the tangible benefit of code and data separation, and allows for easy introduction of a variety of changes in the future. This change relies on the reserved byte introduced by <a href="https://wg-eips.ritovision.com/3541/">EIP-3541</a>.</p> <p>To summarise, EOF bytecode has the following layout:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>magic, version, (section_kind, section_size_or_sizes)+, 0, &lt;section contents&gt;</span></span></code></pre><h2 id="motivation">Motivation</h2> <p>On-chain deployed EVM bytecode contains no pre-defined structure today. Code is typically validated in clients to the extent of <code>JUMPDEST</code> analysis at runtime, every single time prior to execution. This poses not only an overhead, but also a challenge for introducing new or deprecating existing features.</p> <p>Validating code during the contract creation process allows code versioning without an additional version field in the account. Versioning is a useful tool for introducing or deprecating features, especially for larger changes (such as significant changes to control flow, or features like account abstraction).</p> <p>The format described in this EIP introduces a simple and extensible container with a minimal set of changes required to both clients and languages, and introduces validation.</p> <p>The first tangible feature it provides is separation of code and data. This separation is especially beneficial for on-chain code validators (like those utilised by layer-2 scaling tools, such as Optimism), because they can distinguish code and data (this includes deployment code and constructor arguments too). Currently, they a) require changes prior to contract deployment; b) implement a fragile method; or c) implement an expensive and restrictive jump analysis. Code and data separation can result in ease of use and significant gas savings for such use cases. Additionally, various (static) analysis tools can also benefit, though off-chain tools can already deal with existing code, so the impact is smaller.</p> <p>A non-exhaustive list of proposed changes which could benefit from this format:</p> <ul> <li>Including a <code>JUMPDEST</code>-table (to avoid analysis at execution time) and/or removing <code>JUMPDEST</code>s entirely.</li> <li>Introducing static jumps (with relative addresses) and jump tables, and disallowing dynamic jumps at the same time.</li> <li>Multibyte opcodes without any workarounds.</li> <li>Representing functions as individual code sections instead of subroutines.</li> <li>Introducing special sections for different use cases, notably Account Abstraction.</li> </ul> <h2 id="specification">Specification</h2> <p>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>In order to guarantee that every EOF-formatted contract in the state is valid, we need to prevent already deployed (and not validated) contracts from being recognized as such format. This is achieved by choosing a byte sequence for the <em>magic</em> that doesn't exist in any of the already deployed contracts.</p> <h3 id="remarks">Remarks</h3> <p>If code starts with the <code>MAGIC</code>, it is considered to be EOF formatted, otherwise it is considered to be <em>legacy</em> code. For clarity, the <code>MAGIC</code> together with a version number <em>n</em> is denoted as the <em>EOFn prefix</em>, e.g. <em>EOF1 prefix</em>.</p> <p>EOF-formatted contracts are created using new instructions which are introduced in a separate EIP.</p> <p>The opcode <code>0xEF</code> is currently an undefined instruction, therefore: <em>It pops no stack items and pushes no stack items, and it causes an exceptional abort when executed.</em> This means legacy <em>initcode</em> or already deployed legacy <em>code</em> starting with this instruction will continue to abort execution.</p> <p>Unless otherwise specified, all integers are encoded in big-endian byte order.</p> <h3 id="code-validation">Code validation</h3> <p>We introduce <em>code validation</em> for new contract creation. To achieve this, we define a format called EVM Object Format (EOF), containing a version indicator, and a ruleset of validity tied to a given version.</p> <p>Legacy code is not affected by EOF code validation.</p> <p>Code validation is performed during contract creation, and is elaborated on in separate EIPs. The EOF format itself and its formal validation are described in the following sections.</p> <h3 id="container-specification">Container specification</h3> <p>EOF container is a binary format with the capability of providing the EOF version number and a list of EOF sections.</p> <p>The container starts with the EOF prefix:</p> <table><thead><tr><th>description</th><th>length</th><th>value</th><th></th></tr></thead><tbody> <tr><td>magic</td><td>2-bytes</td><td>0xEF00</td><td></td></tr> <tr><td>version</td><td>1-byte</td><td>0x01–0xFF</td><td>EOF version number</td></tr> </tbody></table> <p>The EOF prefix is followed by at least one section header. Each section header contains two fields, <code>section_kind</code> and either <code>section_size</code> or <code>section_size_list</code>, depending on the kind. <code>section_size_list</code> is a list of size values when multiple sections of this kind are allowed, encoded as a count of items followed by the items.</p> <table><thead><tr><th>description</th><th>length</th><th>value</th><th></th></tr></thead><tbody> <tr><td>section_kind</td><td>1-byte</td><td>0x01–0xFF</td><td><code>uint8</code></td></tr> <tr><td>section_size</td><td>2-bytes</td><td>0x0000–0xFFFF</td><td><code>uint16</code></td></tr> <tr><td>section_size_list</td><td>dynamic</td><td>n/a</td><td><code>uint16, uint16+</code></td></tr> </tbody></table> <p>The list of section headers is terminated with the <em>section headers terminator byte</em> <code>0x00</code>. The body content follows immediately after.</p> <h4 id="container-validation-rules">Container validation rules</h4> <ol> <li><code>version</code> MUST NOT be <code>0</code>.</li> <li><code>section_kind</code> MUST NOT be <code>0</code>. The value <code>0</code> is reserved for <em>section headers terminator byte</em>.</li> <li>There MUST be at least one section (and therefore section header).</li> <li>Stray bytes outside of sections MUST NOT be present. This includes trailing bytes after the last section.</li> </ol> <h3 id="eof-version-1">EOF version 1</h3> <p>EOF version 1 is made up of several EIPs, including this one. Some values in this specification are only discussed briefly. To understand the full scope of EOF, it is necessary to review each EIP in-depth.</p> <h4 id="container">Container</h4> <p>The EOF version 1 container consists of a <code>header</code> and <code>body</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>container := header, body</span></span> <span class="giallo-l"><span>header := </span></span> <span class="giallo-l"><span> magic, version, </span></span> <span class="giallo-l"><span> kind_type, type_size, </span></span> <span class="giallo-l"><span> kind_code, num_code_sections, code_size+,</span></span> <span class="giallo-l"><span> [kind_container, num_container_sections, container_size+,]</span></span> <span class="giallo-l"><span> kind_data, data_size,</span></span> <span class="giallo-l"><span> terminator</span></span> <span class="giallo-l"><span>body := types_section, code_section+, container_section*, data_section</span></span> <span class="giallo-l"><span>types_section := (inputs, outputs, max_stack_increase)+</span></span></code></pre> <p><em>note: <code>,</code> is a concatenation operator, <code>+</code> should be interpreted as "one or more" of the preceding item, <code>*</code> should be interpreted as "zero or more" of the preceding item, and <code>[item]</code> should be interpreted as an optional item.</em></p> <h4 id="header">Header</h4> <table><thead><tr><th>name</th><th>length</th><th>value</th><th>description</th></tr></thead><tbody> <tr><td>magic</td><td>2 bytes</td><td>0xEF00</td><td></td></tr> <tr><td>version</td><td>1 byte</td><td>0x01</td><td>EOF version</td></tr> <tr><td>kind_type</td><td>1 byte</td><td>0x01</td><td>kind marker for type section</td></tr> <tr><td>type_size</td><td>2 bytes</td><td>0x0004-0x1000</td><td>16-bit unsigned big-endian integer denoting the length of the type section content, 4 bytes per code section</td></tr> <tr><td>kind_code</td><td>1 byte</td><td>0x02</td><td>kind marker for code size section</td></tr> <tr><td>num_code_sections</td><td>2 bytes</td><td>0x0001-0x0400</td><td>16-bit unsigned big-endian integer denoting the number of the code sections</td></tr> <tr><td>code_size</td><td>2 bytes</td><td>0x0001-0xFFFF</td><td>16-bit unsigned big-endian integer denoting the length of the code section content</td></tr> <tr><td>kind_container</td><td>1 byte</td><td>0x03</td><td>kind marker for container size section</td></tr> <tr><td>num_container_sections</td><td>2 bytes</td><td>0x0001-0x0100</td><td>16-bit unsigned big-endian integer denoting the number of the container sections</td></tr> <tr><td>container_size</td><td>4 bytes</td><td>0x00000001-0xFFFFFFFF</td><td>32-bit unsigned big-endian integer denoting the length of the container section content</td></tr> <tr><td>kind_data</td><td>1 byte</td><td>0xFF</td><td>kind marker for data size section</td></tr> <tr><td>data_size</td><td>2 bytes</td><td>0x0000-0xFFFF</td><td>16-bit unsigned big-endian integer denoting the length of the data section content (*)</td></tr> <tr><td>terminator</td><td>1 byte</td><td>0x00</td><td>marks the end of the header</td></tr> </tbody></table> <p>(*) For not yet deployed containers this can be greater than the actual content length.</p> <h4 id="body">Body</h4> <table><thead><tr><th>name</th><th>length</th><th>value</th><th>description</th></tr></thead><tbody> <tr><td>types_section</td><td>variable</td><td>n/a</td><td>stores code section metadata</td></tr> <tr><td>inputs</td><td>1 byte</td><td>0x00-0x7F</td><td>number of stack elements the code section consumes</td></tr> <tr><td>outputs</td><td>1 byte</td><td>0x00-0x7F</td><td>number of stack elements the code section returns</td></tr> <tr><td>max_stack_increase</td><td>2 bytes</td><td>0x0000-0x03FF</td><td>maximum increase of the operand stack height by the code section</td></tr> <tr><td>code_section</td><td>variable</td><td>n/a</td><td>arbitrary bytecode</td></tr> <tr><td>container_section</td><td>variable</td><td>n/a</td><td>arbitrary EOF-formatted container</td></tr> <tr><td>data_section</td><td>variable</td><td>n/a</td><td>arbitrary sequence of bytes</td></tr> </tbody></table> <p><strong>NOTE</strong>: A special value of <code>outputs</code> being <code>0x80</code> is designated to denote non-returning functions as defined in a separate EIP.</p> <h4 id="eof-version-1-validation-rules">EOF version 1 validation rules</h4> <p>The following validity constraints are placed on the container format:</p> <ul> <li><code>types_size</code> is divisible by <code>4</code></li> <li>the number of code sections must be equal to <code>types_size / 4</code></li> <li>data body length may be shorter than <code>data_size</code> for a not yet deployed container</li> <li>the total size of a container must not exceed <code>MAX_INITCODE_SIZE</code> (as defined in <a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a>)</li> </ul> <h3 id="changes-to-execution-semantics">Changes to execution semantics</h3> <p>For an EOF contract:</p> <ul> <li>Execution starts at the first byte of code section 0</li> <li><code>CODESIZE</code>, <code>CODECOPY</code>, <code>EXTCODESIZE</code>, <code>EXTCODECOPY</code>, <code>EXTCODEHASH</code>, <code>GAS</code> are rejected by validation in EOF contracts, with no replacements</li> <li><code>CALL</code>, <code>DELEGATECALL</code>, <code>STATICCALL</code> are rejected by validation in EOF contracts, replacement instructions to be introduced in a separate EIP.</li> <li><code>DELEGATECALL</code> (or any replacement instruction for EOF) from an EOF contract to a non-EOF contract (legacy contract, EOA, empty account) is disallowed, and it should fail in the same mode as if the call depth check failed. We allow legacy to EOF path for existing proxy contracts to be able to use EOF upgrades.</li> </ul> <p>For a legacy contract:</p> <ul> <li>If the target account of <code>EXTCODECOPY</code> is an EOF contract, then it will copy up to 2 bytes from <code>EF00</code>, as if that would be the code.</li> <li>If the target account of <code>EXTCODEHASH</code> is an EOF contract, then it will return <code>0x9dbf3648db8210552e9c4f75c6a1c3057c0ca432043bd648be15fe7be05646f5</code> (the hash of <code>EF00</code>, as if that would be the code).</li> <li>If the target account of <code>EXTCODESIZE</code> is an EOF contract, then it will return 2.</li> </ul> <p><strong>NOTE</strong> Like for legacy targets, the aforementioned behavior of <code>EXTCODECOPY</code>, <code>EXTCODEHASH</code> and <code>EXTCODESIZE</code> does not apply to EOF contract targets mid-creation, i.e. those report same as accounts without code.</p> <h2 id="rationale">Rationale</h2> <p>EVM and/or account versioning has been discussed numerous times over the past years. This proposal aims to learn from them. See "Ethereum account versioning" on the Fellowship of Ethereum Magicians Forum for a good starting point.</p> <h3 id="execution-vs-creation-time-validation">Execution vs. creation time validation</h3> <p>This specification introduces creation time validation, which means:</p> <ul> <li>All created contracts with <em>EOFn</em> prefix are valid according to version <em>n</em> rules. This is very strong and useful property. The client can trust that the deployed code is well-formed.</li> <li>In the future, this allows to serialize <code>JUMPDEST</code> map in the EOF container and eliminate the need of implicit <code>JUMPDEST</code> analysis required before execution.</li> <li>Or to completely remove the need for <code>JUMPDEST</code> instructions.</li> <li>This helps with deprecating EVM instructions and/or features.</li> <li>The biggest disadvantage is that deploy-time validation of EOF code must be enabled in two hard-forks. However, the first step (<a href="https://wg-eips.ritovision.com/3541/">EIP-3541</a>) is already deployed in London.</li> </ul> <p>The alternative is to have execution time validation for EOF. This is performed every single time a contract is executed, however clients may be able to cache validation results. This <em>alternative</em> approach has the following properties:</p> <ul> <li>Because the validation is consensus-level execution step, it means the execution always requires the entire code. This makes <em>code merkleization impractical</em>.</li> <li>Can be enabled via a single hard-fork.</li> <li>Better backwards compatibility: data contracts starting with the <code>0xEF</code> byte or the <em>EOF prefix</em> can be deployed. This is a dubious benefit, however.</li> </ul> <h3 id="the-magic">The MAGIC</h3> <ol> <li> <p>The first byte <code>0xEF</code> was chosen because it is reserved for this purpose by <a href="https://wg-eips.ritovision.com/3541/">EIP-3541</a>.</p> </li> <li> <p>The second byte <code>0x00</code> was chosen to avoid clashes with three contracts which were deployed on <strong>Mainnet</strong>:</p> <ul> <li><code>0xca7bf67ab492b49806e24b6e2e4ec105183caa01</code>: <code>EFF09f918bf09f9fa9</code></li> <li><code>0x897da0f23ccc5e939ec7a53032c5e80fd1a947ec</code>: <code>EF</code></li> <li><code>0x6e51d4d9be52b623a3d3a2fa8d3c5e3e01175cd0</code>: <code>EF</code></li> </ul> </li> <li> <p>No contracts starting with <code>0xEF</code> bytes exist on public testnets: Goerli, Ropsten, Rinkeby, Kovan and Sepolia at their London fork block.</p> </li> </ol> <p><strong>NOTE</strong>: This EIP MUST NOT be enabled on chains which contain bytecodes starting with <code>MAGIC</code> and not being valid EOF.</p> <h3 id="eof-version-range-start-with-1">EOF version range start with 1</h3> <p>The version number 0 will never be used in EOF, so we can call legacy code <em>EOF0</em>. Also, implementations may use APIs where 0 version number denotes legacy code.</p> <h3 id="section-structure">Section structure</h3> <p>We have considered different questions for the sections:</p> <ul> <li>Streaming headers (i.e. <code>section_header, section_data, section_header, section_data, ...</code>) are used in some other formats (such as WebAssembly). They are handy for formats which are subject to editing (adding/removing sections). That is not a useful feature for EVM. One minor benefit applicable to our case is that they do not require a specific "header terminator". On the other hand they seem to play worse with code chunking / merkleization, as it is better to have all section headers in a single chunk.</li> <li>Whether to have a header terminator or to encode <code>number_of_sections</code> or <code>total_size_of_headers</code>. Both raise the question of how large of a value these fields should be able to hold. A terminator byte seems to avoid the problem of choosing a size which is too small without any perceptible downside, so it is the path taken.</li> <li>(EOF1) Whether to encode section sizes as fixed 16-bit (32-bit for container section size) values or some kind of variable length field (e.g. LEB128). We have opted for fixed size. Should this be limiting in the future, a new EOF version could change the format. Besides simplifying client implementations, not using LEB128 also greatly simplifies on-chain parsing.</li> <li>Whether or not to have more structure to the container header for all EOF versions to follow. In order to allow future formats optimized for chunking and merkleization (verkleization) it was decided to keep it generic and specify the structure only for a specific EOF version.</li> </ul> <h3 id="data-only-contracts">Data-only contracts</h3> <p>See section <a href="https://wg-eips.ritovision.com/7480/#lack-of-extdatacopy">Lack of <code>EXTDATACOPY</code> in EIP-7480</a>.</p> <h3 id="eof1-contracts-can-only-delegatecall-eof1-contracts">EOF1 contracts can only <code>DELEGATECALL</code> EOF1 contracts</h3> <p>Currently contracts can selfdestruct in three different ways (directly through <code>SELFDESTRUCT</code>, indirectly through <code>CALLCODE</code> and indirectly through <code>DELEGATECALL</code>). <a href="https://wg-eips.ritovision.com/3670/">EIP-3670</a> disables the first two possibilities, however the third possibility remains. Allowing EOF1 contracts to only <code>DELEGATECALL</code> other EOF1 contracts allows the following strong statement: EOF1 contract can never be destructed. Attacks based on <code>SELFDESTRUCT</code> completely disappear for EOF1 contracts. These include destructed library contracts (e.g. Parity Multisig).</p> <h3 id="eof1-containers-have-a-size-limit">EOF1 containers have a size limit</h3> <p>Imposing an EOF-validation time limit for the size of EOF containers provides a reference limit of how large the containers should EVM implementations be able to handle when validating and processing containers. <code>MAX_INITCODE_SIZE</code> was chosen for EOF1, as it is what contract creation currently allows for.</p> <p>Given one of the main reasons for the limit is to avoid attack vectors on <code>JUMPDEST</code>-analysis, and EOF removes the need for <code>JUMPDEST</code>-analysis and introduces a cost structure for deploy-time analysis, in the future this limit could be increased or even lifted for EOF.</p> <h3 id="kind-data-could-be-0x04-not-0xff"><code>kind_data</code> could be <code>0x04</code> not <code>0xff</code></h3> <p>Putting the data section last as <code>0xff</code> has the advantage of aligning with the fact that it always comes last. We're avoiding a situation that a new section kind would need to go before the data section and break the section kind ordering. At the same time, data section being last is advantageous because it is the section which gets data appended to during contract deployment.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a breaking change given that any code starting with <code>0xEF</code> was not deployable before (and resulted in exceptional abort if executed), but now some subset of such codes can be deployed and executed successfully.</p> <p>The choice of <code>MAGIC</code> guarantees that none of the contracts existing on the chain are affected by the new rules.</p> <h2 id="security-considerations">Security Considerations</h2> <p>With the anticipated EOF extensions, the validation is expected to have linear computational and space complexity. We think that the validation cost is sufficiently covered by:</p> <ul> <li><a href="https://wg-eips.ritovision.com/3860/">EIP-3860</a> for <em>initcode</em>,</li> <li>high per-byte cost of deploying <em>code</em>.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 mineruniter969https://github.com/mineruniter969 mineruniter969mineruniter969@tutanota.com https://wg-eips.ritovision.com/3372/ <h2 id="simple-summary">Simple Summary</h2> <p>Introduce 5 new FNV primes into the ethash algorithm.</p> <h2 id="abstract">Abstract</h2> <p>This EIP is to kick current ASIC implementations out of the network to keep the Ethereum network secure and healthy by changing the <code>fnv</code> constants.</p> <h2 id="motivation">Motivation</h2> <p>ASICs provide a severe centralization risk for the Ethereum network. If we do not get rid of them, small GPU miners will be forced to exit the Ethereum mining because EIP-1559 will make them mining at a loss. Furthermore, ASIC production will be concentrated only at one or two parties, which will make the Ethereum hashrate centralized. Also, it is worth noting that Ethash ASIC machines cost 10k+ USD, while GPUs are priced less than 1000 USD.</p> <p>With GPUs, miners can switch to other mining algorithms, but with ASICs, it is impossible. Leaving everything as-is will almost certainly a very tough (from the side of miners) integration of the Ethereum 2.0.</p> <p>In short, this EIP is required to keep the Ethereum network stable and decentralized by keeping the ASIC business away.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= ETHASH11_BLKNUM</code>, activate the <code>ethash1.1</code> algorithm version.</p> <h3 id="ethash1-1">ethash1.1</h3> <p>Prior to this change, <code>fnv</code> hash function is used throughout the <code>hashimoto</code> function. <code>fnv</code> is identical for all steps, <code>ethash1.1</code> will introduce additional <code>fnvA</code>, <code>fnvB</code>, <code>fnvC</code>, <code>fnvD</code>, and <code>fnvE</code> functions. All those functions will have different FNV constants.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>// Previously used FNV prime</span></span> <span class="giallo-l"><span>#define FNV_PRIME_0 0x1000193</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// New FNV primes</span></span> <span class="giallo-l"><span>#define FNV_PRIME_A 0x10001a7</span></span> <span class="giallo-l"><span>#define FNV_PRIME_B 0x10001ab</span></span> <span class="giallo-l"><span>#define FNV_PRIME_C 0x10001cf</span></span> <span class="giallo-l"><span>#define FNV_PRIME_D 0x10001e3</span></span> <span class="giallo-l"><span>#define FNV_PRIME_E 0x10001f9</span></span></code></pre> <p>Prior to this EIP, all parts of Ethash are using the <code>fnv</code> (hereinafter referenced as <code>fnv0</code>) function. As of the introduction of this EIP:</p> <ul> <li><code>fnvA</code> replaces <code>fnv0</code> in the DAG item selection step</li> <li><code>fnvB</code> replaces <code>fnv0</code> in the DAG item mix step</li> <li><code>fnvC(fnvD(fnvE</code> replaces <code>fnv0(fnv0(fnv0(</code> in the compress mix step</li> <li><code>fnv0</code> in the DAG generation step should remain unchanged.</li> </ul> <h2 id="rationale">Rationale</h2> <p>ASIC Miners have become a threat to the future of Ethereum and a hard fork is required to remove them from the network before additional damage is caused. EIP-3372 proposes the minimum necessary to do so and will not affect ETH stakeholders or the network like Ethash 2.0 would. The threat ASICs pose is legal, social, moral, technical, monetary, and environmental. As we continue to come closer to the merge ASICs will attack the network and the developers personally as they have done in the past because miners will always pursue profits.</p> <p>Legally and socially ASIC's have previously been a threat and a nuisance. As Hudson describes Linzhi attacked the EF and developers personally seeking to spread lies and misinformation while sending legal threats during discussions around EIP-1057. His account is <a rel="external" href="https://github.com/Souptacular/linzhi">here</a> and in his own words</p> <blockquote> <p>ASIC manufacturer Linzhi has both pressured me and told lies</p> </blockquote> <p>With their attacks and harassment on staff demonstrated in the below image: <img src="upload://n8TJsS8hEEH4DXYJ2WDzblm5qJo.jpeg" alt="" /></p> <p>Socially and morally the Ethereum community must adopt a no-tolerance policy towards personal attacks on its developers. It is only because of the core developers that Ethereum has value, the community cannot allow large companies free reign to attack them personally and must seek to protect each developer as they are a resource that keeps Ethereum viable. Multiple developers were "burned" during this event. As we accelerate the merge, it is likely that ASIC companies will repeat their actions and again attack the developers personally while pursuing legal options. This is seen not only by their actions during EIP-1057 but recent discussion around EIP-969 where legal threats from them caused the champion of that EIP to dropout and forcing me to submit this EIP anonymously. Ethereum cannot allow its actors to be threatened without consequence and this is a fight that must happen now while they are weak rather than pre-merge where they are stronger which will result in a delayed merge and hurt the value of Ethereum.</p> <p>ASICs have the greatest incentives and resources to commit bad acts because they are centralized in farms this is why Vitalik designed ETH to be ASIC-resistant because ASICs had ruined BTC's principles of decentralization. Each day their power and control over the network grows. ASICs are against the founding principles of Ethereum which promotes a decentralized system run by common people, not a single owner of large warehouses. F2Pool which consists largely of ASIC farms has become the #3 largest pool controlling around 10% of hashrate. Their farms can be viewed on their webpage. In November 2020 they were 23TH/s yet today they are 45.6 TH/s. That's a doubling in 4 months and their growth is accelerating as additional ASICs come online. ASICs are becoming a threat that will soon dominate the network and action must be taken now to head them off.</p> <p>ASICs on F2Pool have long been known to be "bad actors" on the BTC network. They are known for market manipulation and dumping BTC to manipulate prices (I could not post the source link as this is a new account). What will these ASICs do once they find out that they are about to lose millions prior to the merge? Ethereum is not just a network it is a community and they will use their financial resources and pour millions into delaying the merge as they launch legal case after legal case. They will attack the developers and the community as they seek to squeeze every last dollar.</p> <p>The reason Ethereum was founded on the principle of being anti-ASIC is because Vitalik had seen the damage ASICs had caused to the BTC network as they pursued profits rather than the betterment of the network. GPU miners are decentralized and disorganized which makes them a much lower threat than warehouses under one central corporation that is outside the legal system and thus cannot be held to account for bad acts.</p> <p>EIP-3372 also works to protect the environment. Post merge, gpus will go into the secondary market or move to other coins. However, ASICs will become junk. As more ASICs are produced, Ethereum increases its environmental footprint. These ASICs are being mass produced in greater numbers despite it being public that the merge is being accelerated. It is clear that these ASIC manufacturers and buyers must either be ignorant of the accelerated merge or plan to delay it. Because they dump their ETH they have no stake in the network except the money they can squeeze from it and if by making trouble they can give themselves another day than they will do it.</p> <p>Finally, Ethereum has always sought to pursue "minimum issuance". By reducing the amount of miners that can pose a threat to the network, Ethereum also decreases how much it needs to pay for protection. Some EIP's are being prepared to increase miner incomes post EIP-1559 should a threat appear. EIP-3372 eliminates the need to pay more for security and allows miners to be paid less without compromising the network's security. As we go forward closer to the merge, the community must reduce attack vectors so as to reduce the cost of the merge itself and maximize the security of the network. The community already pays too much for protection and by reducing threats we can reduce this cost. ASIC warehouse farms are dumping all the ETH they make which is suppressing the price of ETH. Although rare, several individual GPU miners are taking part in staking or have gone on to join the community in development or our financial endeavors. They thus are more valuable to the community than a warehouse of future junk. There is no need for the Ethereum community to continue to pay for soon-to-be obsolete hardware that will end up in landfills.</p> <h3 id="technical-overview">Technical Overview</h3> <p>Ethash 1.1 will replace the only FNV prime with five new primes at the stage of the hash computation. The prime used for the DAG generation is remained unchanged, while all others are be changed. This will not prevent ASIC companies from creating new ASICs that adapt but so close to the merge it is unlikely they will do so, and even if they do they are unlikely to be able to produce enough to again be a threat. The choice of FNV constants are based on the formal specification that is available on <a rel="external" href="https://ietf">https://tools.ietf.org/html/draft-eastlake-fnv-14#section-2.1</a></p> <p>We apologize for the delay in submitting the justification for this EIP. As the community may or may not be aware, the original champion was forced to stop working on this EIP due to legal attacks from ASIC companies. It has taken us this long to review his work and find a new champion. To protect ourselves we are submitting this anonymously and would request the community's aid in our endeavor to maintain our anonymity and some lenience given the circumstances and threats we face pursuing this EIP.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Mining hardware that is optimized for ethash may no longer work if the <code>fnv</code> constants are baked into the hardware and cannot be changed.</p> <h2 id="test-vectors">Test Vectors</h2> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">first</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nonce</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">4242424242424242</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">mixHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">aa6a928db9b548ebf20fc9a74e9200321426f1c2db1571636cdd3a33eb162b36</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">header</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">f901f3a00000000000000000000000000000000000000000000000000000000000000000a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347940000000000000000000000000000000000000000a09178d0f23c965d81f0834a4c72c6253ce6830f4022b1359aaebfc1ecba442d4ea056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421b90100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008302000080830f4240808080a058f759ede17a706c93f13030328bcea40c1d1341fb26f2facd21ceb0dae57017884242424242424242</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">seed</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">3972318778d2af9d3c5c3dfc463bc2a5ebeebd1a7a04392708ff94d29aa18c5f</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">cache_size</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 16776896</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">full_size</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1073739904</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">header_hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2a8de2adf89af77358250bf908bf04ba94a6e8c3ba87775564a41d269a05e4ce</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">cache_hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">35ded12eecf2ce2e8da2e15c06d463aae9b84cb2530a00b932e4bbc484cde353</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">second</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nonce</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">307692cf71b12f6d</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">mixHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">4a2ef8287dc21f5def0d4e9694208c56e574b1692d7b254822a3f4704d8ad1ba</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">header</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">f901f7a01bef91439a3e070a6586851c11e6fd79bbbea074b2b836727b8e75c7d4a6b698a01dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d4934794ea3cb5f94fa2ddd52ec6dd6eb75cf824f4058ca1a00c6e51346be0670ce63ac5f05324e27d20b180146269c5aab844d09a2b108c64a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421a056e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421b90100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008302004002832fefd880845511ed2a80a0e55d02c555a7969361cf74a9ec6211d8c14e4517930a00442f171bdb1698d17588307692cf71b12f6d</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">seed</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">5ab98957ba5520d4e367080f442e37a047cfd9d2857b6e00dd12d82900d108a6</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">cache_size</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 16776896</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">full_size</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1073739904</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">header_hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">100cbec5e5ef82991290d0d93d758f19082e71f234cf479192a8b94df6da6bfe</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">cache_hash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">35ded12eecf2ce2e8da2e15c06d463aae9b84cb2530a00b932e4bbc484cde353</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>There are no known security issues with this change.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 Michael D. Carterhttps://github.com/BitsBeTrippin https://wg-eips.ritovision.com/3368/ <h2 id="simple-summary">Simple Summary</h2> <p>Changes the block reward paid to proof-of-work (POW) miners to 3 ETH from existing 2 ETH and starts a decay schedule for next two years to 1 ETH Block Reward.</p> <h2 id="abstract">Abstract</h2> <p>Set the block reward to 3 ETH and then decrease it slightly every block for 4,724,000 blocks (approximately 2 years) until it reaches 1 ETH.</p> <h2 id="motivation">Motivation</h2> <p>A sudden drop in PoW mining rewards could result in a sudden precipitous decrease in mining profitability that may drive miners to auction off their hashrate to the highest bidder while they figure out what to do with their now "worthless" hardware. If enough hashrate is auctioned off in this way at the same time, an attacker will be able to rent a large amount of hashing power for a short period of time at relatively low cost vs. reward and potentially attack the network. By setting the block reward to X (where X is enough to offset the sudden profitability decrease) and then decreasing it over time to Y (where Y is a number below the sudden profitability decrease), we both avoid introducing long term inflation while at the same time spreading out the rate that individual miners cross into a transitional range. This approach offers a higher level of confidence and published schedule of yield, while allowing mining participants time to gracefully repurpose/sell their hardware. This greatly increases ethereums PoW security by keeping incentives aligned to ethereum and not being force projected to short term brokerage for the highest bidder. Additionally the decay promotes a known schedule of a deflationary curve, aligning to the overall Minimal Viable Issuance directive aligned to a 2 year transition schedule for Proof of Stake, consensus replacement of Proof of Work. Security is paramount in cryptocurrency blockchains and the risk to a 51% non-resistant chain is real. The scope of Ethereum's current hashrate has expanded to hundreds of thousands of new participants and over 2.5x original ATH hashrate/difficulty. While the largest by hashrate crypto is bitcoin, ethereum is not far behind the total network size in security aspects. This proposal is focused to keep that superiority in security one of the key aspects.</p> <h2 id="specification">Specification</h2> <p>Adjust block, uncle, and nephew rewards</p> <h3 id="constants">Constants</h3> <ul> <li><code>TRANSITION_START_BLOCK_NUMBER: TBD</code></li> <li><code>TRANSITION_DURATION: 4_724_000</code> (about two years)</li> <li><code>TRANSITION_END_BLOCK_NUMBER: FORK_BLOCK_NUMBER + TRANSITION_DURATION</code></li> <li><code>STARTING_REWARD: 3_000_000_000_000_000_000</code></li> <li><code>ENDING_REWARD: 1_000_000_000_000_000_000</code></li> <li><code>REWARD_DELTA: STARTING_REWARD - ENDING_REWARD</code></li> </ul> <h3 id="block-reward">Block Reward</h3> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">if</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> TRANSITION_END_BLOCK_NUMBER</span><span>:</span></span> <span class="giallo-l"><span> block_reward</span><span class="z-keyword"> =</span><span class="z-constant"> ENDING_REWARD</span></span> <span class="giallo-l"><span class="z-keyword">elif</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> =</span><span class="z-constant"> TRANSITION_START_BLOCK_NUMBER</span><span>:</span></span> <span class="giallo-l"><span> block_reward</span><span class="z-keyword"> =</span><span class="z-constant"> STARTING_REWARD</span></span> <span class="giallo-l"><span class="z-keyword">elif</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> &gt;</span><span class="z-constant"> TRANSITION_START_BLOCK_NUMBER</span><span>:</span></span> <span class="giallo-l"><span> block_reward</span><span class="z-keyword"> =</span><span class="z-constant"> STARTING_REWARD</span><span class="z-keyword"> -</span><span class="z-constant"> REWARD_DELTA</span><span class="z-keyword"> *</span><span class="z-constant"> TRANSITION_DURATION</span><span class="z-keyword"> /</span><span> (</span><span>block</span><span>.</span><span>number</span><span class="z-keyword"> -</span><span class="z-constant"> TRANSITION_START_BLOCK_NUMBER</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>2 years was chosen because it gives miners sufficient time to find alternative uses for their hardware and/or get their hardware back out onto the open market (e.g., in the form of gaming GPUs) without flooding the market suddenly. This proposal should ONLY be considered as a last resort as something we have in our pocket should the "network need to attract hashing power quickly and then bleed it off over time" rather than "something that is scheduled to be included in X hard fork" ; Recommendation to have in a fast track state, but NOT deployed to mainnet unless needed.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no known backward compatibility issues with the introduction of this EIP.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no known security issues with the introduction of this EIP.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> 2021-03-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Calvin Koderhttps://github.com/ashrowz https://wg-eips.ritovision.com/3386/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for contracts that create generic ERC-20 tokens which derive from a pool of unique ERC-721/ERC-1155 tokens.</p> <h2 id="abstract">Abstract</h2> <p>This standard outlines a smart contract interface to wrap identifiable tokens with fungible tokens. This allows for derivative <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens to be minted by locking the base <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> non-fungible tokens and <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> multi tokens into a pool. The derivative tokens can be burned to redeem base tokens out of the pool. These derivatives have no reference to the unique id of these base tokens, and should have a proportional rate of exchange with the base tokens. As representatives of the base tokens, these generic derivative tokens can be traded and otherwise utilized according to ERC-20, such that the unique identifier of each base token is irrelevant.</p> <p>ERC-721 and ERC-1155 tokens are considered valid base, tokens because they have unique identifiers and are transferred according to similar rules. This allows for both ERC-721 NFTs and ERC-1155 Multi-Tokens to be wrapped under a single common interface.</p> <h2 id="motivation">Motivation</h2> <p>The ERC-20 token standard is the most widespread and liquid token standard on Ethereum. ERC-721 and ERC-1155 tokens on the other hand can only be transferred by their individual ids, in whole amounts. Derivative tokens allow for exposure to the base asset while benefiting from contracts which utilize ERC-20 tokens. This allows for the base tokens to be fractionalized, traded and pooled generically on AMMs, collateralized, and be used for any other ERC-20 type contract. Several implementations of this proposal already exist without a common standard.</p> <p>Given a fixed exchange rate between base and derivative tokens, the value of the derivative token is proportional to the floor price of the pooled tokens. With the derivative tokens being used in AMMs, there is opportunity for arbitrage between derived token markets and the base NFT markets. By specifying a subset of base tokens which may be pooled, the difference between the lowest and highest value token in the pool may be minimized. This allows for higher value tokens within a larger set to be poolable. Additionally, price calculations using methods such as Dutch auctions, as implemented by NFT20, allow for price discovery of subclasses of base tokens. This allows the provider of a higher value base token to receive a proportionally larger number of derivative tokens than a token worth the floor price would receive.</p> <h2 id="specification">Specification</h2> <p>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 <a rel="external" href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a>.</p> <p><strong>Every IWrapper compliant contract must implement the <code>IWrapper</code> and <code>ERC165</code> interfaces</strong> :</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @title</span><span class="z-comment"> IWrapper Identifiable Token Wrapper Standard</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> {Wrapper} refers to any contract implementing this interface.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> {Base} refers to any ERC-721 or ERC-1155 contract. It MAY be the {Wrapper}.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> {Pool} refers to the contract which holds the {Base} tokens. It MAY be the {Wrapper}.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> {Derivative} refers to the ERC-20 contract which is minted/burned by the {Wrapper}. It MAY be the {Wrapper}.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> All uses of &quot;single&quot;, &quot;batch&quot; refer to the number of token ids. This includes individual ERC-721 tokens by id, and multiple ERC-1155 by id. An ERC-1155 `TransferSingle` event may emit with a `value` greater than `1`, but it is still considered a single token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> All parameters named `_amount`, `_amounts` refer to the `value` parameters in ERC-1155. When using this interface with ERC-721, `_amount` MUST be 1, and `_amounts` MUST be either an empty list or a list of 1 with the same length as `_ids`.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IWrapper</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST emit when a mint occurs where a single {Base} token is received by the {Pool}.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_from` argument MUST be the address of the account that sent the {Base} token.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_to` argument MUST be the address of the account that received the {Derivative} token(s).</span></span> <span class="giallo-l"><span class="z-comment"> * The `_id` argument MUST be the id of the {Base} token transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_amount` argument MUST be the number of {Base} tokens transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_value` argument MUST be the number of {Derivative} tokens minted.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MintSingle</span><span> (</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _id</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _amount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST emit when a mint occurs where multiple {Base} tokens are received by the {Wrapper}.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_from` argument MUST be the address of the account that sent the {Base} tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_to` argument MUST be the address of the account that received the {Derivative} token(s).</span></span> <span class="giallo-l"><span class="z-comment"> * The `_ids` argument MUST be the list ids of the {Base} tokens transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_amounts` argument MUST be the list of the numbers of {Base} tokens transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_value` argument MUST be the number of {Derivative} tokens minted.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> MintBatch</span><span> (</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> _ids</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> _amounts</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST emit when a burn occurs where a single {Base} token is sent by the {Wrapper}.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_from` argument MUST be the address of the account that sent the {Derivative} token(s).</span></span> <span class="giallo-l"><span class="z-comment"> * The `_to` argument MUST be the address of the account that received the {Base} token.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_id` argument MUST be the id of the {Base} token transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_amount` argument MUST be the number of {Base} tokens transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_value` argument MUST be the number of {Derivative} tokens burned.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> BurnSingle</span><span> (</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _id</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _amount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> MUST emit when a mint occurs where multiple {Base} tokens are sent by the {Wrapper}.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_from` argument MUST be the address of the account that sent the {Derivative} token(s).</span></span> <span class="giallo-l"><span class="z-comment"> * The `_to` argument MUST be the address of the account that received the {Base} tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_ids` argument MUST be the list of ids of the {Base} tokens transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_amounts` argument MUST be the list of the numbers of {Base} tokens transferred.</span></span> <span class="giallo-l"><span class="z-comment"> * The `_value` argument MUST be the number of {Derivative} tokens burned.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> BurnBatch</span><span> (</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> _ids</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> _amounts</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Transfers the {Base} token with `_id` from `msg.sender` to the {Pool} and mints {Derivative} token(s) to `_to`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Target address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> Id of the {Base} token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _amount</span><span class="z-comment"> Amount of the {Base} token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {MintSingle} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mint</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _amount</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Transfers `_amounts[i]` of the {Base} tokens with `_ids[i]` from `msg.sender` to the {Pool} and mints {Derivative} token(s) to `_to`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Target address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _ids</span><span class="z-comment"> Ids of the {Base} tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _amounts</span><span class="z-comment"> Amounts of the {Base} tokens.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a {MintBatch} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> batchMint</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _ids</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _amounts</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Burns {Derivative} token(s) from `_from` and transfers `_amounts` of some {Base} token from the {Pool} to `_to`. No guarantees are made as to what token is withdrawn.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> Source address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Target address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _amount</span><span class="z-comment"> Amount of the {Base} tokens.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits either a {BurnSingle} or {BurnBatch} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> burn</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _amount</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Burns {Derivative} token(s) from `_from` and transfers `_amounts` of some {Base} tokens from the {Pool} to `_to`. No guarantees are made as to what tokens are withdrawn.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> Source address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Target address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _amounts</span><span class="z-comment"> Amounts of the {Base} tokens.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits either a {BurnSingle} or {BurnBatch} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> batchBurn</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _amounts</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Burns {Derivative} token(s) from `_from` and transfers `_amounts[i]` of the {Base} tokens with `_ids[i]` from the {Pool} to `_to`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> Source address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Target address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> Id of the {Base} token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _amount</span><span class="z-comment"> Amount of the {Base} token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits either a {BurnSingle} or {BurnBatch} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> idBurn</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _amount</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Burns {Derivative} tokens from `_from` and transfers `_amounts[i]` of the {Base} tokens with `_ids[i]` from the {Pool} to `_to`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> Source address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> Target address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _ids</span><span class="z-comment"> Ids of the {Base} tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _amounts</span><span class="z-comment"> Amounts of the {Base} tokens.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits either a {BurnSingle} or {BurnBatch} event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> batchIdBurn</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _ids</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _amounts</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="naming">Naming</h3> <p>The ERC-721/ERC-1155 tokens which are pooled are called {Base} tokens. Alternative names include:</p> <ul> <li>Underlying.</li> <li>NFT. However, ERC-1155 tokens may be considered "semi-fungible".</li> </ul> <p>The ERC-20 tokens which are minted/burned are called {Derivative} tokens. Alternative names include:</p> <ul> <li>Wrapped.</li> <li>Generic.</li> </ul> <p>The function names <code>mint</code> and <code>burn</code> are borrowed from the minting and burning extensions to ERC-20. Alternative names include:</p> <ul> <li><code>mint</code>/<code>redeem</code> (<a rel="external" href="https://nftx.org">NFTX</a>)</li> <li><code>deposit</code>/<code>withdraw</code> (<a rel="external" href="https://wrappedkitties.com/">WrappedKitties</a>)</li> <li><code>wrap</code>/<code>unwrap</code> (<a rel="external" href="https://etherscan.io/address/0x7c40c393dc0f283f318791d746d894ddd3693572">MoonCatsWrapped</a>)</li> </ul> <p>The function names <code>*idBurn</code> are chosen to reduce confusion on what is being burned. That is, the {Derivative} tokens are burned in order to redeem the id(s).</p> <p>The wrapper/pool itself can be called an "Index fund" according to NFTX, or a "DEX" according to <a rel="external" href="https://nft20.io">NFT20</a>. However, the {NFT20Pair} contract allows for direct NFT-NFT swaps which are out of the scope of this standard.</p> <h3 id="minting">Minting</h3> <p>Minting requires the transfer of the {Base} tokens into the {Pool} in exchange for {Derivative} tokens. The {Base} tokens deposited in this way MUST NOT be transferred again except through the burning functions. This ensures the value of the {Derivative} tokens is representative of the value of the {Base} tokens.</p> <p>Alternatively to transferring the {Base} tokens into the {Pool}, the tokens may be locked as collateral in exchange for {Derivative} loans, as proposed in NFTX litepaper, similarly to Maker vaults. This still follows the general minting pattern of removing transferability of the {Base} tokens in exchange for {Derivative} tokens.</p> <h3 id="burning">Burning</h3> <p>Burning requires the transfer of {Base} tokens out of the {Pool} in exchange for burning {Derivative} tokens. The burn functions are distinguished by the quantity and quality of {Base} tokens redeemed.</p> <ul> <li>For burning without specifying the <code>id</code>: <code>burn</code>, <code>batchBurn</code>.</li> <li>For burning with specifying the <code>id</code>(s): <code>idBurn</code>, <code>batchIdBurn</code>.</li> </ul> <p>By allowing for specific ids to be targeted, higher value {Base} tokens may be selected out of the pool. NFTX proposes an additional fee to be applied for such targeted withdrawals, to offset the desire to drain the {Pool} of {Base} tokens worth more than the floor price.</p> <h3 id="pricing">Pricing</h3> <p>Prices should not be necessarily fixed. therefore, Mint/Burn events MUST include the ERC-20 <code>_value</code> minted/burned.</p> <p>Existing pricing implementations are as follows (measured in base:derivative):</p> <ul> <li>Equal: Every {Base} costs 1 {Derivative} <ul> <li>NFTX</li> <li>Wrapped Kitties</li> </ul> </li> <li>Proportional <ul> <li>NFT20 sets a fixed rate of 100 {Base} tokens per {Derivative} token.</li> </ul> </li> <li>Variable <ul> <li>NFT20 also allows for Dutch auctions when minting.</li> <li>NFTX proposes an additional fee to be paid when targeting the id of the {Base} token.</li> </ul> </li> </ul> <p>Due to the variety of pricing implementations, the Mint* and Burn* events MUST include the number {Derivative} tokens minted/burned.</p> <h3 id="inheritance">Inheritance</h3> <h4 id="erc-20">ERC-20</h4> <p>The {Wrapper} MAY inherit from {ERC20}, in order to directly call <code>super.mint</code> and <code>super.burn</code>. If the {Wrapper} does not inherit from {ERC20}, the {Derivative} contract MUST be limited such that the {Wrapper} has the sole power to <code>mint</code>, <code>burn</code>, and otherwise change the supply of tokens.</p> <h4 id="erc721receiver-erc1155receiver">ERC721Receiver, ERC1155Receiver</h4> <p>If not inheriting from {ERC721Receiver} and/or {ERC1155Receiver}, the pool MUST be limited such that the base tokens can only be transferred via the Wrapper's <code>mint</code>, <code>burn</code>.</p> <p>There exists only one of each ERC-721 token of with a given (address, id) pair. However, ERC-1155 tokens of a given (address, id) may have quantities greater than 1. Accordingly, the meaning of "Single" and "Batch" in each standard varies. In both standards, "single" refers to a single id, and "batch" refers to multiple ids. In ERC-1155, a single id event/function may involve multiple tokens, according to the <code>value</code> field.</p> <p>In building a common set of events and functions, we must be aware of these differences in implementation. The current implementation treats ERC-721 tokens as a special case where, in reference to the quantity of each {Base} token:</p> <ul> <li>All parameters named <code>_amount</code>, MUST be <code>1</code>.</li> <li>All parameters named <code>_amounts</code> MUST be either an empty list or a list of <code>1</code> with the same length as <code>_ids</code>.</li> </ul> <p>This keeps a consistent enumeration of tokens along with ERC-1155. Alternative implementations include:</p> <ul> <li>A common interface with specialized functions. EX: <code>mintFromERC721</code>.</li> <li>Separate interfaces for each type. EX: <code>ERC721Wrapper</code>, <code>ERC1155Wrapper</code>.</li> </ul> <h4 id="erc721-erc1155">ERC721, ERC1155</h4> <p>The {Wrapper} MAY inherit from {ERC721} and/or {ERC1155} in order to call <code>super.mint</code>, directly. This is optional as minting {Base} tokens is not required in this standard. An "Initial NFT Offering" could use this to create a set of {Base} tokens within the contract, and directly distribute {Derivative} tokens.</p> <p>If the {Wrapper} does not inherit from {ERC721} or {ERC1155}, it MUST include calls to {IERC721} and {IERC1155} in order to transfer {Base} tokens.</p> <h3 id="approval">Approval</h3> <p>All of the underlying transfer methods are not tied to the {Wrapper}, but rather call the ERC-20/721/1155 transfer methods. Implementations of this standard MUST:</p> <ul> <li>Either implement {Derivative} transfer approval for burning, and {Base} transfer approval for minting.</li> <li>Or check for Approval outside of the {Wrapper} through {IERC721} / {IERC1155} before attempting to execute.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Most existing implementations inherit from ERC-20, using functions <code>mint</code> and <code>burn</code>. Events:</p> <ul> <li> <p>Mint</p> <ul> <li>WK: DepositKittyAndMintToken</li> <li>NFTX: Mint</li> </ul> </li> <li> <p>Burn</p> <ul> <li>WK: BurnTokenAndWithdrawKity</li> <li>NFTX: Redeem</li> </ul> </li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p><a rel="external" href="https://github.com/ashrowz/erc-3386">ERC-3386 Reference Implementation</a></p> <h2 id="security-considerations">Security Considerations</h2> <p>Wrapper contracts are RECOMMENDED to inherit from burnable ERC-20 tokens. If they are not, the supply of the {Derivative} tokens MUST be controlled by the Wrapper. Similarly, price implementations MUST ensure that the supply of {Base} tokens is reflected by the {Derivative} tokens.</p> <p>With the functions <code>idBurn</code>, <code>idBurns</code>, users may target the most valuable NFT within the generic lot. If there is a significant difference between tokens values of different ids, the contract SHOULD consider creating specialized pools (NFTX) or pricing (NFT20) to account for this.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Nick Johnsonhttps://github.com/arachnid https://wg-eips.ritovision.com/3336/ <h2 id="simple-summary">Simple Summary</h2> <p>Changes the memory model for the EVM to use pagination.</p> <h2 id="abstract">Abstract</h2> <p>Presently, the EVM charges for memory as a linear array starting at address 0 and extending to the highest address that has been read from or written to. This suffices for simple uses, but means that compilers have to generate programs that use memory compactly, which leads to wasted gas with reallocation of memory elements, and makes some memory models such as separate heap and stack areas impractical. This EIP proposes changing to a page-based billing model, which adds minimal complexity to implementations, while providing for much more versatility in EVM programs.</p> <h2 id="motivation">Motivation</h2> <p>Most modern computers implement "virtual memory" for userspace programs, where programs have access to a large address space, with pages of RAM that are allocated as needed by the OS. This allows them to distribute data throughout memory in ways that minimises the amount of reallocation and copying that needs to go on, and permits flexible use of memory for data with different lifetimes. Implementing a simple version of paged memory inside the EVM will provide the same flexibility to compilers targeting the EVM.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLOCK</code></td><td>TBD</td></tr> <tr><td><code>PAGE_BITS</code></td><td>10</td></tr> <tr><td><code>PAGE_BASE_COST</code></td><td>96</td></tr> </tbody></table> <p>For blocks where <code>block.number &gt;= FORK_BLOCK</code>, the following changes apply.</p> <h3 id="changes-to-memory-allocation-in-evm-implementations">Changes to memory allocation in EVM implementations</h3> <p>Memory is now allocated in pages of <code>2**PAGE_BITS</code> bytes each. The most significant <code>256 - PAGE_BITS</code> bits of each memory address denote the page number, while the least significant <code>PAGE_BITS</code> bits of the memory address denote the location in the page. Pages are initialized to contain all zero bytes and allocated when the first byte from a page is read or written.</p> <p>EVM implementations are encouraged to store the pagetable as an associative array (eg, hashtable or dict) mapping from page number to an array of bytes for the page.</p> <h3 id="changes-to-memory-expansion-gas-cost">Changes to memory expansion gas cost</h3> <p>Presently, the total cost to extend the memory to <code>a</code> words long is <code>Cmem(a) = 3 * a + floor(a ** 2 / 512)</code>. If the memory is already <code>b</code> words long, the incremental cost is <code>Cmem(a) - Cmem(b)</code>. <code>a</code> is the number of words required to cover the range from memory address 0 to the last word that has been read or written by the EVM.</p> <p>Under this EIP, we define a new memory cost function, based on the number of allocated pages. This function is <code>Cmem'(p) = max(PAGE_BASE_COST * (p - 1) + floor(2 * (p - 1) ** 2), 0)</code>. As above, if the memory already contains <code>q</code> pages, the incremental cost is <code>Cmem'(p) - Cmem'(q)</code>.</p> <h3 id="changes-to-mload-and-mstore">Changes to <code>MLOAD</code> and <code>MSTORE</code></h3> <p>Loading a word from memory or storing a word to memory requires instantiating any pages that it touches that do not already exist, with the resulting gas cost as described above. If the word being loaded or stored resides in a single page, the gas cost remains unchanged at 3 gas. If the word being loaded spans two pages, the cost is 6 gas.</p> <h3 id="changes-to-other-memory-touching-opcodes">Changes to other memory-touching opcodes</h3> <p><code>CALLDATACOPY</code>, <code>CODECOPY</code>, <code>EXTCODECOPY</code>, <code>CALL</code>, <code>CALLCODE</code>, <code>DELEGATECALL</code>, <code>STATICCALL</code>, <code>CREATE</code>, <code>MSTORE8</code> and any other opcodes that read or write memory are modified as follows:</p> <ul> <li>Any page they touch for reading or writing is instantiated if it is not already.</li> <li>Memory expansion gas is charged as described above.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="memory-expansion-gas-cost">Memory expansion gas cost</h3> <p>The new gas cost follows the same curve as the previous one, while ensuring that the new gas cost is always less than or equal to the previous cost. This prevents existing programs that make assumptions about memory allocation gas costs from resulting in errors, without unduly discounting memory below what it costs today. Intuitively, a program that uses up to a page boundary pays for one page less than they would under the old model, while a program that uses one word more than a page boundary pays for one word less than they would under the old model.</p> <p>We believe that this incremental reduction will not have a significant impact on the effective gas limit, as it gets proportionally smaller as programs use more RAM.</p> <h3 id="additional-cost-for-mloads-and-mstores-spanning-two-pages">Additional cost for MLOADs and MSTOREs spanning two pages</h3> <p>Loading or storing data spanning two memory pages requires more work from the EVM implementation, which must split the word at the page boundary and update the two (possibly disjoint) pages. Since we cannot guarantee loads and stores in existing EVM programs are page-aligned, we cannot prohibit this behaviour for efficiency. Instead, we propose treating each as two loads or stores for gas accounting purposes. This discourages the use of this functionality, and accounts for the additional execution cost, without prohibiting it outright.</p> <p>This will result in additional gas costs for any programs that perform these operations. We believe this to be minimal, and hope to do future analysis to confirm this.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The new function for memory expansion gas cost is designed specifically to avoid backwards compatibility issues by always charging less than or equal to the amount the current EVM would charge. Under some circumstances existing programs will be charged more for MLOADs and MSTOREs that span page boundaries as described above; we believe these changes will affect a minimum of programs and have only a small impact on their gas consumption.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>Potential CPU DoS issues arising from additional work done under the new model are alleviated by charging more for non-page-aligned reads and writes. Charges for memory expansion asymptotically approach those currently in force, so this change will not permit programs to allocate substantially more memory than they can today.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Nick Johnsonhttps://github.com/arachnid https://wg-eips.ritovision.com/3337/ <h2 id="simple-summary">Simple Summary</h2> <p>Introduces four new opcodes for loading data from and storing data to memory offset by a frame pointer.</p> <h2 id="abstract">Abstract</h2> <p>This EIP introduces four new opcodes, <code>MLOADFP</code>, <code>MSTOREFP</code>, <code>GETFP</code> and <code>SETFP</code> that allow for more efficient memory access offset by a user-controlled quantity called the "frame pointer". This permits compilers to more efficiently offload ephemeral data such as local variables to memory instead of the EVM's evaluation stack, which has a number of benefits, including the effective elimination of restrictions on the number of local variables in a function.</p> <h2 id="motivation">Motivation</h2> <p>In most commonly used VMs, ephemeral data such as local variables, function arguments, and return addresses is stored in a region of memory called the stack. In contrast to the EVM's evaluation stack, this area of memory is randomly accessible, and thus can store an arbitrary amount of data, which can be referenced from anywhere they remain in scope. Although this model is possible in the current EVM design, it is made difficult by the linear model of memory (addressed in <a href="https://wg-eips.ritovision.com/3336/">EIP-3336</a>) and by the lack of opcodes for relative memory access commonly found in other architectures. This EIP proposes new opcodes that permit this form of memory use, without imposing undue burden on EVM implementers or on runtime efficiency.</p> <p>In the current EVM model, a compiler wishing to use this pattern would have to store the frame pointer - which points to the start or end of the current memory stack frame - in memory, and load it each time they wish to reference it. For example, loading a value from memory offset by the frame pointer would require the following sequence of operations:</p> <table><thead><tr><th>Opcode</th><th>Gas used</th></tr></thead><tbody> <tr><td><code>PUSHn x</code></td><td>3</td></tr> <tr><td><code>PUSH1 0</code></td><td>3</td></tr> <tr><td><code>MLOAD</code></td><td>3</td></tr> <tr><td><code>ADD</code></td><td>3</td></tr> <tr><td><code>MLOAD</code></td><td>3</td></tr> </tbody></table> <p>This consumes a total of 15 gas, and takes up at least 7 bytes of bytecode each time it is referenced. In contrast, after this EIP, the equivalent sequence of operations is:</p> <table><thead><tr><th>Opcode</th><th>Gas used</th></tr></thead><tbody> <tr><td><code>PUSH1 x</code></td><td>3</td></tr> <tr><td><code>MLOADFP</code></td><td>3</td></tr> </tbody></table> <p>This consumes only 6 gas, and takes at least 3 bytes of bytecode. The effort required from the EVM implementation is equivalent, costing only one extra addition operation over a regular <code>MLOAD</code>. The alternative of storing values on the stack, which requires 3 gas and 1 byte of bytecode for a <code>DUPn</code> operation, but it is now at most twice as efficient rather than 5 times as efficient, making storing values in memory a viable alternative.</p> <p>Likewise, before this EIP a frame-pointer relative store requires the following sequence of operations:</p> <table><thead><tr><th>Opcode</th><th>Gas used</th></tr></thead><tbody> <tr><td><code>PUSHn x</code></td><td>3</td></tr> <tr><td><code>PUSH1 0</code></td><td>3</td></tr> <tr><td><code>MLOAD</code></td><td>3</td></tr> <tr><td><code>ADD</code></td><td>3</td></tr> <tr><td><code>MSTORE</code></td><td>3</td></tr> </tbody></table> <p>This consumes 15 gas and at least 7 bytes of bytecode. After this EIP, the equivalent sequence of operations is:</p> <table><thead><tr><th>Opcode</th><th>Gas used</th></tr></thead><tbody> <tr><td><code>PUSHn x</code></td><td>3</td></tr> <tr><td><code>MSTOREFP</code></td><td>3</td></tr> </tbody></table> <p>Consuming only 6 gas and at least 3 bytes of bytecode, while once again only requiring EVM implementations to do one extra addition operation. The alternative of storing values on the stack requires 6 gas and 2 bytes of bytecode for the sequence <code>SWAPn POP</code>, making it no more efficient than memory storage.</p> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLOCK</code></td><td>TBD</td></tr> </tbody></table> <p>For blocks where <code>block.number &gt;= FORK_BLOCK</code>, the following changes apply.</p> <h3 id="frame-pointer">Frame pointer</h3> <p>A new EVM internal state variable called the "frame pointer" is introduced. This is a signed integer that starts at 0.</p> <h3 id="setfp-opcode"><code>SETFP</code> opcode</h3> <p>A new opcode, <code>SETFP</code> is introduced with value <code>0x5c</code>. This opcode costs <code>G_low</code> (3 gas) and takes one argument from the stack. The argument is stored as the new value of the frame pointer.</p> <h3 id="getfp-opcode"><code>GETFP</code> opcode</h3> <p>A new opcode, <code>GETFP</code> is introduced with value <code>0x5d</code>. This opcode costs <code>G_low</code> (3 gas) and takes no arguments. It takes the current value of the frame pointer and pushes it to the stack.</p> <h3 id="mloadfp-opcode"><code>MLOADFP</code> opcode</h3> <p>A new opcode <code>MLOADFP</code> is introduced with value <code>0x5e</code>. This opcode acts in all ways identical to <code>MLOAD</code>, except that the value of the frame pointer is added to the address before loading data from memory. An attempt to load data from a negative address should be treated identically to an invalid opcode, consuming all gas and reverting the current execution context.</p> <h3 id="mstorefp-opcode"><code>MSTOREFP</code> opcode</h3> <p>A new opcode <code>MSTOREFP</code> is introduced with value <code>0x5f</code>. This opcode acts in all ways identical to <code>MSTORE</code>, except that the value of the frame pointer is added to the address before storing data to memory. An attempt to store data to a negative address should be treated identically to an invalid opcode, consuming all gas and reverting the current execution context.</p> <h2 id="rationale">Rationale</h2> <h3 id="cost-of-new-opcodes">Cost of new opcodes</h3> <p>The cost of the new opcodes <code>MLOADFP</code> and <code>MSTOREFP</code> reflects the cost of <code>MLOAD</code> and <code>MSTORE</code>. They are generally equivalent in cost with the exception of an extra addition operation, which imposes negligible cost.</p> <p>The cost of the new opcodes <code>SETFP</code> and <code>GETFP</code> is based on other common low-cost opcodes such as <code>PUSH</code> and <code>POP</code>.</p> <h3 id="absence-of-mstore8fp">Absence of <code>MSTORE8FP</code></h3> <p><code>MSTORE8FP</code> opcode was not included because it is expected that it would be used infrequently, and there is a desire to minimise the size of the instruction set and to conserve opcodes for future use.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP exclusively introduces new opcodes, and as a result should not impact any existing programs unless they operate under the assumption that these opcodes are undefined, which we believe will not be the case.</p> <h2 id="security-considerations">Security Considerations</h2> <p>DoS risks are mitigated by correct pricing of opcodes to reflect current execution costs. No other security considerations pertain to this EIP.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-03-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 Erik Markshttps://github.com/rekmarks https://wg-eips.ritovision.com/3326/ <h2 id="simple-summary">Simple Summary</h2> <p>An RPC method for switching the wallet's active Ethereum chain.</p> <h2 id="abstract">Abstract</h2> <p>The <code>wallet_switchEthereumChain</code> RPC method allows Ethereum applications ("dapps") to request that the wallet switches its active Ethereum chain, if the wallet has a concept thereof. The caller must specify a chain ID. The wallet application may arbitrarily refuse or accept the request. <code>null</code> is returned if the active chain was switched, and an error otherwise.</p> <p>Important cautions for implementers of this method are included in the <a href="https://wg-eips.ritovision.com/3326/#security-considerations">Security Considerations</a> section.</p> <h2 id="motivation">Motivation</h2> <p>All dapps require the user to interact with one or more Ethereum chains in order to function. Some wallets only supports interacting with one chain at a time. We call this the wallet's "active chain". <code>wallet_switchEthereumChain</code> enables dapps to request that the wallet switches its active chain to whichever one is required by the dapp. This enables UX improvements for both dapps and wallets.</p> <h2 id="specification">Specification</h2> <p>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 <a rel="external" href="https://www.ietf.org/rfc/rfc2119.txt">RFC-2119</a>.</p> <h3 id="wallet-switchethereumchain"><code>wallet_switchEthereumChain</code></h3> <p>The method accepts a single object parameter with a <code>chainId</code> field. The method returns <code>null</code> if the wallet switched its active chain, and an error otherwise.</p> <p>The method presupposes that the wallet has a concept of a single "active chain". The active chain is defined as the chain that the wallet is forwarding RPC requests to.</p> <h4 id="parameters">Parameters</h4> <p><code>wallet_switchEthereumChain</code> accepts a single object parameter, specified by the following TypeScript interface:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> SwitchEthereumChainParameter</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>If a field does not meet the requirements of this specification, the wallet <strong>MUST</strong> reject the request.</p> <ul> <li><code>chainId</code> <ul> <li><strong>MUST</strong> specify the integer ID of the chain as a hexadecimal string, per the <a href="https://wg-eips.ritovision.com/695/"><code>eth_chainId</code></a> Ethereum RPC method.</li> <li>The chain ID <strong>MUST</strong> be known to the wallet.</li> <li>The wallet <strong>MUST</strong> be able to switch to the specified chain and service RPC requests to it.</li> </ul> </li> </ul> <h4 id="returns">Returns</h4> <p>The method <strong>MUST</strong> return <code>null</code> if the request was successful, and an error otherwise.</p> <p>If the wallet does not have a concept of an active chain, the wallet <strong>MUST</strong> reject the request.</p> <h3 id="examples">Examples</h3> <p>These examples use JSON-RPC, but the method could be implemented using other RPC protocols.</p> <p>To switch to Mainnet:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_switchEthereumChain</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>To switch to the Goerli test chain:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_switchEthereumChain</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x5</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The purpose <code>wallet_switchEthereumChain</code> is to provide dapps with a way of requesting to switch the wallet's active chain, which they would otherwise have to ask the user to do manually.</p> <p>The method accepts a single object parameter to allow for future extensibility at virtually no cost to implementers and consumers.</p> <p>For related work, see <a href="https://wg-eips.ritovision.com/3085/">EIP-3085: <code>wallet_addEthereumChain</code></a> and <a href="https://wg-eips.ritovision.com/2015/">EIP-2015: <code>wallet_updateEthereumChain</code></a>. <code>wallet_switchEthereumChain</code> intentionally forgoes the chain metadata parameters included in those EIPs, since it is purely concerned with switching the active chain, regardless of RPC endpoints or any other metadata associated therewith.</p> <h2 id="security-considerations">Security Considerations</h2> <p>For wallets with a concept of an active chain, switching the active chain has significant implications for pending RPC requests and the user's experience. If the active chain switches without the user's awareness, a dapp could induce the user to take actions for unintended chains.</p> <p>In light of this, the wallet should:</p> <ul> <li>Display a confirmation whenever a <code>wallet_switchEthereumChain</code> is received, clearly identifying the requester and the chain that will be switched to. <ul> <li>The confirmation used in <a href="https://wg-eips.ritovision.com/1102/">EIP-1102</a> may serve as a point of reference.</li> </ul> </li> <li>When switching the active chain, cancel all pending RPC requests and chain-specific user confirmations.</li> </ul> <h3 id="preserving-user-privacy">Preserving User Privacy</h3> <p>Automatically rejecting requests for chains that aren't supported or have yet to be added by the wallet allows requesters to infer which chains are supported by the wallet. Wallet implementers should consider whether this communication channel violates any security properties of the wallet, and if so, take appropriate steps to mitigate it.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-02-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin Martin Swendehttps://github.com/holiman https://wg-eips.ritovision.com/3298/ <h2 id="simple-summary">Simple Summary</h2> <p>Remove gas refunds for SSTORE and SELFDESTRUCT.</p> <h2 id="motivation">Motivation</h2> <p>Gas refunds for SSTORE and SELFDESTRUCT were originally introduced to motivate application developers to write applications that practice "good state hygiene", clearing storage slots and contracts that are no longer needed. However, they are not widely used for this, and poor state hygiene continues to be the norm. It is now widely accepted that the only solution to state growth is some form of <a rel="external" href="https://hackmd.io/@HWeNw8hNRimMm2m2GH56Cw/state_size_management">statelessness or state expiry</a>, and if such a solution is implemented, then disused storage slots and contracts would start to be ignored automatically.</p> <p>Gas refunds additionally have multiple harmful consequences:</p> <ul> <li>Refunds give rise to <a rel="external" href="https://gastoken.io/">GasToken</a>. GasToken has benefits in moving gas space from low-fee periods to high-fee periods, but it also has downsides to the network, particularly in exacerbating state size (as state slots are effectively used as a "battery" to save up gas) and inefficiently clogging blockchain gas usage</li> <li>Refunds increase block size variance. The theoretical maximum amount of actual gas consumed in a block is nearly twice the on-paper gas limit (as refunds add gas space for subsequent transactions in a block, though refunds are capped at 50% of a transaction's gas used). This is <a rel="external" href="https://notes.ethereum.org/@vbuterin/eip_1559_spikes">not fatal</a>, but is still undesirable, especially given that refunds can be used to maintain 2x usage spikes for far longer than EIP 1559 can.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="parameters">Parameters</h3> <table><thead><tr><th>Constant</th><th>Value</th></tr></thead><tbody> <tr><td><code>FORK_BLOCK</code></td><td>TBD</td></tr> </tbody></table> <p>For blocks where <code>block.number &gt;= FORK_BLOCK</code>, the following changes apply.</p> <p>Do not apply the <code>refund</code>.</p> <p>The description above is sufficient to describe the change, but for the sake of clarity we enumerate all places where gas refunds are currently used and which should/could be removed within a node implementation.</p> <ol> <li> <p>Remove all use of the "refund counter" in SSTORE gas accounting, as defined in <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2200">EIP 2200</a>. Particularly:</p> <ul> <li>If a storage slot is changed and the <em>current value</em> equals the <em>original value</em>, but does not equal the <em>new value</em>, <code>SSTORE_RESET_GAS</code> is deducted (plus <code>COLD_SLOAD_COST</code> if <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2929#sstore-changes">prescribed by EIP 2929 rules</a>), but no modifications to the refund counter are made.</li> <li>If a storage slot is changed and the <em>current value</em> equals neither the <em>new value</em> nor the <em>original value</em> (regardless of whether or not the latter two are equal), <code>SLOAD_GAS</code> is deducted (plus <code>COLD_SLOAD_COST</code> if <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2929#sstore-changes">prescribed by EIP 2929 rules</a>), but no modifications to the refund counter are made.</li> </ul> </li> <li> <p>Remove the <code>SELFDESTRUCT</code> refund.</p> </li> </ol> <h2 id="rationale">Rationale</h2> <p>A full removal of refunds is the simplest way to solve the issues with refunds; any gains from partial retention of the refund mechanism are not worth the complexity that that would leave remaining in the Ethereum protocol.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Refunds are currently only applied <em>after</em> transaction execution, so they cannot affect how much gas is available to any particular call frame during execution. Hence, removing them will not break the ability of any code to execute, though it will render some applications economically nonviable.</p> <p><a rel="external" href="https://gastoken.io/">GasToken</a> in particular will become valueless. DeFi arbitrage bots, which today frequently use either established GasToken schemes or a custom alternative to reduce on-chain costs, would benefit from rewriting their code to remove calls to these no-longer-functional gas storage mechanisms.</p> <h2 id="implementation">Implementation</h2> <p>An implementation can be found here: https://gist.github.com/holiman/460f952716a74eeb9ab358bb1836d821#gistcomment-3642048</p> <h2 id="test-case-changes">Test case changes</h2> <ul> <li>The "original", "1st", "2nd", "3rd" columns refer to the value of storage slot 0 before the execution and after each SSTORE.</li> <li>The "Berlin (cold)" column gives the post-Berlin (EIP 2929) gas cost assuming the storage slot had not yet been accessed.</li> <li>The "Berlin (hot)" column gives the post-Berlin gas cost assuming the storage slot has already been accessed.</li> <li>The "Berlin (hot) + norefund" column gives the post-Berlin gas cost assuming the storage slot has already been accessed, <strong>and assuming this EIP has been implemented</strong>.</li> </ul> <p>Gas costs are provided with refunds subtracted; if the number is negative this means that refunds exceed gas costs. The 50% refund limit is not applied (due to the implied assumption that this code is only a small fragment of a much larger execution).</p> <p>If refunds were to be removed, this would be the comparative table</p> <table><thead><tr><th>Code</th><th>Original</th><th>1st</th><th>2nd</th><th>3rd</th><th>Istanbul</th><th>Berlin (cold)</th><th>Berlin (hot)</th><th>Berlin (hot)+norefund</th></tr></thead><tbody> <tr><td><code>0x60006000556000600055</code></td><td>0</td><td>0</td><td>0</td><td></td><td>1612</td><td>2312</td><td>212</td><td>212</td></tr> <tr><td><code>0x60006000556001600055</code></td><td>0</td><td>0</td><td>1</td><td></td><td>20812</td><td>22212</td><td>20112</td><td>20112</td></tr> <tr><td><code>0x60016000556000600055</code></td><td>0</td><td>1</td><td>0</td><td></td><td>1612</td><td>2312</td><td>212</td><td>20112</td></tr> <tr><td><code>0x60016000556002600055</code></td><td>0</td><td>1</td><td>2</td><td></td><td>20812</td><td>22212</td><td>20112</td><td>20112</td></tr> <tr><td><code>0x60016000556001600055</code></td><td>0</td><td>1</td><td>1</td><td></td><td>20812</td><td>22212</td><td>20112</td><td>20112</td></tr> <tr><td><code>0x60006000556000600055</code></td><td>1</td><td>0</td><td>0</td><td></td><td>-9188</td><td>-9888</td><td>-11988</td><td>3012</td></tr> <tr><td><code>0x60006000556001600055</code></td><td>1</td><td>0</td><td>1</td><td></td><td>1612</td><td>2312</td><td>212</td><td>3012</td></tr> <tr><td><code>0x60006000556002600055</code></td><td>1</td><td>0</td><td>2</td><td></td><td>5812</td><td>5112</td><td>3012</td><td>3012</td></tr> <tr><td><code>0x60026000556000600055</code></td><td>1</td><td>2</td><td>0</td><td></td><td>-9188</td><td>-9888</td><td>-11988</td><td>3012</td></tr> <tr><td><code>0x60026000556003600055</code></td><td>1</td><td>2</td><td>3</td><td></td><td>5812</td><td>5112</td><td>3012</td><td>3012</td></tr> <tr><td><code>0x60026000556001600055</code></td><td>1</td><td>2</td><td>1</td><td></td><td>1612</td><td>2312</td><td>212</td><td>3012</td></tr> <tr><td><code>0x60026000556002600055</code></td><td>1</td><td>2</td><td>2</td><td></td><td>5812</td><td>5112</td><td>3012</td><td>3012</td></tr> <tr><td><code>0x60016000556000600055</code></td><td>1</td><td>1</td><td>0</td><td></td><td>-9188</td><td>-9888</td><td>-11988</td><td>3012</td></tr> <tr><td><code>0x60016000556002600055</code></td><td>1</td><td>1</td><td>2</td><td></td><td>5812</td><td>5112</td><td>3012</td><td>3012</td></tr> <tr><td><code>0x60016000556001600055</code></td><td>1</td><td>1</td><td>1</td><td></td><td>1612</td><td>2312</td><td>212</td><td>212</td></tr> <tr><td><code>0x600160005560006000556001600055</code></td><td>0</td><td>1</td><td>0</td><td>1</td><td>21618</td><td>22318</td><td>20218</td><td>40118</td></tr> <tr><td><code>0x600060005560016000556000600055</code></td><td>1</td><td>0</td><td>1</td><td>0</td><td>-8382</td><td>-9782</td><td>-11882</td><td>5918</td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-02-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Victor Portonhttps://github.com/vporton Victor Portonporton@narod.ru https://wg-eips.ritovision.com/3267/ <h2 id="simple-summary">Simple Summary</h2> <p>Transfer a part of Ethereum transfer/mining fees to Future Salaries contract</p> <h2 id="abstract">Abstract</h2> <p>Transfer a part (exact fractions - TBD) of mining/transfer fees + (probably: TBD) some minted ETH to the <code>DonateETH</code> contract configured to transfer to <code>SalaryWithDAO</code> contract.</p> <h2 id="motivation">Motivation</h2> <p>This proposal solves two problems at once:</p> <ol> <li> <p>It provides a big amount of "money" to common good producers. That obviously personally benefits common good producers, allowing them to live better human lives, it increases peoples' and organizations' both abilities and incentives to produce common goods. That benefits the humanity as a whole and the Ethereum ecosystem in particular. See more in the discussion why it's crucial.</p> </li> <li> <p>This would effectively decrease circulating ETH supply. The necessity to decrease the (circulating) ETH supply (by locking ETH in Future Salaries system for a long time) is a well-known important thing to be done.</p> </li> </ol> <p>Paradoxically, it will directly benefit miners/validators, see the discussion.</p> <h2 id="specification">Specification</h2> <p>(TBD)</p> <p><code>SalaryWithDAO</code> = <code>TBD</code> (<code>address</code>)</p> <p><code>DefaultDAOInterface</code> = <code>TBD</code> (<code>address</code>)</p> <p><code>MintPerPeriod</code> = <code>TBD</code> (<code>uint256</code>)</p> <p><code>TransferFraction</code> = <code>TBD</code> (0..1)</p> <p><code>MineFraction</code> = <code>TBD</code> (0..1)</p> <p><a href="https://wg-eips.ritovision.com/3267/assets/contracts/README/">The contract's source</a></p> <p>Prior to <code>FORK_BLOCK_NUMBER</code>, <code>SalaryWithDAO</code> and <code>DefaultDAOInterface</code> contracts will be deployed to the network and exist at the above specified addresses.</p> <p>Change the Ethereum clients to transfer at every ETH transfer and every ETH mine a fixed fraction <code>TransferFraction</code> of the transferred ETH and <code>MineFraction</code> of the mined ETH to a fixed account (decide the account number, it can be for example <code>0x00000000000000000000000000000000000000001</code> or even <code>0x00000000000000000000000000000000000000000</code> or a random account).</p> <p>Change the Ethereum clients to mint <code>MintPerPeriod</code> ETH to the contract <code>DonateETH</code> every some time (e.g. the first transaction of the first block every UTC day - TBD how often).</p> <p>Change the Ethereum clients to every some time (e.g. the second transaction of the first block every UTC day - TBD how often) transfer the entire ETH from this account to the contract <code>DonateETH</code>.</p> <p>Because this EIP solves a similar problem, cancel any other EIPs that burn ETH (except gas fees) during transfers or mining. (TBD: We should transfer more ETH in this EIP than we burned accordingly older accepted EIPs, because this EIP has the additional advantages of: 1. funding common goods; 2. better aligning values of ETH and values of tokens).</p> <h2 id="rationale">Rationale</h2> <p>The Future Salaries is the <em>only</em> known system of distributing significant funds to common good producers. (Quadratic funding aimed to do a similar thing, but in practice as we see on GitCoin it favors a few developers, ignores project of highly advanced scientific research that is hard to explain to an average developer, and encourages colluding, and it just highly random due to small number of donors. Also quadratic funding simply does not gather enough funds to cover common good needs). So this EIP is the only known way to recover the economy.</p> <p>The economical model of Future Salaries is described in <a href="https://wg-eips.ritovision.com/3267/./assets/science-salaries.pdf">this research article preprint</a>.</p> <p>Funding multiple oracles with different finish time would alleviate the future trouble that the circulating ETH (or other tokens) supply would suddenly increase when the oracle finishes. It would effectively exclude some ETH from the circulation forever.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Because transferring to the aforementioned account is neither mining nor a transaction, we get a new kinds of ETH transfers, so there may be some (expected moderate impact) troubles with applications that have made assumptions about ETH transfers all occurring either as miner payments or transactions.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The security considerations are:</p> <ul> <li>The DAO that controls account restoration may switch to a non-effective or biased way of voting (for example to being controlled by one human) thus distributing funds unfairly. This problem could be solved by a future fork of Ethereum that would "confiscate" control from the DAO.</li> </ul> <p>See more in the discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-01-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alberto Cuesta Cañadahttps://github.com/albertocuestacanada Fiona Kobayashihttps://github.com/fifikobayashi fubuloubuhttps://github.com/fubuloubu Austin Williamshttps://github.com/onewayfunction https://wg-eips.ritovision.com/3234/ <h2 id="simple-summary">Simple Summary</h2> <p>This ERC provides standard interfaces and processes for multiple-asset flash loans.</p> <h2 id="motivation">Motivation</h2> <p>Flash loans of multiple assets, or batch flash loans, are a common offering of flash lenders, and have a strong use case in the simultaneous refinance of several positions between platforms. At the same time, batch flash loans are more complicated to use than single asset flash loans (ER3156). This divergence of use cases and user profiles calls for independent, but consistent, standards for single asset flash loans and batch flash loans.</p> <h2 id="specification">Specification</h2> <p>A batch flash lending feature integrates two smart contracts using a callback pattern. These are called the LENDER and the RECEIVER in this EIP.</p> <h3 id="lender-specification">Lender Specification</h3> <p>A <code>lender</code> MUST implement the IERC3234BatchFlashLender interface.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.7.0 || ^0.8.0;</span></span> <span class="giallo-l"><span>import &quot;./IERC3234BatchFlashBorrower.sol&quot;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC3234BatchFlashLender {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev The amount of currency available to be lended.</span></span> <span class="giallo-l"><span> * @param tokens The currency for each loan in the batch.</span></span> <span class="giallo-l"><span> * @return The maximum amount that can be borrowed for each loan in the batch.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function maxFlashLoan(</span></span> <span class="giallo-l"><span> address[] calldata tokens</span></span> <span class="giallo-l"><span> ) external view returns (uint256[]);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev The fees to be charged for a given batch loan.</span></span> <span class="giallo-l"><span> * @param tokens The loan currencies.</span></span> <span class="giallo-l"><span> * @param amounts The amounts of tokens lent.</span></span> <span class="giallo-l"><span> * @return The amount of each `token` to be charged for each loan, on top of the returned principal.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function flashFee(</span></span> <span class="giallo-l"><span> address[] calldata tokens,</span></span> <span class="giallo-l"><span> uint256[] calldata amounts</span></span> <span class="giallo-l"><span> ) external view returns (uint256[]);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Initiate a batch flash loan.</span></span> <span class="giallo-l"><span> * @param receiver The receiver of the tokens in the loan, and the receiver of the callback.</span></span> <span class="giallo-l"><span> * @param tokens The loan currencies.</span></span> <span class="giallo-l"><span> * @param amounts The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @param data Arbitrary data structure, intended to contain user-defined parameters.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function batchFlashLoan(</span></span> <span class="giallo-l"><span> IERC3234BatchFlashBorrower receiver,</span></span> <span class="giallo-l"><span> address[] calldata tokens,</span></span> <span class="giallo-l"><span> uint256[] calldata amounts,</span></span> <span class="giallo-l"><span> bytes[] calldata data</span></span> <span class="giallo-l"><span> ) external returns (bool);</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>maxFlashLoan</code> function MUST return the maximum loan possible for each <code>token</code>. If a <code>token</code> is not currently supported <code>maxFlashLoan</code> MUST return 0, instead of reverting.</p> <p>The <code>flashFee</code> function MUST return the fees charged for each loan of <code>amount</code> <code>token</code>. If a token is not supported <code>flashFee</code> MUST revert.</p> <p>The <code>batchFlashLoan</code> function MUST include a callback to the <code>onBatchFlashLoan</code> function in a <code>IERC3234BatchFlashBorrower</code> contract.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function batchFlashLoan(</span></span> <span class="giallo-l"><span> IERC3234BatchFlashBorrower receiver,</span></span> <span class="giallo-l"><span> address[] calldata tokens,</span></span> <span class="giallo-l"><span> uint256[] calldata amounts,</span></span> <span class="giallo-l"><span> bytes calldata data</span></span> <span class="giallo-l"><span>) external returns (bool) {</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> require(</span></span> <span class="giallo-l"><span> receiver.onBatchFlashLoan(</span></span> <span class="giallo-l"><span> msg.sender,</span></span> <span class="giallo-l"><span> tokens,</span></span> <span class="giallo-l"><span> amounts,</span></span> <span class="giallo-l"><span> fees,</span></span> <span class="giallo-l"><span> data</span></span> <span class="giallo-l"><span> ) == keccak256(&quot;ERC3234BatchFlashBorrower.onBatchFlashLoan&quot;),</span></span> <span class="giallo-l"><span> &quot;IERC3234: Callback failed&quot;</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>batchFlashLoan</code> function MUST transfer <code>amounts[i]</code> of each <code>tokens[i]</code> to <code>receiver</code> before the callback to the borrower.</p> <p>The <code>batchFlashLoan</code> function MUST include <code>msg.sender</code> as the <code>initiator</code> to <code>onBatchFlashLoan</code>.</p> <p>The <code>batchFlashLoan</code> function MUST NOT modify the <code>tokens</code>, <code>amounts</code> and <code>data</code> parameters received, and MUST pass them on to <code>onBatchFlashLoan</code>.</p> <p>The <code>lender</code> MUST verify that the <code>onBatchFlashLoan</code> callback returns the keccak256 hash of "ERC3234BatchFlashBorrower.onBatchFlashLoan".</p> <p>The <code>batchFlashLoan</code> function MUST include a <code>fees</code> argument to <code>onBatchFlashLoan</code> with the fee to pay for each individual <code>token</code> and <code>amount</code> lent, ensuring that <code>fees[i] == flashFee(tokens[i], amounts[i])</code>.</p> <p>After the callback, for each <code>token</code> in <code>tokens</code>, the <code>batchFlashLoan</code> function MUST take the <code>amounts[i] + fees[i]</code> of <code>tokens[i]</code> from the <code>receiver</code>, or revert if this is not successful.</p> <p>If successful, <code>batchFlashLoan</code> MUST return <code>true</code>.</p> <h3 id="receiver-specification">Receiver Specification</h3> <p>A <code>receiver</code> of flash loans MUST implement the IERC3234BatchFlashBorrower interface:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>pragma solidity ^0.7.0 || ^0.8.0;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>interface IERC3234BatchFlashBorrower {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * @dev Receive a flash loan.</span></span> <span class="giallo-l"><span> * @param initiator The initiator of the loan.</span></span> <span class="giallo-l"><span> * @param tokens The loan currency.</span></span> <span class="giallo-l"><span> * @param amounts The amount of tokens lent.</span></span> <span class="giallo-l"><span> * @param fees The additional amount of tokens to repay.</span></span> <span class="giallo-l"><span> * @param data Arbitrary data structure, intended to contain user-defined parameters.</span></span> <span class="giallo-l"><span> * @return The keccak256 hash of &quot;ERC3234BatchFlashBorrower.onBatchFlashLoan&quot;</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function onBatchFlashLoan(</span></span> <span class="giallo-l"><span> address initiator,</span></span> <span class="giallo-l"><span> address[] calldata tokens,</span></span> <span class="giallo-l"><span> uint256[] calldata amounts,</span></span> <span class="giallo-l"><span> uint256[] calldata fees,</span></span> <span class="giallo-l"><span> bytes calldata data</span></span> <span class="giallo-l"><span> ) external returns (bytes32);</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>For the transaction to not revert, for each <code>token</code> in <code>tokens</code>, <code>receiver</code> MUST approve <code>amounts[i] + fees[i]</code> of <code>tokens[i]</code> to be taken by <code>msg.sender</code> before the end of <code>onBatchFlashLoan</code>.</p> <p>If successful, <code>onBatchFlashLoan</code> MUST return the keccak256 hash of "ERC3156BatchFlashBorrower.onBatchFlashLoan".</p> <h2 id="rationale">Rationale</h2> <p>The interfaces described in this ERC have been chosen as to cover the known flash lending use cases, while allowing for safe and gas efficient implementations.</p> <p><code>flashFee</code> reverts on unsupported tokens, because returning a numerical value would be incorrect.</p> <p><code>batchFlashLoan</code> has been chosen as a function name as descriptive enough, unlikely to clash with other functions in the lender, and including both the use cases in which the tokens lended are held or minted by the lender.</p> <p><code>receiver</code> is taken as a parameter to allow flexibility on the implementation of separate loan initiators and receivers.</p> <p>Existing flash lenders (Aave, dYdX and Uniswap) all provide flash loans of several token types from the same contract (LendingPool, SoloMargin and UniswapV2Pair). Providing a <code>token</code> parameter in both the <code>batchFlashLoan</code> and <code>onBatchFlashLoan</code> functions matches closely the observed functionality.</p> <p>A <code>bytes calldata data</code> parameter is included for the caller to pass arbitrary information to the <code>receiver</code>, without impacting the utility of the <code>batchFlashLoan</code> standard.</p> <p><code>onBatchFlashLoan</code> has been chosen as a function name as descriptive enough, unlikely to clash with other functions in the <code>receiver</code>, and following the <code>onAction</code> naming pattern used as well in EIP-667.</p> <p>An <code>initiator</code> will often be required in the <code>onBatchFlashLoan</code> function, which the lender knows as <code>msg.sender</code>. An alternative implementation which would embed the <code>initiator</code> in the <code>data</code> parameter by the caller would require an additional mechanism for the receiver to verify its accuracy, and is not advisable.</p> <p>The <code>amounts</code> will be required in the <code>onBatchFlashLoan</code> function, which the lender took as a parameter. An alternative implementation which would embed the <code>amounts</code> in the <code>data</code> parameter by the caller would require an additional mechanism for the receiver to verify its accuracy, and is not advisable.</p> <p>The <code>fees</code> will often be calculated in the <code>batchFlashLoan</code> function, which the <code>receiver</code> must be aware of for repayment. Passing the <code>fees</code> as a parameter instead of appended to <code>data</code> is simple and effective.</p> <p>The <code>amount + fee</code> are pulled from the <code>receiver</code> to allow the <code>lender</code> to implement other features that depend on using <code>transferFrom</code>, without having to lock them for the duration of a flash loan. An alternative implementation where the repayment is transferred to the <code>lender</code> is also possible, but would need all other features in the lender to be also based in using <code>transfer</code> instead of <code>transferFrom</code>. Given the lower complexity and prevalence of a "pull" architecture over a "push" architecture, "pull" was chosen.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="verification-of-callback-arguments">Verification of callback arguments</h3> <p>The arguments of <code>onBatchFlashLoan</code> are expected to reflect the conditions of the flash loan, but cannot be trusted unconditionally. They can be divided in two groups, that require different checks before they can be trusted to be genuine.</p> <ol start="0"> <li>No arguments can be assumed to be genuine without some kind of verification. <code>initiator</code>, <code>tokens</code> and <code>amounts</code> refer to a past transaction that might not have happened if the caller of <code>onBatchFlashLoan</code> decides to lie. <code>fees</code> might be false or calculated incorrectly. <code>data</code> might have been manipulated by the caller.</li> <li>To trust that the value of <code>initiator</code>, <code>tokens</code>, <code>amounts</code> and <code>fees</code> are genuine a reasonable pattern is to verify that the <code>onBatchFlashLoan</code> caller is in a whitelist of verified flash lenders. Since often the caller of <code>batchFlashLoan</code> will also be receiving the <code>onBatchFlashLoan</code> callback this will be trivial. In all other cases flash lenders will need to be approved if the arguments in <code>onBatchFlashLoan</code> are to be trusted.</li> <li>To trust that the value of <code>data</code> is genuine, in addition to the check in point 1, it is recommended that the <code>receiver</code> verifies that the <code>initiator</code> is in some list of trusted addresses. Trusting the <code>lender</code> and the <code>initiator</code> is enough to trust that the contents of <code>data</code> are genuine.</li> </ol> <h3 id="flash-lending-security-considerations">Flash lending security considerations</h3> <h4 id="automatic-approvals-for-untrusted-borrowers">Automatic approvals for untrusted borrowers</h4> <p>The safest approach is to implement an approval for <code>amount+fee</code> before the <code>batchFlashLoan</code> is executed.</p> <p>Including in <code>onBatchFlashLoan</code> the approval for the <code>lender</code> to take the <code>amount + fee</code> needs to be combined with a mechanism to verify that the borrower is trusted, such as those described above.</p> <p>If an unsuspecting contract with a non-reverting fallback function, or an EOA, would approve a <code>lender</code> implementing ERC3156, and not immediately use the approval, and if the <code>lender</code> would not verify the return value of <code>onBatchFlashLoan</code>, then the unsuspecting contract or EOA could be drained of funds up to their allowance or balance limit. This would be executed by a <code>borrower</code> calling <code>batchFlashLoan</code> on the victim. The flash loan would be executed and repaid, plus any fees, which would be accumulated by the <code>lender</code>. For this reason, it is important that the <code>lender</code> implements the specification in full and reverts if <code>onBatchFlashLoan</code> doesn't return the keccak256 hash for "ERC3156FlashBorrower.onBatchFlashLoan".</p> <h3 id="flash-minting-external-security-considerations">Flash minting external security considerations</h3> <p>The typical quantum of tokens involved in flash mint transactions will give rise to new innovative attack vectors.</p> <h4 id="example-1-interest-rate-attack">Example 1 - interest rate attack</h4> <p>If there exists a lending protocol that offers stable interests rates, but it does not have floor/ceiling rate limits and it does not rebalance the fixed rate based on flash-induced liquidity changes, then it could be susceptible to the following scenario:</p> <p>FreeLoanAttack.sol</p> <ol> <li>Flash mint 1 quintillion DAI</li> <li>Deposit the 1 quintillion DAI + $1.5 million worth of ETH collateral</li> <li>The quantum of your total deposit now pushes the stable interest rate down to 0.00001% stable interest rate</li> <li>Borrow 1 million DAI on 0.00001% stable interest rate based on the 1.5M ETH collateral</li> <li>Withdraw and burn the 1 quint DAI to close the original flash mint</li> <li>You now have a 1 million DAI loan that is practically interest free for perpetuity ($0.10 / year in interest)</li> </ol> <p>The key takeaway being the obvious need to implement a flat floor/ceiling rate limit and to rebalance the rate based on short term liquidity changes.</p> <h4 id="example-2-arithmetic-overflow-and-underflow">Example 2 - arithmetic overflow and underflow</h4> <p>If the flash mint provider does not place any limits on the amount of flash mintable tokens in a transaction, then anyone can flash mint 2^256-1 amount of tokens.</p> <p>The protocols on the receiving end of the flash mints will need to ensure their contracts can handle this. One obvious way is to leverage OpenZeppelin's SafeMath libraries as a catch-all safety net, however consideration should be given to when it is or isn't used given the gas tradeoffs.</p> <p>If you recall there was a series of incidents in 2018 where exchanges such as OKEx, Poloniex, HitBTC and Huobi had to shutdown deposits and withdrawls of ERC20 tokens due to integer overflows within the ERC20 token contracts.</p> <h3 id="flash-minting-internal-security-considerations">Flash minting internal security considerations</h3> <p>The coupling of flash minting with business specific features in the same platform can easily lead to unintended consequences.</p> <h4 id="example-treasury-draining">Example - Treasury draining</h4> <p>In early implementations of the Yield Protocol flash loaned fyDai could be redeemed for Dai, which could be used to liquidate the Yield Protocol CDP vault in MakerDAO:</p> <ol> <li>Flash mint a very large amount of fyDai.</li> <li>Redeem for Dai as much fyDai as the Yield Protocol collateral would allow.</li> <li>Trigger a stability rate increase with a call to <code>jug.drip</code> which would make the Yield Protocol uncollateralized.</li> <li>Liquidate the Yield Protocol CDP vault in MakerDAO.</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-01-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Afri Schoedonhttps://github.com/q9f https://wg-eips.ritovision.com/3238/ <h2 id="simple-summary">Simple Summary</h2> <p>Delays the difficulty bomb so 30 second blocks won't happen until around Q2/2022.</p> <h2 id="abstract">Abstract</h2> <p>Starting with <code>FORK_BLOCK_NUMBER</code> the client will calculate the difficulty based on a fake block number suggesting to the client that the difficulty bomb is adjusting eleven million blocks later than the actual block number.</p> <h2 id="motivation">Motivation</h2> <p>Even after the Ethereum 2.0 mainnet launch, Ethash proof-of-work mining on the legacy chain should be feasible. It should allow miners sealing new blocks every 13~15 seconds on average for another ten months and allow both Ethereum 1.x and Ethereum 2.0 developers to conclude the merge.</p> <h2 id="specification">Specification</h2> <h4 id="relax-difficulty-with-fake-block-number">Relax Difficulty with Fake Block Number</h4> <p>For the purposes of <code>calc_difficulty</code>, simply replace the use of <code>block.number</code>, as used in the exponential ice age component, with the formula:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>fake_block_number = max(0, block.number - 11_000_000) if block.number &gt;= FORK_BLOCK_NUMBER else block.number</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This will delay the ice age by another ~26 million seconds (approximately ~9.89 months), so the chain would be back at ~30 second block times in Q2/2022. Hopefully, by then the Eth1-to-Eth2 merge will be concluded and the ice age fulfilled its task.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is not forward compatible and introduces backwards incompatibilities in the difficulty calculation. Therefore, it should be included in a scheduled hardfork at a certain block number. It's suggested to consider this EIP either with or shortly after the Berlin hard-fork but not later than July 2021.</p> <p>Alternatively, in order to maintain stability of the system, a it can be considered to activate this EIP along with EIP-1559 fee market changes in a bundle. With the delay of the ice age, there is a desire to no further increase inflation and rather incentivize users to participate in proof-of-stake consensus instead.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no known security issues with this proposal.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2021-01-23T00:00:00+00:00 2026-02-11T14:48:25+00:00 Richard Moorehttps://github.com/ricmoo Nick Johnsonhttps://github.com/arachnid https://wg-eips.ritovision.com/3224/

Contract method to compute human-readable descriptions for signable data.

<h2 id="abstract">Abstract</h2> <p>Human-readable descriptions for machine executable operations, described in higher level machine readable data, so that wallets can provide meaningful feedback to the user describing the action the user is about to perform.</p> <h2 id="motivation">Motivation</h2> <p>When using an Ethereum Wallet (e.g. MetaMask, Clef, Hardware Wallets) users must accept and authorize signing messages or sending transactions.</p> <p>Due to the complexity of Ethereum transactions, wallets are very limitd in their ability to provide insight into the contents of transactions user are approving; outside special-cased support for common transactions such as ERC20 transfers, this often amounts to asking the user to sign an opaque blob of binary data.</p> <p>This EIP presents a method for dapp developers to enable a more comfortable user experience by providing wallets with a means to generate a better description about what the contract claims will happen.</p> <p>It does not address malicious contracts which wish to lie, it only addresses honest contracts that want to make their user's life better. We believe that this is a reasonable security model, as transaction descriptions can be audited at the same time as contract code, allowing auditors and code reviewers to check that transaction descriptions are accurate as part of their review.</p> <h2 id="specification">Specification</h2> <p>The <strong>description string</strong> and <strong>described data</strong> are generated simultaneously by evaluating the contract (i.e. the <strong>describer</strong>), passing the <strong>describer inputs</strong> to the method:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> eipXXXDescribe</span><span>(</span><span class="z-support">bytes</span><span class="z-variable"> describer_inputs</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable"> description_string</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> described_data</span><span>)</span><span>;</span></span></code></pre> <p>The method must be executable in a static context, (i.e. any side effects, such as logX, sstore, etc.), including through indirect calls may be ignored.</p> <p>During evaluation, the <code>ADDRESS</code> (i.e. <code>to</code>), <code>CALLER</code> (i.e. <code>from</code>), <code>VALUE</code>, and <code>GASPRICE</code> must be the same as the values for the transaction being described, so that the code generating the description can rely on them. For signing <strong>described messages</strong>, <code>VALUE</code> should always be 0.</p> <p>When executing the bytecode, best efforts should be made to ensure <code>BLOCKHASH</code>, <code>NUMBER</code>, <code>TIMESTAMP</code> and <code>DIFFICULTY</code> match the <code>"latest"</code> block. The <code>COINBASE</code> should be the zero address.</p> <p>The method may revert, in which case the signing must be aborted.</p> <h3 id="new-json-rpc-methods">New JSON-RPC Methods</h3> <p>Clients which manage private keys should expose additional methods for interacting with the related accounts.</p> <p>If an user interface is not present or expected for any other account-based operations, the description strings should be ignored and the described data used directly.</p> <p>These JSON-RPC methods will also be implemented in standard Ethereum libraries, so the JSON-RPC description is meant more of a canonical way to describe them.</p> <h3 id="signing-described-messages">Signing Described Messages</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">eth_signDescribedMessage</span><span>(</span><span class="z-support">address</span><span>,</span><span> describer</span><span>,</span><span> describerInput</span><span>)</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Result: {</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> description: &quot;text/plain;Hello World&quot;,</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> data: &quot;0x...&quot;, // described data</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> signature: &quot;0x...&quot;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> }</span></span></code></pre> <p>Compute the <strong>description string</strong> and <strong>described data</strong> by evaluating the call to <strong>describer</strong>, with the <strong>describerInput</strong> passed to the ABI encoded call to <code>eipXXXDescription(bytes)</code>. The <code>VALUE</code> during execution must be 0.</p> <p>If the wallet contains a user interface for accepting or denying signing a message, it should present the description string to the user. Optionally, a wallet may wish to additionally provide a way to examine the described data.</p> <p>If accepted, the computed <strong>described data</strong> is signed according to <a href="https://wg-eips.ritovision.com/191/">EIP-191</a>, with the <em>version byte</em> of <code>0x00</code> and the <em>version specific data</em> of describer address.</p> <p>That is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x19 0x00 DESCRIBER_ADDRESS 0xDESCRIBED_DATA</span></span></code></pre> <p>The returned result includes the <strong>described data</strong>, allowing dapps that use parameters computed in the contract to be available.</p> <h3 id="sending-described-transactions">Sending Described Transactions</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">eth_sendDescribedTransaction</span><span>(</span><span class="z-support">address</span><span>,</span><span> {</span></span> <span class="giallo-l"><span> to</span><span class="z-keyword">:</span><span class="z-string"> &quot;0x...&quot;</span><span>,</span></span> <span class="giallo-l"><span> value</span><span class="z-keyword">:</span><span class="z-constant"> 1234</span><span>,</span></span> <span class="giallo-l"><span> nonce</span><span class="z-keyword">:</span><span class="z-constant"> 42</span><span>,</span></span> <span class="giallo-l"><span> gas</span><span class="z-keyword">:</span><span class="z-constant"> 42000</span><span>,</span></span> <span class="giallo-l"><span> gasPrice</span><span class="z-keyword">:</span><span class="z-constant"> 9000000000</span><span>,</span></span> <span class="giallo-l"><span> describerInput</span><span class="z-keyword">:</span><span class="z-string"> &quot;0x1234...&quot;</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Result: {</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> description: &quot;text/plain;Hello World&quot;,</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> transaction: &quot;0x...&quot;, // serialized signed transaction</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> }</span></span></code></pre> <p>Compute the <strong>description string</strong> and <strong>described data</strong> by evaluating the call to the <strong>describer</strong> <code>to</code>, with the <strong>describerInput</strong> passed to the ABI encoded call to <code>eipXXXDescription(bytes)</code>.</p> <p>If the wallet contains a user interface for accepting or denying a transaction, it should present the description string along with fee and value information. Optionally, a wallet may wish to additionally provide a way to further examine the transaction.</p> <p>If accepted, the transaction data is set to the computed <strong>described data</strong>, the derived transaction is signed and sent, and the <strong>description string</strong> and serialized signed transaction is returned.</p> <h3 id="signing-described-transaction">Signing Described Transaction</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">eth_signDescribedTransaction</span><span>(</span><span class="z-support">address</span><span>,</span><span> {</span></span> <span class="giallo-l"><span> to</span><span class="z-keyword">:</span><span class="z-string"> &quot;0x...&quot;</span><span>,</span></span> <span class="giallo-l"><span> value</span><span class="z-keyword">:</span><span class="z-constant"> 1234</span><span>,</span></span> <span class="giallo-l"><span> nonce</span><span class="z-keyword">:</span><span class="z-constant"> 42</span><span>,</span></span> <span class="giallo-l"><span> gas</span><span class="z-keyword">:</span><span class="z-constant"> 42000</span><span>,</span></span> <span class="giallo-l"><span> gasPrice</span><span class="z-keyword">:</span><span class="z-constant"> 9000000000</span><span>,</span></span> <span class="giallo-l"><span> describerInput</span><span class="z-keyword">:</span><span class="z-string"> &quot;0x1234...&quot;</span><span>,</span></span> <span class="giallo-l"><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Result: {</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> description: &quot;text/plain;Hello World&quot;,</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> transaction: &quot;0x...&quot;, // serialized signed transaction</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> }</span></span></code></pre> <p>Compute the <strong>description string</strong> and <strong>described data</strong> by evaluating the call to the <strong>describer</strong> <code>to</code>, with the <strong>describerInput</strong> passed to the ABI encoded call to <code>eipXXXDescription(bytes)</code>.</p> <p>If the wallet contains a user interface for accepting or denying a transaction, it should present the description string along with fee and value information. Optionally, a wallet may wish to additionally provide a way to further examine the transaction.</p> <p>If accepted, the transaction data is set to the computed <strong>described data</strong>, the derived transaction is signed (and not sent) and the <strong>description string</strong> and serialized signed transaction is returned.</p> <h3 id="description-strings">Description Strings</h3> <p>A <strong>description string</strong> must begin with a mime-type followed by a semi-colon (<code>;</code>). This EIP specifies only the <code>text/plain</code> mime-type, but future EIPs may specify additional types to enable more rich processing, such as <code>text/markdown</code> so that addresses can be linkable within clients or to enable multi-locale options, similar to multipart/form-data.</p> <h2 id="rationale">Rationale</h2> <h3 id="meta-description">Meta Description</h3> <p>There have been many attempts to solve this problem, many of which attempt to examine the encoded transaction data or message data directly.</p> <p>In many cases, the information that would be necessary for a meaningful description is not present in the final encoded transaction data or message data.</p> <p>Instead this EIP uses an indirect description of the data.</p> <p>For example, the <code>commit(bytes32)</code> method of ENS places a commitement <strong>hash</strong> on-chain. The hash contains the <strong>blinded</strong> name and address; since the name is blinded, the encoded data (i.e. the hash) no longer contains the original values and is insufficient to access the necessary values to be included in a description.</p> <p>By instead describing the commitment indirectly (with the original information intact: NAME, ADDRESS and SECRET) a meaningful description can be computed (e.g. "commit to NAME for ADDRESS (with SECRET)") and the matching data can be computed (i.e. <code>commit(hash(name, owner, secret))</code>).</p> <h3 id="entangling-the-contract-address">Entangling the Contract Address</h3> <p>To prevent data being signed from one contract being used against another, the contract address is entanlged into both the transaction (implicitly via the <code>to</code> field) and in messages by the EIP-191 versions specific data.</p> <p>The use of the zero address is reserved.</p> <h3 id="alternatives">Alternatives</h3> <ul> <li> <p>NatSpec and company are a class of more complex languages that attempt to describe the encoded data directly. Because of the language complexity they often end up being quite large requiring entire runtime environments with ample processing power and memory, as well as additional sandboxing to reduce security concerns. One goal of this is to reduce the complexity to something that could execute on hardware wallets and other simple wallets. These also describe the data directly, which in many cases (such as blinded data), cannot adequately describe the data at all</p> </li> <li> <p>Custom Languages; due to the complexity of Ethereum transactions, any language used would require a lot of expressiveness and re-inventing the wheel. The EVM already exists (it may not be ideal), but it is there and can handle everything necessary.</p> </li> <li> <p>Format Strings (e.g. Trustless Signing UI Protocol; format strings can only operate on the class of regular languages, which in many cases is insufficient to describe an Ethereum transaction. This was an issue quite often during early attempts at solving this problem.</p> </li> <li> <p>The signTypedData <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> has many parallels to what this EIP aims to solve</p> </li> <li> <p>@TODO: More</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>All signatures for messages are generated using <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> which had a previously compatible version byte of <code>0x00</code>, so there should be no concerns with backwards compatibility.</p> <h2 id="test-cases">Test Cases</h2> <p>All test cases operate against the published and verified contracts:</p> <ul> <li>Formatter: Ropsten @ 0x7a89c0521604008c93c97aa76950198bca73d933</li> <li>TestFormatter: Ropsten @ 0xab3045aa85cbcabb06ed3f3fe968fa5457727270</li> </ul> <p>The private key used for signing messages and transactions is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>privateKey = &quot;0x6283185307179586476925286766559005768394338798750211641949889184&quot;</span></span></code></pre><h3 id="messages">Messages</h3> <p><strong>Example: login with signed message</strong></p> <ul> <li>sends selector login()</li> <li>received data with selector doLogin(bytes32 timestamp)</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Input:</span></span> <span class="giallo-l"><span> Address: 0xab3045AA85cBCaBb06eD3F3FE968fA5457727270</span></span> <span class="giallo-l"><span> Describer Input: 0xb34e97e800000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span> i.e. encode(</span></span> <span class="giallo-l"><span> [ &quot;bytes4&quot; ],</span></span> <span class="giallo-l"><span> [ SEL(&quot;login()&quot;) ]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Output:</span></span> <span class="giallo-l"><span> Description: text/plain;Log into ethereum.org?</span></span> <span class="giallo-l"><span> Data: 0x14629d78000000000000000000000000000000000000000000000000000000006010d607</span></span> <span class="giallo-l"><span> i.e. encodeWithSelector(&quot;doLogin(bytes32)&quot;, &quot;0x000000000000000000000000000000000000000000000000000000006010d607&quot; ]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Signing:</span></span> <span class="giallo-l"><span> Preimage: 0x1900ab3045aa85cbcabb06ed3f3fe968fa545772727014629d78000000000000000000000000000000000000000000000000000000006010d607</span></span> <span class="giallo-l"><span> Signature: 0x8b9def29343c85797a580c5cd3607c06e78a53351219f9ba706b9985c1a3c91e702bf678e07f5daf5ef48b3e3cc581202de233904b72cf2c4f7d714ce92075b21c</span></span></code></pre><h3 id="transactions">Transactions</h3> <p>All transaction test cases use the ropsten network (chainId: 3) and for all unspecified properties use 0.</p> <p><strong>Example: ERC-20 transfer</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Input:</span></span> <span class="giallo-l"><span> Address: 0xab3045AA85cBCaBb06eD3F3FE968fA5457727270</span></span> <span class="giallo-l"><span> Describer Input: 0xa9059cbb000000000000000000000000000000000000000000000000000000000000000000000000000000008ba1f109551bd432803012645ac136ddd64dba720000000000000000000000000000000000000000000000002b992b75cbeb6000</span></span> <span class="giallo-l"><span> i.e. encode(</span></span> <span class="giallo-l"><span> [ &quot;bytes4&quot;, &quot;address&quot;, &quot;uint&quot;],</span></span> <span class="giallo-l"><span> [ SEL(&quot;transfer(address,uint256)&quot;), &quot;0x8ba1f109551bD432803012645Ac136ddd64DBA72&quot;, 3.14159e18 ]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>Output:</span></span> <span class="giallo-l"><span> Description: text/plain;Send 3.14159 TOKN to &quot;ricmoose.eth&quot; (0x8ba1f109551bD432803012645Ac136ddd64DBA72)?</span></span> <span class="giallo-l"><span> Described Data: 0xa9059cbb0000000000000000000000000000000000000000000000002b992b75cbeb60000000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72</span></span> <span class="giallo-l"><span> i.e. encodeWithSelector(&quot;transfer(address,uint256)&quot;, &quot;0x8ba1f109551bD432803012645Ac136ddd64DBA72&quot;, 3.14159e18)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Signing:</span></span> <span class="giallo-l"><span> Signed Transaction: 0xf8a280808094ab3045aa85cbcabb06ed3f3fe968fa545772727080b844a9059cbb0000000000000000000000000000000000000000000000002b992b75cbeb60000000000000000000000000008ba1f109551bd432803012645ac136ddd64dba7229a0f33ea492d326ac32d9b7ae203c61bf7cf0ac576fb0cf8be8e4c63dc89c90de12a06c8efb28aaf3b70c032b3bd1edfc664578c49f040cf749bb19b000da56507fb2</span></span></code></pre> <p><strong>Example: ERC-20 approve</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Input:</span></span> <span class="giallo-l"><span> Address: 0xab3045AA85cBCaBb06eD3F3FE968fA5457727270</span></span> <span class="giallo-l"><span> Describer Input: 0x095ea7b3000000000000000000000000000000000000000000000000000000000000000000000000000000008ba1f109551bd432803012645ac136ddd64dba720000000000000000000000000000000000000000000000002b992b75cbeb6000</span></span> <span class="giallo-l"><span> i.e. encode(</span></span> <span class="giallo-l"><span> [ &quot;bytes4&quot;, &quot;address&quot;, &quot;uint&quot;],</span></span> <span class="giallo-l"><span> [ SEL(&quot;approve(address,uint256)&quot;), &quot;0x8ba1f109551bD432803012645Ac136ddd64DBA72&quot;, 3.14159e18 ]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Output:</span></span> <span class="giallo-l"><span> Description: text/plain;Approve &quot;ricmoose.eth&quot; (0x8ba1f109551bD432803012645Ac136ddd64DBA72) to manage 3.14159 TOKN tokens?</span></span> <span class="giallo-l"><span> Described Data: 0xa9059cbb0000000000000000000000000000000000000000000000002b992b75cbeb60000000000000000000000000008ba1f109551bd432803012645ac136ddd64dba72</span></span> <span class="giallo-l"><span> i.e. encodeWithSelector(&quot;approve(address,uint256)&quot;, &quot;0x8ba1f109551bD432803012645Ac136ddd64DBA72&quot;, 3.14159e18)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Signing:</span></span> <span class="giallo-l"><span> Signed Transaction: 0xf8a280808094ab3045aa85cbcabb06ed3f3fe968fa545772727080b844a9059cbb0000000000000000000000000000000000000000000000002b992b75cbeb60000000000000000000000000008ba1f109551bd432803012645ac136ddd64dba7229a0f33ea492d326ac32d9b7ae203c61bf7cf0ac576fb0cf8be8e4c63dc89c90de12a06c8efb28aaf3b70c032b3bd1edfc664578c49f040cf749bb19b000da56507fb2</span></span></code></pre> <p><strong>Example: ENS commit</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Input:</span></span> <span class="giallo-l"><span> Address: 0xab3045AA85cBCaBb06eD3F3FE968fA5457727270</span></span> <span class="giallo-l"><span> Describer Input: 0x0f0e373f000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000e31f43c1d823afaa67a8c5fbb8348176d225a79e65462b0520ef7d3df61b9992ed3bea0c56ead753be7c8b3614e0ce01e4cac41b00000000000000000000000000000000000000000000000000000000000000087269636d6f6f7365000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span> i.e. encode(</span></span> <span class="giallo-l"><span> [ &quot;bytes4&quot;, &quot;string&quot;, &quot;address&quot;, &quot;bytes32&quot;],</span></span> <span class="giallo-l"><span> [ SEL(&quot;commit(string,address,bytes32)&quot;), &quot;ricmoose&quot;, &quot;0xE31f43C1d823AfAA67A8C5fbB8348176d225A79e&quot;, &quot;0x65462b0520ef7d3df61b9992ed3bea0c56ead753be7c8b3614e0ce01e4cac41b&quot; ]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>Output:</span></span> <span class="giallo-l"><span> Description: text/plain;Commit to the ENS name &quot;ricmoose.eth&quot; for 0xE31f43C1d823AfAA67A8C5fbB8348176d225A79e?</span></span> <span class="giallo-l"><span> Described Data: 0xf14fcbc8e4a4f2bb818545497be34c7ab30e6e87e0001df4ba82e7c8b3f224fbaf255b91</span></span> <span class="giallo-l"><span> i.e. encodeWithSelector(&quot;commit(bytes32)&quot;, makeCommitment(&quot;ricmoose&quot;, &quot;0xE31f43C1d823AfAA67A8C5fbB8348176d225A79e&quot;, &quot;0x65462b0520ef7d3df61b9992ed3bea0c56ead753be7c8b3614e0ce01e4cac41b&quot;))</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Signing:</span></span> <span class="giallo-l"><span> Signed Transaction: 0xf88180808094ab3045aa85cbcabb06ed3f3fe968fa545772727080a4f14fcbc8e4a4f2bb818545497be34c7ab30e6e87e0001df4ba82e7c8b3f224fbaf255b912aa0a62b41d1ebda584fe84cf8a05f61b429fe4ec361e13c17f30a23281106b38a8da00bcdd896fe758d8f0cfac46445a48f76f5e9fe27790d67c51412cb98a12a0844</span></span></code></pre> <p><strong>Example: WETH mint()</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Input:</span></span> <span class="giallo-l"><span> Address: 0xab3045AA85cBCaBb06eD3F3FE968fA5457727270</span></span> <span class="giallo-l"><span> Describer Input: 0x1249c58b00000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span> i.e. encode(</span></span> <span class="giallo-l"><span> [ &quot;bytes4&quot; ],</span></span> <span class="giallo-l"><span> [ SEL(&quot;mint()&quot;) ]</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> Value: 1.23 ether</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Output:</span></span> <span class="giallo-l"><span> Description: text/plain;Mint 1.23 WETH (spending 1.23 ether)?</span></span> <span class="giallo-l"><span> Described Data: 0x1249c58b</span></span> <span class="giallo-l"><span> i.e. encodeWithSelector(&quot;mint()&quot;)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Signing:</span></span> <span class="giallo-l"><span> Signed Transaction: 0xf86980808094ab3045aa85cbcabb06ed3f3fe968fa5457727270881111d67bb1bb0000841249c58b29a012df802e1394a97caab23c15c3a8c931668df4b2d6d604ca23f3f6b836d0aafca0071a2aebef6a9848616b4d618912f2003fb4babde3dba451b5246f866281a654</span></span></code></pre><h2 id="reference-implementation">Reference Implementation</h2> <p>@TODO (consider adding it as one or more files in <code>../assets/eip-####/</code>)</p> <p>I will add examples in Solidity and JavaScript.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="escaping-text">Escaping Text</h3> <p>Wallets must be careful when displaying text provided by contracts and proper efforts must be taken to sanitize it, for example, be sure to consider:</p> <ul> <li>HTML could be embedded to attempt to trick web-based wallets into executing code using the script tag (possibly uploading any private keys to a server)</li> <li>In general, extreme care must be used when rendering HTML; consider the ENS names <code>&lt;span style="display:none"&gt;not-&lt;/span&gt;ricmoo.eth</code> or <code>&amp;thinsp;ricmoo.eth</code>, which if rendered without care would appear as <code>ricmoo.eth</code>, which it is not</li> <li>Other marks which require escaping could be included, such as quotes (<code>"</code>), formatting (<code>\n</code> (new line), <code>\f</code> (form feed), <code>\t</code> (tab), any of many non-standard whitespaces), back-slassh (<code>\</code>)</li> <li>UTF-8 has had bugs in the past which could allow arbitrary code execution and crashing renderers; consider using the UTF-8 replacement character (or <em>something</em>) for code-points outside common planes or common sub-sets within planes</li> <li>Homoglyphs attacks</li> <li>Right-to-left marks may affect rendering</li> <li>Many other things, deplnding on your environment</li> </ul> <h3 id="distinguished-signed-data">Distinguished Signed Data</h3> <p>Applications implementing this EIP to sign message data should ensure there are no collisions within the data which could result in ambiguously signed data.</p> <p>@TODO: Expand on this; compare packed data to ABI encoded data?</p> <h3 id="enumeration">Enumeration</h3> <p>If an abort occurs during signing, the response from this call should match the response from a declined signing request; otherwise this could be used for enumeration attacks, etc. A random interactive-scale delay should also be added, otherwise a &lt; 10ms response could be interpreted as an error.</p> <h3 id="replayablility">Replayablility</h3> <p>Transactions contain an explicit nonce, but signed messages do not.</p> <p>For many purposes, such as signing in, a nonce could be injected (using block.timestamp) into the data. The log in service can verify this is a recent timestamp. The timestamp may or may not be omitted from the description string in this case, as it it largely useful internally only.</p> <p>In general, when signing messages a nonce often makes sense to include to prevent the same signed data from being used in the future.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-12-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ben Tinnerhttps://github.com/Terra854 https://wg-eips.ritovision.com/3143/ <h2 id="simple-summary">Simple Summary</h2> <p>Changes the block reward paid to proof-of-work (POW) miners to 5 ETH.</p> <h2 id="abstract">Abstract</h2> <p>Starting with <code>FORK_BLKNUM</code> block rewards will be increased to a base of 5 ETH, uncle and nephew rewards will be adjusted accordingly.</p> <h2 id="motivation">Motivation</h2> <p>Currently, the transaction fees (tx fees) portion of the mining rewards makes up a significant portion of the total rewards per block, at times almost exceeded the block reward of 2 ETH. This have resulted in situations where at times of low tx fees, POW miners decide to point their rigs away from ETH as they will always prefer to mine coins that are the most profitable at any point in time, reducing the security of the ETH network till transaction activity picks up again. By increasing the block rewards back to the original 5 ETH when the network first started, the voliatility will be reduced in terms of the percentage of tx fees that make up the mining rewards per block while increasing the total rewards per block, making it more financially attractive to POW miners to mine ETH barring any gigantic ETH price drops. The increase in block rewards will also allow smaller POW miners ample opporturnity to build up their stores of ETH so that when the time comes to fully transition to ETH 2.0, they may be more willing to become validators as they already have earned the requite amount of ETH needed to do so as opposed to having to spend tens of thousands of dollars to purchase the required ETH directly, increasing the number of validators in the network and therefore strengthening network security.</p> <p>Therefore, the ultimate end goal for this EIP is to give POW miners more incentive to switch to POS once ETH 2.0 is fully implemented since the transition will take a few years to complete and during that time, they will be incentivised to hold on to the tokens instead of selling it straight away in order to prepare to be a validator for ETH 2.0, reducing the selling pressure on ETH and increasing it's value in the long run. A side effect of miners staying on Ethereum is that network security will be assured during the transition period.</p> <h2 id="specification">Specification</h2> <h4 id="adjust-block-uncle-and-nephew-rewards">Adjust Block, Uncle, and Nephew rewards</h4> <p>Adjust the block reward to <code>new_block_reward</code>, where</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_block_reward = 5_000_000_000_000_000_000 if block.number &gt;= FORK_BLKNUM else block.reward</span></span></code></pre> <p>(5E18 wei, or 5,000,000,000,000,000,000 wei, or 5 ETH).</p> <p>Analogue, if an uncle is included in a block for <code>block.number &gt;= FORK_BLKNUM</code> such that <code>block.number - uncle.number = k</code>, the uncle reward is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_uncle_reward = (8 - k) * new_block_reward / 8</span></span></code></pre> <p>This is the existing formula for uncle rewards, simply adjusted with <code>new_block_reward</code>.</p> <p>The nephew reward for <code>block.number &gt;= FORK_BLKNUM</code> is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_nephew_reward = new_block_reward / 32</span></span></code></pre> <p>This is the existing formula for nephew rewards, simply adjusted with <code>new_block_reward</code>.</p> <h2 id="rationale">Rationale</h2> <p>A 5 ETH base reward was chosen as a middle ground between wanting to prevent too high of an inflation rate (10.4% per annum for the first year at 5 ETH per block) and converting as many POW miners as possible into POS validators by making it easier to amass the required ETH needed through POW mining.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no known backward compatibility issues with the introduction of this EIP.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no known security issues presented by this change.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-11-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 Pedro Gomeshttps://github.com/pedrouid ligihttps://github.com/ligi https://wg-eips.ritovision.com/3091/

API Routes for Blockchain explorers

<h2 id="abstract">Abstract</h2> <p>This proposal brings standardization between block explorers API routes when linking transactions, blocks, accounts and tokens.</p> <h2 id="motivation">Motivation</h2> <p>Currently wallets and dapps link transactions and accounts to block explorer web pages but as chain diversity and layer two solutions grow it becomes harder to maintain a consistent user experience. Adding new chains or layer two solutions becomes harder given these endpoints are inconsistent. Standardizing the API routes to these links improves interoperability between wallets and block explorers.</p> <h2 id="specification">Specification</h2> <p>Block explorers will route their webpages accordingly for the following data:</p> <h3 id="blocks">Blocks</h3> <p><code>&lt;BLOCK_EXPLORER_URL&gt;/block/&lt;BLOCK_HASH_OR_HEIGHT&gt;</code></p> <h3 id="transactions">Transactions</h3> <p><code>&lt;BLOCK_EXPLORER_URL&gt;/tx/&lt;TX_HASH&gt;</code></p> <h3 id="accounts">Accounts</h3> <p><code>&lt;BLOCK_EXPLORER_URL&gt;/address/&lt;ACCOUNT_ADDRESS&gt;</code></p> <h3 id="tokens">Tokens</h3> <p><code>&lt;BLOCK_EXPLORER_URL&gt;/token/&lt;TOKEN_ADDRESS&gt;</code></p> <h2 id="rationale">Rationale</h2> <p>The particular paths used in this proposal are chosen to be compatible with the majority of existing block explorers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Incompatible block explorers can use redirects to their existing API routes in order to conform to this EIP.</p> <h2 id="security-considerations">Security Considerations</h2> <p>None</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-11-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Erik Markshttps://github.com/rekmarks Pedro Gomeshttps://github.com/pedrouid Pandapip1https://github.com/Pandapip1 https://wg-eips.ritovision.com/3085/

Adds an RPC method to add EVM-compatible chains

<h2 id="abstract">Abstract</h2> <p>This EIP adds a wallet-namespaced RPC method: <code>wallet_addEtherereumChain</code>, providing a standard interface for adding chains to Ethereum wallets.</p> <h2 id="specification">Specification</h2> <p>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> <p>This proposal defines a new RPC method, <code>wallet_addEthereumChain</code>.</p> <h3 id="wallet-addethereumchain"><code>wallet_addEthereumChain</code></h3> <p>The <code>wallet_addEthereumChain</code> method is used to suggest to the wallet that a new chain be added to the wallet's list of chains. It takes a single parameter and returns <code>null</code> if the chain was added successfully, or an error if the chain was not added.</p> <h4 id="wallet-addethereumchain-parameters"><code>wallet_addEthereumChain</code> Parameters</h4> <p>The <code>wallet_addEthereumChain</code> method takes a single parameter, an <code>EthereumChainAddRequest</code> object, which is defined as follows:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> AddEthereumChainParameter</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> blockExplorerUrls</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> chainName</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> iconUrls</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> nativeCurrency</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> name</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> symbol</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> decimals</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> rpcUrls</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Only the <code>chainId</code> is required per this specification, but a wallet MAY require any other fields listed, impose additional requirements on them, or ignore them outright.</p> <p>If a field does not meet the requirements of this specification and the wallet does not ignore the field, the wallet MUST reject the request.</p> <p>The <code>chainId</code> is the integer ID of the chain as a hexadecimal string, as per <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>. The <code>blockExplorerUrls</code>, <code>iconUrls</code>, and <code>rpcUrls</code> fields are arrays of strings, each of which MUST be a valid URL. The <code>nativeCurrency</code> field is an object with <code>name</code>, <code>symbol</code>, and <code>decimals</code> fields, where <code>decimals</code> is a non-negative integer, and is to be interpreted like in <a href="https://wg-eips.ritovision.com/20/">EIP-20</a>. The <code>chainName</code> field is a string that is the human-readable name of the chain.</p> <p>The wallet MUST reject the request if the <code>chainId</code> is not a valid hexadecimal string, or if the <code>chainId</code> is not a valid chain ID.</p> <p>The wallet MUST reject the request if the <code>rpcUrls</code> field is not provided, or if the <code>rpcUrls</code> field is an empty array. The wallet MUST reject the request if the <code>rpcUrls</code> contains any strings that are not valid URLs. The wallet must reject the request if the <code>chainId</code> does not match the value of the <code>eth_chainId</code> method for any of the RPC urls.</p> <p>The wallet MUST reject the request if the <code>nativeCurrency</code> field is provided, and any of the <code>name</code>, <code>symbol</code>, or <code>decimals</code> fields are missing. The wallet MUST reject the request if the <code>decimals</code> field is a negative integer.</p> <p>The wallet MUST reject the request if the <code>blockExplorerUrls</code> field is provided, and any of the URLs are not valid URLs.</p> <p>The wallet MUST reject the request if the <code>iconUrls</code> field is provided, and any of the URLs are not valid URLs or do not point to a valid image.</p> <p>The wallet MUST reject any URLs that use the <code>file:</code> or <code>http:</code> schemes.</p> <h4 id="wallet-addethereumchain-returns"><code>wallet_addEthereumChain</code> Returns</h4> <p>The method MUST return <code>null</code> if the request was successful, and an error otherwise. The wallet MAY reject the request for any reason.</p> <p>The chain MUST NOT be assumed to be automatically selected by the wallet, even if the wallet does not reject the request.</p> <p>A request to add a chain that was already added SHOULD be successful, unless the user declines the request or the validation fails.</p> <p>The wallet MUST NOT allow the same <code>chainId</code> to be added multiple times. See <a href="https://wg-eips.ritovision.com/3085/#security-considerations">Security Considerations</a> for more information.</p> <h2 id="rationale">Rationale</h2> <p>The design of <code>wallet_addEthereumChain</code> is deliberately ignorant of what it means to "add" a chain to a wallet. The meaning of "adding" a chain to a wallet depends on the wallet implementation.</p> <p>When calling the method, specifying the <code>chainId</code> will always be necessary, since in the universe of Ethereum chains, the <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> chain ID is effectively the chain GUID. The remaining parameters amount to what, in the estimation of the authors, a wallet will minimally require in order to effectively support a chain and represent it to the user. The network ID (per the <code>net_version</code> RPC method) is omitted since it is effectively superseded by the chain ID.</p> <p>For <a href="https://wg-eips.ritovision.com/3085/#security-considerations">security reasons</a>, a wallet should always attempt to validate the chain metadata provided by the requester, and may choose to fetch the metadata elsewhere entirely. Either way, only the wallet can know which chain metadata it needs from the requester in order to "add" the chain. Therefore, all parameters except <code>chainId</code> are specified as optional, even though a wallet may require them in practice.</p> <p>This specification does not mandate that the wallet "switches" its "active" or "currently selected" chain after a successful request, if the wallet has a concept thereof. Just like the meaning of "adding" a chain, "switching" between chains is a wallet implementation detail, and therefore out of scope.</p> <h2 id="security-considerations">Security Considerations</h2> <p><code>wallet_addEthereumChain</code> is a powerful method that exposes the end user to serious risks if implemented incorrectly. Many of these risks can be avoided by validating the request data in the wallet, and clearly disambiguating different chains in the wallet UI.</p> <h3 id="chain-ids">Chain IDs</h3> <p>Since the chain ID used for transaction signing determines which chain the transaction is valid for, handling the chain ID correctly is of utmost importance. The wallet should:</p> <ul> <li>Ensure that a submitted chain ID is valid. <ul> <li>It should be a <code>0x</code>-prefixed hexadecimal string per <a href="https://wg-eips.ritovision.com/695/">EIP-695</a>, and parse to an integer number.</li> </ul> </li> <li>Prevent the same chain ID from being added multiple times. <ul> <li>See the next section for how to handle multiple RPC endpoints.</li> </ul> </li> <li>Only use the submitted chain ID to sign transactions, <strong>never</strong> a chain ID received from an RPC endpoint. <ul> <li>A malicious or faulty endpoint could return arbitrary chain IDs, and potentially cause the user to sign transactions for unintended chains.</li> </ul> </li> <li>Verify that the specified chain ID matches the return value of <code>eth_chainId</code> from the endpoint, as described above.</li> </ul> <h3 id="rpc-endpoints-and-rpc-urls">RPC Endpoints and RPC URLs</h3> <p>Wallets generally interact with chains via an RPC endpoint, identified by some URL. Most wallets ship with a set of chains and corresponding trusted RPC endpoints. The endpoints identified by the <code>rpcUrls</code> parameter cannot be assumed to be honest, correct, or even pointing to the same chain. Moreover, even trusted endpoints can expose users to privacy risks depending on their data collection practices.</p> <p>Therefore, the wallet should:</p> <ul> <li>Inform users that their on-chain activity and IP address will be exposed to RPC endpoints.</li> <li>If an endpoint is unknown to the wallet, inform users that the endpoint may behave in unexpected ways.</li> <li>Observe good web security practices when interacting with the endpoint, such as require HTTPS.</li> <li>Clearly inform the user which RPC URL is being used to communicate with a chain at any given moment, and inform the user of the risks of using multiple RPC endpoints to interact with the same chain.</li> </ul> <h3 id="validating-chain-data">Validating Chain Data</h3> <p>A wallet that implements <code>wallet_addEthereumChain</code> should expect to encounter requests for chains completely unknown to the wallet maintainers. That said, community resources exist that can be leveraged to verify requests for many Ethereum chains. The wallet should maintain a list of known chains, and verify requests to add chains against that list. Indeed, a wallet may even prefer its own chain metadata over anything submitted with a <code>wallet_addEthereumChain</code> request.</p> <h3 id="ux">UX</h3> <p>Adding a new chain to the wallet can have significant implications for the wallet's functionality and the experience of the user. A chain should never be added without the explicit consent of the user, and different chains should be clearly differentiated in the wallet UI. In service of these goals, the wallet should:</p> <ul> <li>When receiving a <code>wallet_addEthereumChain</code> request, display a confirmation informing the user that a specific requester has requested that the chain be added.</li> <li>Ensure that any chain metadata, such as <code>nativeCurrency</code> and <code>blockExplorerUrls</code>, are validated and used to maximum effect in the UI.</li> <li>If any images are provided via <code>iconUrls</code>, ensure that the user understands that the icons could misrepresent the actual chain added.</li> <li>If the wallet UI has a concept of a "currently selected" or "currently active" chain, ensure that the user understands when a chain added using <code>wallet_addEthereumChain</code> becomes selected.</li> </ul> <h3 id="preserving-user-privacy">Preserving User Privacy</h3> <p>Although a request to add a chain that was already added should generally be considered a success, treating such requests as <em>automatic</em> successes leaks information to requesters about the chains a user has added to their wallet. In the interest of preserving user privacy, implementers of <code>wallet_addEthereumChain</code> should consider displaying user confirmations even in these cases. If the user denies the request, the wallet should return the same user rejection error as normal so that requesters cannot learn which chains are supported by the wallet without explicit permission to do so.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-10-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Dr. Christopher Gormanhttps://github.com/chgormanMH https://wg-eips.ritovision.com/3068/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP defines a hash-to-curve precompile for use in BN256 and would allow for cheaper BLS signature verification.</p> <h2 id="abstract">Abstract</h2> <p>There is currently no inexpensive way to perform BLS signature verification for arbitrary messages. This stems from the fact that there is no precompiled contract in the EVM for a hash-to-curve algorithm for the BN256 elliptic curve. The gas cost of calling a deterministic hash-to-curve algorithm written in Solidity is approximately that of one pairing check, although the latter requires an order of magnitude more computation. This EIP remedies this by implementing a hash-to-curve algorithm for the BN256 G1 curve, which would reduce the cost of signature verification to essentially that of the pairing check precompiled contract. We also include a hash-to-curve algorithm for the BN256 G2 group.</p> <h2 id="motivation">Motivation</h2> <p>The precompiled contracts in <a href="https://wg-eips.ritovision.com/198/">EIP-198</a> and <a href="https://wg-eips.ritovision.com/1108/">EIP-1108</a> increased usage of cryptographic operations in the EVM by reducing the gas costs. In particular, the cost reduction from <a href="https://wg-eips.ritovision.com/1108/">EIP-1108</a> helps increase the use of SNARKs in Ethereum via an elliptic curve pairing check; however, a hash-to-curve algorithm enabling arbitrary BLS signature verification on BN256 in the EVM was noticeably missing. There is interest in having a precompiled contract which would allow for signature verification, as noted <a rel="external" href="https://ethereum-magicians.org/t/pre-compile-for-bls/3973">here</a>.</p> <p>At this time, we are able to perform addition, scalar multiplication, and pairing checks in BN256. Reducing these costs in <a href="https://wg-eips.ritovision.com/1108/">EIP-1108</a> made <a rel="external" href="https://github.com/PhilippSchindler/ethdkg">ETHDKG</a>, a distributed key generation protocol in Ethereum, less expensive. ETHDKG by itself is useful; however, what it is lacking is the ability to verify arbitrary BLS signatures. Creating group signatures by aggregating partial signatures is one goal of a DKG protocol. The DKG enables the computation of partial signatures to be combined into a group signature offline, but there is no easy way to verify partial signatures or group signatures in the EVM.</p> <p>In order to perform BLS signature validation, a hash-to-curve algorithm is required. While the MapToGroup method initially discussed in the original BLS <a href="https://wg-eips.ritovision.com/3068/./assets/weilsigs.pdf">paper</a> works in practice, the nondeterministic nature of the algorithm leaves something to be desired as we would like to bound the overall computational cost in the EVM. A deterministic method for mapping to BN curves is given <a href="https://wg-eips.ritovision.com/3068/./assets/latincrypt12.pdf">here</a>; in the paper, Fouque and Tibouchi proved their mapping was indifferentiable from a random oracle. This gives us the desired algorithm.</p> <h2 id="specification">Specification</h2> <p>Here is the pseudocode for the <code>HashToG1</code> function:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function HashToG1(msg)</span></span> <span class="giallo-l"><span> fieldElement0 = HashToBase(msg, 0x00, 0x01)</span></span> <span class="giallo-l"><span> fieldElement1 = HashToBase(msg, 0x02, 0x03)</span></span> <span class="giallo-l"><span> curveElement0 = BaseToG1(fieldElement0)</span></span> <span class="giallo-l"><span> curveElement1 = BaseToG1(fieldElement1)</span></span> <span class="giallo-l"><span> g1Element = ECAdd(curveElement0, curveElement1)</span></span> <span class="giallo-l"><span> return g1Element</span></span> <span class="giallo-l"><span>end function</span></span></code></pre> <p>Here is the pseudocode for <code>HashToBase</code>; <code>msg</code> is the byte slice to be hashed while <code>dsp1</code> and <code>dsp2</code> are domain separation parameters. <code>fieldPrime</code> is the prime of the underlying field.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function HashToBase(msg, dsp1, dsp2)</span></span> <span class="giallo-l"><span> hashResult0 = uint256(Keccak256(dsp1||msg))</span></span> <span class="giallo-l"><span> hashResult1 = uint256(Keccak256(dsp2||msg))</span></span> <span class="giallo-l"><span> constant = 2^256 mod fieldPrime</span></span> <span class="giallo-l"><span> fieldElement0 = hashResult0*constant mod fieldPrime</span></span> <span class="giallo-l"><span> fieldElement1 = hashResult1 mod fieldPrime</span></span> <span class="giallo-l"><span> fieldElement = fieldElement0 + fieldElement1 mod fieldPrime</span></span> <span class="giallo-l"><span> return fieldElement</span></span> <span class="giallo-l"><span>end function</span></span></code></pre> <p>Here is the pseudocode for <code>BaseToG1</code>. All of these operations are performed in the finite field. <code>inverse</code> computes the multiplicative inverse in the underlying finite field; we have the convention <code>inverse(0) == 0</code>. <code>is_square(a)</code> computes the Legendre symbol of the element, returning 1 if <code>a</code> is a square, -1 if <code>a</code> is not a square, and 0 if <code>a</code> is 0. <code>sqrt</code> computes the square root of the element in the finite field; a square root is assumed to exist. <code>sign0</code> returns the sign of the finite field element.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function BaseToG1(t)</span></span> <span class="giallo-l"><span> # All operations are done in the finite field GF(fieldPrime)</span></span> <span class="giallo-l"><span> # Here, the elliptic curve satisfies the equation</span></span> <span class="giallo-l"><span> # y^2 == g(x) == x^3 + curveB</span></span> <span class="giallo-l"><span> constant1 = (-1 + sqrt(-3))/2</span></span> <span class="giallo-l"><span> constant2 = -3</span></span> <span class="giallo-l"><span> constant3 = 1/3</span></span> <span class="giallo-l"><span> constant4 = g(1)</span></span> <span class="giallo-l"><span> s = (constant4 + t^2)^3</span></span> <span class="giallo-l"><span> alpha = inverse(t^2*(constant4 + t^2))</span></span> <span class="giallo-l"><span> x1 = constant1 - constant2*t^4*alpha</span></span> <span class="giallo-l"><span> x2 = -1 - x1</span></span> <span class="giallo-l"><span> x3 = 1 - constant3*s*alpha</span></span> <span class="giallo-l"><span> a1 = x1^3 + curveB</span></span> <span class="giallo-l"><span> a2 = x2^3 + curveB</span></span> <span class="giallo-l"><span> residue1 = is_square(a1)</span></span> <span class="giallo-l"><span> residue2 = is_square(a2)</span></span> <span class="giallo-l"><span> index = (residue1 - 1)*(residue2 - 3)/4 + 1</span></span> <span class="giallo-l"><span> coef1 = ConstantTimeEquality(1, index)</span></span> <span class="giallo-l"><span> coef2 = ConstantTimeEquality(2, index)</span></span> <span class="giallo-l"><span> coef3 = ConstantTimeEquality(3, index)</span></span> <span class="giallo-l"><span> x = coef1*x1 + coef2*x2 + coef3*x3</span></span> <span class="giallo-l"><span> y = sign0(t)*sqrt(x^3 + curveB)</span></span> <span class="giallo-l"><span> return (x, y)</span></span> <span class="giallo-l"><span>end function</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function sign0(t)</span></span> <span class="giallo-l"><span> if t &lt;= (fieldPrime-1)/2</span></span> <span class="giallo-l"><span> return 1</span></span> <span class="giallo-l"><span> else</span></span> <span class="giallo-l"><span> return fieldPrime-1</span></span> <span class="giallo-l"><span> end if</span></span> <span class="giallo-l"><span>end function</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function ConstantTimeEquality(a, b)</span></span> <span class="giallo-l"><span> # This function operates in constant time</span></span> <span class="giallo-l"><span> if a == b</span></span> <span class="giallo-l"><span> return 1</span></span> <span class="giallo-l"><span> else</span></span> <span class="giallo-l"><span> return 0</span></span> <span class="giallo-l"><span> end if</span></span> <span class="giallo-l"><span>end function</span></span></code></pre> <p>In <code>HashToG2</code>, we first map to the underlying twist curve and then clear the cofactor to map to G2. Here is the pseudocode for <code>HashToG2</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function HashToG2(msg)</span></span> <span class="giallo-l"><span> fieldElement00 = HashToBase(msg, 0x04, 0x05)</span></span> <span class="giallo-l"><span> fieldElement01 = HashToBase(msg, 0x06, 0x07)</span></span> <span class="giallo-l"><span> fieldElement10 = HashToBase(msg, 0x08, 0x09)</span></span> <span class="giallo-l"><span> fieldElement11 = HashToBase(msg, 0x0a, 0x0b)</span></span> <span class="giallo-l"><span> fieldElement0 = (fieldElement00, fieldElement01)</span></span> <span class="giallo-l"><span> fieldElement1 = (fieldElement10, fieldElement11)</span></span> <span class="giallo-l"><span> twistElement0 = BaseToTwist(fieldElement0)</span></span> <span class="giallo-l"><span> twistElement1 = BaseToTwist(fieldElement1)</span></span> <span class="giallo-l"><span> twistElement = ECAdd(twistElement0, twistElement1)</span></span> <span class="giallo-l"><span> g2Element = ClearCofactor(twistElement)</span></span> <span class="giallo-l"><span> return g2Element</span></span> <span class="giallo-l"><span>end function</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function ClearCofactor(twistElement)</span></span> <span class="giallo-l"><span> return ECMul(twistElement, cofactor)</span></span> <span class="giallo-l"><span>end function</span></span></code></pre> <p>Here is the pseudocode for <code>BaseToTwist</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function BaseToTwist(t)</span></span> <span class="giallo-l"><span> # All operations are done in the finite field GF(fieldPrime^2)</span></span> <span class="giallo-l"><span> # Here, the twist curve satisfies the equation</span></span> <span class="giallo-l"><span> # y^2 == g&#39;(x) == x^3 + curveBPrime</span></span> <span class="giallo-l"><span> constant1 = (-1 + sqrt(-3))/2</span></span> <span class="giallo-l"><span> constant2 = -3</span></span> <span class="giallo-l"><span> constant3 = 1/3</span></span> <span class="giallo-l"><span> constant4 = g&#39;(1)</span></span> <span class="giallo-l"><span> s = (constant4 + t^2)^3</span></span> <span class="giallo-l"><span> alpha = inverse(t^2*(constant4 + t^2))</span></span> <span class="giallo-l"><span> x1 = constant1 - constant2*t^4*alpha</span></span> <span class="giallo-l"><span> x2 = -1 - x1</span></span> <span class="giallo-l"><span> x3 = 1 - constant3*s*alpha</span></span> <span class="giallo-l"><span> a1 = x1^3 + curveBPrime</span></span> <span class="giallo-l"><span> a2 = x2^3 + curveBPrime</span></span> <span class="giallo-l"><span> residue1 = is_square(a1)</span></span> <span class="giallo-l"><span> residue2 = is_square(a2)</span></span> <span class="giallo-l"><span> index = (residue1 - 1)*(residue2 - 3)/4 + 1</span></span> <span class="giallo-l"><span> coef1 = ConstantTimeEquality(1, index)</span></span> <span class="giallo-l"><span> coef2 = ConstantTimeEquality(2, index)</span></span> <span class="giallo-l"><span> coef3 = ConstantTimeEquality(3, index)</span></span> <span class="giallo-l"><span> x = coef1*x1 + coef2*x2 + coef3*x3</span></span> <span class="giallo-l"><span> y = sign0(t)*sqrt(x^3 + curveBPrime)</span></span> <span class="giallo-l"><span> return (x, y)</span></span> <span class="giallo-l"><span>end function</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The BaseToG1 algorithm is based on the original Fouque and Tibouchi <a href="https://wg-eips.ritovision.com/3068/./assets/latincrypt12.pdf">paper</a> with modifications based on Wahby and Boneh's <a href="https://wg-eips.ritovision.com/3068/./assets/2019-403_BLS12_H2C.pdf">paper</a>. There is freedom in choosing the HashToBase function and this could easily be changed. Within HashToBase, the particular hashing algorithm (Keccak256 in our case) could also be modified. It may be desired to change the call to <code>sign0</code> at the end of BaseToG1 and BaseToTwist with <code>is_square</code>, as this would result in the same deterministic map to curve from the Fouque and Tibouchi <a href="https://wg-eips.ritovision.com/3068/./assets/latincrypt12.pdf">paper</a> and ensure HashToG1 is indifferentiable from a random oracle; they proved this result in their paper. It may be possible to show that switching the <code>is_square</code> call with <code>sign0</code> does not affect indifferentiability, although this has not been proven.</p> <p>The HashToG2 algorithm follows from the Wahby and Boneh <a href="https://wg-eips.ritovision.com/3068/./assets/2019-403_BLS12_H2C.pdf">paper</a>. Algorithms for computing <code>inverse</code>, <code>is_square</code>, and <code>sqrt</code> in finite field GF(fieldPrime^2) can be found <a href="https://wg-eips.ritovision.com/3068/./assets/2012-685_Square_Root_Even_Ext.pdf">here</a>.</p> <p>We now discuss the potential gas cost for the HashToG1 and HashToG2 operations. On a local machine, ECMul was clocked at 68 microseconds per operation. The same machine clocked HashToG1 at 94 microseconds per operation when hashing 32 bytes into G1 and 105 microseconds per operation when hashing 1024 bytes into G1. Given that it currently costs 6000 gas for ECMul, this gives us an estimated gas cost for HashToG1 at <code>8500 + len(bytes)</code>. Similarly, HashToG2 was clocked at 886 microseconds per operation when hashing 32 bytes into G2 and 912 microseconds per operation when hashing 1024 bytes into G2. This allows us to estimate the gas cost at <code>80000 + 3*len(bytes)</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backward compatibility concerns.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>Due to recent <a href="https://wg-eips.ritovision.com/3068/./assets/2015-1027_exTNFS.pdf">work</a>, the 128-bit security promised by the BN256 elliptic curve no longer applies; this was mentioned in the Cloudflare BN256 <a rel="external" href="https://github.com/cloudflare/bn256">library</a>. There has been some discussion on the exact security decrease from this advancement; see these <a href="https://wg-eips.ritovision.com/3068/./assets/2016-1102_Assessing_NFS_Advances.pdf">two</a> <a href="https://wg-eips.ritovision.com/3068/./assets/2017-334.pdf">papers</a> for different estimates. The more conservative estimate puts the security of BN256 at 100-bits. While this is likely still out of reach for many adversaries, it should give us pause. This reduced security was noted in the recent MadNet <a href="https://wg-eips.ritovision.com/3068/./assets/madnet.pdf">whitepaper</a>, and this security concern was partially mitigated by requiring Secp256k1 signatures of the partial group signatures in order for those partial signatures to be valid. Full disclosure: the author of this EIP works for MadHive, assisted in the development of MadNet, and helped write the MadNet whitepaper.</p> <p>The security concerns of the BN256 elliptic curve affect any operation using pairing check because it is related to the elliptic curve pairing; they are independent of this EIP.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-10-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Weijia Zhanghttps://github.com/weijia31415 Peter Robinsonhttps://github.com/drinkcoffee https://wg-eips.ritovision.com/3220/ <h2 id="simple-summary">Simple Summary</h2> <p>A self-verifying unique blockchain identifier that deals with forks.</p> <h2 id="abstract">Abstract</h2> <p>The crosschain-id is a 32 byte hex string and with some bytes extracted from blockchain hash and some manually defined to characterize a blockchain. We also propose a registration and lookup service to retrieve blockchain metadata from the crosschain-id.</p> <h2 id="motivation">Motivation</h2> <p>With the success of Bitcoin and Ethereum, various blockchains such as EOS, Ripple, Litecoin, Besu, Wanchain and the like have been developed and are growing at a fast pace. There are also other private and consortium blockchains such as Hyperledger Fabric, Hyperledger Besu, Stellar, Corda, Quorum that only allow nodes with permitted identities to join the blockchain network. The growth of public and private blockchains imposes challenges for inter-chain interoperability, particularly when these chains are heterogeneous and incompatible. Enterprise Ethereum Alliance formed Crosschain Interoperability Task Force (CITF) to look into common crosschain problems and solutions. CITF team noticed that there is a lack of unique identifier to charaterise and describe a blockchain. Several proprosals were discussed in EEA Crosschain Interoperability Task Force meetings and discussions.</p> <p><a href="https://wg-eips.ritovision.com/155/">EIP-155</a> provides a unique identifier to a blockchain to provide simple relay attack protection. This specification defines an integer for Chainid for a blockchain and sign the chainid into a transaction data and hence present attackers to send same transaction to different blockchains. This specification will require blockchains to define a chainid and register the chainid in a public repository.</p> <p>The challenge of using an integer for chainid is that it is not broad enough to cover all blockchains and it does not prevent different blockchains using the same chainid. Also, it does not address the issue for two forked blockchains having the same chainid.</p> <p>Hence there is need for a more robust blockchain identifier that will overcome these drawbacks, especially for crosschain operations where multiple chains are involved. A blockchain identifier (crosschain id) should be unique and satisfy the following requirements:</p> <ul> <li>should provide identification, description, and discovery of blockchains.</li> <li>should provide unique identification of each blockchain in the crosschain service ecosystem.</li> <li>should provide descriptions for a blockchain identities such as chainId, name, type, consensus scheme etc.</li> <li>should provide discovery mechanism for supported blockchains and also for new blockchains in the ecosystem.</li> <li>should provide a mechanism for a joining blockchain to register to the ecosystem.</li> <li>should provide a mechanism for a blockchain to edit properties or unregister from the crosschain ecosystem.</li> <li>should provide a mechanism to get some critical information of the blockchain</li> <li>should provide a mechanism to differentiate an original blockchain and a forked blockchain</li> <li>should provide a mechanism to verify a chainid without external registration service</li> </ul> <h2 id="specification">Specification</h2> <h3 id="definition-of-a-32-byte-crosschain-id">Definition of a 32 byte crosschain id</h3> <table><thead><tr><th>Name</th><th>Size(bytes)</th><th>Description</th></tr></thead><tbody> <tr><td>Truncated Block Hash</td><td>16</td><td>This is the block hash of the genesis block or the block hash of the block immediate prior to the fork for a fork of a blockchain. The 16 bytes is the 16 least significant bytes, assuming network byte order.</td></tr> <tr><td>Native Chain ID</td><td>8</td><td>This is the <strong>Chain Id</strong> value that should be used with the blockchain when signing transactions. For blockchains that do not have a concept of <strong>Chain Id</strong>, this value is zero.</td></tr> <tr><td>Chain Type</td><td>2</td><td>Reserve 0x00 as undefined chaintype. 0x01 as mainnet type. 0x1[0-A]: testnet, 0x2[0-A]: private development network</td></tr> <tr><td>Governance Identifier</td><td>2</td><td>For new blockchains, a governance_identifier can be specified to identify an original <strong>owner</strong> of a blockchain, to help settle forked / main chain disputes. For all existing blockchains and for blockchains that do not have the concept of an <strong>owner</strong>, this field is zero.</td></tr> <tr><td>Reserved</td><td>3</td><td>Reserved for future use. Use 000000 for now.</td></tr> <tr><td>Checksum</td><td>1</td><td>Used to verify the integrity of the identifier. This integrity check is targeted at detecting Crosschain Identifiers mis-typed by human users. The value is calculated as the truncated SHA256 message digest of the rest of the identifier, using the least significant byte, assuming network byte order. Note that this checksum byte only detects integrity with a probability of one in 256. This probability is adequate for the intended usage of detecting typographical errors by people manually entering the Crosschain Identifier.</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>We have considered various alternative specifications such as using a random unique hex string to represent a blockchain. The drawback of this method is that the random id can not be used to verify a blockchain's intrinsic identity such as the blockhash of the genesis block. A second alternative is simply using a genesis blockhash to represent a blockchain id for crosschain operations. The drawback of this is that this id does not have information about the property of the blockchain and it has problem when a blockchain is forked into two blockchain.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Crosschainid can be backward compatible with EIP-155. The crosschain id contains an 8 byte segment to record the <code>Native Chain ID</code>. For Ethereum chains, that can be used for a value intended to be used with EIP-155.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Collision of crosschain id: Two blockchains can contain the same crosschain id and hence making the mistakenly transfer assets to a wrong blockchain.<br /> This security concern is addressed by comparing the hash of the crosschain id with the hash of the genesis block. If it matches, then the crosschain id is verified. If not, the crosschain id can be compared with the forked blockhash. If none of the blockhash match the crosschain id hash, then the crosschain id cannot be verified.</p> <p>Preventing relay attack: Although crosschain id by itself is different from chainid and it is not signed into blockchain transaction, the crosschain id can still be used for presenting relay attack. An application that handles crosschain transaction can verified the crosschain id with its blockhash and decide whether the transaction is valid or not. Any transaction with a non-verifiable crosschain id should be rejected.</p> <p>The crosschain-id are not required to be signed into blockchaid tx. For blockchains that do not cryptographically sign crosschain id into the blocks, the crosschain id cannot be verified with the blocks itself and have to be verified with external smart contract address and offchain utilities implemented based on the crosschain id specification.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-10-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Abdelhamid Bakhtahttps://github.com/abdelhamidbakhta https://wg-eips.ritovision.com/3044/ <h2 id="simple-summary">Simple Summary</h2> <p>Add basefee field to <code>eth_getBlockByNumber</code> RPC endpoint response.</p> <h2 id="abstract">Abstract</h2> <p>Adds <code>baseFee</code> property to the <code>eth_getBlockByNumber</code> JSON-RPC request <code>result</code> object. This property will contain the value of the base fee for any block after the EIP-1559 fork.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> introduces a base fee per gas in protocol. This value is maintained under consensus as a new field in the block header structure. Users may need value of the base fee at a given block. Base fee value is important to make gas price predictions more accurate.</p> <h2 id="specification">Specification</h2> <h3 id="eth-getblockbynumber"><code>eth_getBlockByNumber</code></h3> <h4 id="description">Description</h4> <p>Returns information about a block specified by number. Every block returned by this endpoint whose block number is before the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block <strong>MUST NOT</strong> include a <code>baseFee</code> field. Every block returned by this endpoint whose block number is on or after the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block <strong>MUST</strong> include a <code>baseFee</code> field.</p> <h4 id="parameters">Parameters</h4> <p>Parameters remain unchanged.</p> <h4 id="returns">Returns</h4> <p>For the full specification of <code>eth_getBlockByNumber</code> see <a href="https://wg-eips.ritovision.com/1474/">EIP-1474</a>. Add a new JSON field to the <code>result</code> object for block headers containing a base fee (post <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block).</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>baseFee</code> - base fee for this block</li> </ul> <h4 id="example">Example</h4> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1559,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getBlockByNumber&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;:[&quot;latest&quot;, true]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1559,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">difficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">extraData</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">baseFee</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasLimit</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logsBloom</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">miner</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4e65fda2159562a496f9f3522f89122a3088497a</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">number</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b4</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">parentHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">sha3Uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">size</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">stateRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">timestamp</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x54e34e8e</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">totalDifficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactions</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionsRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The addition of a single parameter instead of introducing a whole new endpoint was the simplest change that would be easiest to get integrated. For backward compatibility we decided to not include the base fee in the response for pre-1559 blocks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Backwards compatible. Calls related to block prior to <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block will omit the base fee field in the response.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The added field (<code>baseFee</code>) is informational and does not introduce technical security issues.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-10-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Abdelhamid Bakhtahttps://github.com/abdelhamidbakhta https://wg-eips.ritovision.com/3045/ <h2 id="simple-summary">Simple Summary</h2> <p>Add basefee field to <code>eth_getUncleByBlockHashAndIndex</code> RPC endpoint response.</p> <h2 id="abstract">Abstract</h2> <p>Adds <code>baseFee</code> property to the <code>eth_getUncleByBlockHashAndIndex</code> JSON-RPC request <code>result</code> object. This property will contain the value of the base fee for any block after the EIP-1559 fork.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> introduces a base fee per gas in protocol. This value is maintained under consensus as a new field in the block header structure. Users may need value of the base fee at a given block. Base fee value is important to make gas price predictions more accurate.</p> <h2 id="specification">Specification</h2> <h3 id="eth-getunclebyblockhashandindex"><code>eth_getUncleByBlockHashAndIndex</code></h3> <h4 id="description">Description</h4> <p>Returns information about an uncle specified by block hash and uncle index position Every block returned by this endpoint whose block number is before the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block <strong>MUST NOT</strong> include a <code>baseFee</code> field. Every block returned by this endpoint whose block number is on or after the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block <strong>MUST</strong> include a <code>baseFee</code> field.</p> <h4 id="parameters">Parameters</h4> <p>Parameters remain unchanged.</p> <h4 id="returns">Returns</h4> <p>For the full specification of <code>eth_getUncleByBlockHashAndIndex</code> see <a href="https://wg-eips.ritovision.com/1474/">EIP-1474</a>. Add a new JSON field to the <code>result</code> object for block headers containing a base fee (post <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block).</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>baseFee</code> - base fee for this block</li> </ul> <h4 id="example">Example</h4> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1559,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getUncleByBlockHashAndIndex&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;:[&quot;0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b&quot;, &quot;0x0&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1559,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">difficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">extraData</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">baseFee</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasLimit</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logsBloom</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">miner</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4e65fda2159562a496f9f3522f89122a3088497a</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">number</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b4</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">parentHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">sha3Uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">size</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">stateRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">timestamp</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x54e34e8e</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">totalDifficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactions</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionsRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The addition of a single parameter instead of introducing a whole new endpoint was the simplest change that would be easiest to get integrated. For backward compatibility we decided to not include the base fee in the response for pre-1559 blocks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Backwards compatible. Calls related to block prior to <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block will omit the base fee field in the response.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The added field (<code>baseFee</code>) is informational and does not introduce technical security issues.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-10-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Abdelhamid Bakhtahttps://github.com/abdelhamidbakhta https://wg-eips.ritovision.com/3046/ <h2 id="simple-summary">Simple Summary</h2> <p>Add basefee field to <code>eth_getUncleByBlockNumberAndIndex</code> RPC endpoint response.</p> <h2 id="abstract">Abstract</h2> <p>Adds <code>baseFee</code> property to the <code>eth_getUncleByBlockNumberAndIndex</code> JSON-RPC request <code>result</code> object. This property will contain the value of the base fee for any block after the EIP-1559 fork.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> introduces a base fee per gas in protocol. This value is maintained under consensus as a new field in the block header structure. Users may need value of the base fee at a given block. Base fee value is important to make gas price predictions more accurate.</p> <h2 id="specification">Specification</h2> <h3 id="eth-getunclebyblocknumberandindex"><code>eth_getUncleByBlockNumberAndIndex</code></h3> <h4 id="description">Description</h4> <p>Returns information about an uncle specified by block number and uncle index position Every block returned by this endpoint whose block number is before the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block <strong>MUST NOT</strong> include a <code>baseFee</code> field. Every block returned by this endpoint whose block number is on or after the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block <strong>MUST</strong> include a <code>baseFee</code> field.</p> <h4 id="parameters">Parameters</h4> <p>Parameters remain unchanged.</p> <h4 id="returns">Returns</h4> <p>For the full specification of <code>eth_getUncleByBlockNumberAndIndex</code> see <a href="https://wg-eips.ritovision.com/1474/">EIP-1474</a>. Add a new JSON field to the <code>result</code> object for block headers containing a base fee (post <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block).</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>baseFee</code> - base fee for this block</li> </ul> <h4 id="example">Example</h4> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1559,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getUncleByBlockNumberAndIndex&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;:[&quot;latest&quot;, &quot;0x0&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1559,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">difficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">extraData</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">baseFee</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasLimit</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logsBloom</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">miner</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4e65fda2159562a496f9f3522f89122a3088497a</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">number</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b4</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">parentHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">sha3Uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">size</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">stateRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">timestamp</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x54e34e8e</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">totalDifficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactions</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionsRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The addition of a single parameter instead of introducing a whole new endpoint was the simplest change that would be easiest to get integrated. For backward compatibility we decided to not include the base fee in the response for pre-1559 blocks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Backwards compatible. Calls related to block prior to <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block will omit the base fee field in the response.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The added field (<code>baseFee</code>) is informational and does not introduce technical security issues.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-10-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Abdelhamid Bakhtahttps://github.com/abdelhamidbakhta https://wg-eips.ritovision.com/3041/ <h2 id="simple-summary">Simple Summary</h2> <p>Add basefee field to <code>eth_getBlockByHash</code> RPC endpoint response.</p> <h2 id="abstract">Abstract</h2> <p>Adds <code>baseFee</code> property to the <code>eth_getBlockByHash</code> JSON-RPC request <code>result</code> object. This property will contain the value of the base fee for any block after the EIP-1559 fork.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> introduces a base fee per gas in protocol. This value is maintained under consensus as a new field in the block header structure. Users may need value of the base fee at a given block. Base fee value is important to make gas price predictions more accurate.</p> <h2 id="specification">Specification</h2> <h3 id="eth-getblockbyhash"><code>eth_getBlockByHash</code></h3> <h4 id="description">Description</h4> <p>Returns information about a block specified by hash. Every block returned by this endpoint whose block number is before the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block <strong>MUST NOT</strong> include a <code>baseFee</code> field. Every block returned by this endpoint whose block number is on or after the <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block <strong>MUST</strong> include a <code>baseFee</code> field.</p> <h4 id="parameters">Parameters</h4> <p>Parameters remain unchanged.</p> <h4 id="returns">Returns</h4> <p>For the full specification of <code>eth_getBlockByHash</code> see <a href="https://wg-eips.ritovision.com/1474/">EIP-1474</a>. Add a new JSON field to the <code>result</code> object for block headers containing a base fee (post <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block).</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>baseFee</code> - base fee for this block</li> </ul> <h4 id="example">Example</h4> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1559,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getBlockByHash&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;:[&quot;0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331&quot;, true]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1559,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">difficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">extraData</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">baseFee</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasLimit</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logsBloom</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">miner</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4e65fda2159562a496f9f3522f89122a3088497a</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">number</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b4</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">parentHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">sha3Uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">size</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">stateRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">timestamp</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x54e34e8e</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">totalDifficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactions</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionsRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The addition of a single parameter instead of introducing a whole new endpoint was the simplest change that would be easiest to get integrated. For backward compatibility we decided to not include the base fee in the response for pre-1559 blocks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Backwards compatible. Calls related to block prior to <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> fork block will omit the base fee field in the response.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The added field (<code>baseFee</code>) is informational and does not introduce technical security issues.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-10-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Youssef El Housnihttps://github.com/yelhousni Michael Connorhttps://github.com/iAmMichaelConnor Aurore Guillevicaurore.guillevic@inria.fr hujw77https://github.com/hujw77 https://wg-eips.ritovision.com/3026/

Precompiles for BW6-761 curve operations

<h2 id="abstract">Abstract</h2> <p>This precompile adds operations for the BW6-761 curve (from the EY/Inria <strong>Optimized and secure pairing-friendly elliptic curves suitable for one layer proof composition</strong> research paper) as a precompile in a set necessary to <em>efficiently</em> perform verification of one-layer composed zkSNARKs proofs. If <code>block.number &gt;= X</code> we introduce <em>seven</em> separate precompiles to perform the following operations (addresses to be determined):</p> <ul> <li>BW6_G1_ADD - to perform point addition on a curve defined over a prime field</li> <li>BW6_G1_MUL - to perform point multiplication on a curve defined over a prime field</li> <li>BW6_G1_MULTIEXP - to perform multiexponentiation on a curve defined over a prime field</li> <li>BW6_G2_ADD - to perform point addition on a curve twist defined the base a prime field</li> <li>BW6_G2_MUL - to perform point multiplication on a curve twist defined over a prime field</li> <li>BW6_G2_MULTIEXP - to perform multiexponentiation on a curve twist defined over a prime field</li> <li>BW6_PAIRING - to perform a pairing operations between a set of <em>pairs</em> of (G1, G2) points</li> </ul> <p>The multiexponentiation operations are a generalization of point multiplication, but separate precompiles are prosposed because running a single MUL through MULTIEXP seems to be 20% more expensive.</p> <h2 id="motivation">Motivation</h2> <p>This EIP is based on and tends to replace matter-labs' proposal for significant performance reasons. In most applications, BW6-761 is used as an outer curve to BLS12-377 considered in <a href="https://wg-eips.ritovision.com/2539/">EIP-2539</a>. The motivation of this precompile is to allow efficient one-layer composition of SNARK proofs. Currently this is done by Zexe using the BLS12-377/CP6-782 pair of curves. This precompile proposes a replacement of CP6-782 by BW6-761, which allows much faster operations. For example, it was shown that verifying a Groth16 proof with BW6-761 is 30 times faster than with CP6-782.</p> <h3 id="proposed-addresses-table">Proposed addresses table</h3> <table><thead><tr><th>Precompile</th><th>Address</th></tr></thead><tbody> <tr><td>BW6_G1_ADD</td><td>0x1e</td></tr> <tr><td>BW6_G1_MUL</td><td>0x1f</td></tr> <tr><td>BW6_G1_MULTIEXP</td><td>0x20</td></tr> <tr><td>BW6_G2_ADD</td><td>0x21</td></tr> <tr><td>BW6_G2_MUL</td><td>0x22</td></tr> <tr><td>BW6_G2_MULTIEXP</td><td>0x23</td></tr> <tr><td>BW6_PAIRING</td><td>0x24</td></tr> </tbody></table> <h2 id="specification">Specification</h2> <p>Curve parameters:</p> <p>The BW6-761 <code>y^2=x^3-1</code> curve is fully defined by the following set of parameters:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Base field modulus = 0x122e824fb83ce0ad187c94004faff3eb926186a81d14688528275ef8087be41707ba638e584e91903cebaff25b423048689c8ed12f9fd9071dcd3dc73ebff2e98a116c25667a8f8160cf8aeeaf0a437e6913e6870000082f49d00000000008b</span></span> <span class="giallo-l"><span>A coefficient = 0x0</span></span> <span class="giallo-l"><span>B coefficient = 0x122e824fb83ce0ad187c94004faff3eb926186a81d14688528275ef8087be41707ba638e584e91903cebaff25b423048689c8ed12f9fd9071dcd3dc73ebff2e98a116c25667a8f8160cf8aeeaf0a437e6913e6870000082f49d00000000008a</span></span> <span class="giallo-l"><span>Main subgroup order = 0x1ae3a4617c510eac63b05c06ca1493b1a22d9f300f5138f1ef3622fba094800170b5d44300000008508c00000000001</span></span> <span class="giallo-l"><span>Extension tower:</span></span> <span class="giallo-l"><span>Fp3 construction: (Fp3 = Fp[u]/u^3+4)</span></span> <span class="giallo-l"><span>Fp cubic non-residue = 0x122e824fb83ce0ad187c94004faff3eb926186a81d14688528275ef8087be41707ba638e584e91903cebaff25b423048689c8ed12f9fd9071dcd3dc73ebff2e98a116c25667a8f8160cf8aeeaf0a437e6913e6870000082f49d000000000087</span></span> <span class="giallo-l"><span>Twist parameters:</span></span> <span class="giallo-l"><span>Twist type: M</span></span> <span class="giallo-l"><span>twist curve A coefficient c0 = 0x0</span></span> <span class="giallo-l"><span> c1 = 0x0</span></span> <span class="giallo-l"><span>twist curve B coefficient c0 = 0x4</span></span> <span class="giallo-l"><span> c1 = 0x0</span></span> <span class="giallo-l"><span>Generators:</span></span> <span class="giallo-l"><span>G1:</span></span> <span class="giallo-l"><span>X = 0x1075b020ea190c8b277ce98a477beaee6a0cfb7551b27f0ee05c54b85f56fc779017ffac15520ac11dbfcd294c2e746a17a54ce47729b905bd71fa0c9ea097103758f9a280ca27f6750dd0356133e82055928aca6af603f4088f3af66e5b43d</span></span> <span class="giallo-l"><span>Y = 0x58b84e0a6fc574e6fd637b45cc2a420f952589884c9ec61a7348d2a2e573a3265909f1af7e0dbac5b8fa1771b5b806cc685d31717a4c55be3fb90b6fc2cdd49f9df141b3053253b2b08119cad0fb93ad1cb2be0b20d2a1bafc8f2db4e95363</span></span> <span class="giallo-l"><span>G2:</span></span> <span class="giallo-l"><span>X = 0x110133241d9b816c852a82e69d660f9d61053aac5a7115f4c06201013890f6d26b41c5dab3da268734ec3f1f09feb58c5bbcae9ac70e7c7963317a300e1b6bace6948cb3cd208d700e96efbc2ad54b06410cf4fe1bf995ba830c194cd025f1c</span></span> <span class="giallo-l"><span>Y = 0x17c3357761369f8179eb10e4b6d2dc26b7cf9acec2181c81a78e2753ffe3160a1d86c80b95a59c94c97eb733293fef64f293dbd2c712b88906c170ffa823003ea96fcd504affc758aa2d3a3c5a02a591ec0594f9eac689eb70a16728c73b61</span></span> <span class="giallo-l"><span>Pairing parameters:</span></span> <span class="giallo-l"><span>e(P,Q)=(ML1(P,Q)*ML2(P,Q)^q)^FE</span></span> <span class="giallo-l"><span>|loop_count_1| (first miller loop ML1 count) = 0x8508c00000000002</span></span> <span class="giallo-l"><span>|loop_count_2| (second miller loop ML2 count) = 0x23ed1347970dec008a442f991fffffffffffffffffffffff</span></span> <span class="giallo-l"><span>loop_count_1 is negative = false</span></span> <span class="giallo-l"><span>loop_count_2 is negative = false</span></span></code></pre><h3 id="encoding">Encoding</h3> <h4 id="field-elements-encoding">Field elements encoding:</h4> <p>To encode points involved in the operation one has to encode elements of only the base field.</p> <p>The base field element (Fp) is encoded as <code>96</code> bytes by performing BigEndian encoding of the corresponding (unsigned) integer. The corresponding integer <strong>MUST</strong> be less than the base field modulus.</p> <p>If encodings do not follow this spec anywhere during parsing in the precompile, the precompile <strong>MUST</strong> revert with "endoding error".</p> <h4 id="encoding-of-uncompressed-points">Encoding of uncompressed points:</h4> <p>Points in both G1 and G2 can be expressed as <code>(x, y)</code> affine coordinates, where <code>x</code> and <code>y</code> are elements of the base field. Therefore, points in both G1 and G2 are encoded as the byte concatenation of the field element encodings of the <code>x</code> and <code>y</code> affine coordinates. The total encoding length for a G1/G2 point is thus <code>192</code> bytes.</p> <h4 id="point-at-infinity-encoding">Point at infinity encoding:</h4> <p>Also referred as the "zero point". For BW6-761 (<code>y^2=x^3-1</code>) and its M-twisted curves (<code>y^3=x^3+4</code>), the point with coordinates <code>(0, 0)</code> (formal zeros in Fp) is <em>not</em> on the curve, and so the encoding of <code>(0, 0)</code> is used as a convention to encode the point at infinity.</p> <h4 id="encoding-of-scalars-for-multiplication-and-multiexponentiation-operations">Encoding of scalars for multiplication and multiexponentiation operations:</h4> <p>For multiplication and multiexponentiation operations, a scalar is encoded as <code>64</code> bytes by performing BigEndian encoding of the corresponding (unsigned) integer.</p> <p>Note that the main subgroup order for BW6-761 is actually only <code>377</code> bits (<code>48</code> bytes), but an encoding of <code>64</code> bytes has been chosen to have a <code>32</code>-byte-aligned ABI (representable as e.g. <code>bytes32[2]</code> or <code>uint256[2]</code>).</p> <p>The corresponding integer <strong>MAY</strong> be greater than the main subgroup order.</p> <h3 id="abi-for-operations">ABI for operations</h3> <h4 id="abi-for-g1-addition">ABI for G1 addition</h4> <p>G1 addition call expects <code>384</code> bytes as an input that is interpreted as the byte concatenation of two G1 points (point-encoded as <code>192</code> bytes each). Output is a point-encoding of the addition operation result.</p> <p>Error cases:</p> <ul> <li>Either of the points being not on the curve</li> <li>Input has invalid length</li> <li>Field element encoding rules apply (obviously)</li> </ul> <h4 id="abi-for-g1-multiplication">ABI for G1 multiplication</h4> <p>G1 multiplication call expects <code>256</code> bytes as an input that is interpreted as the byte concatenation of the point-encoding of a G1 point (<code>192</code> bytes) and the encoding of a scalar value (<code>64</code> bytes). Output is a point-encoding of the multiplication operation result.</p> <p>Error cases:</p> <ul> <li>Point being not on the curve</li> <li>Input has invalid length</li> <li>Field element encoding rules apply (obviously)</li> <li>Scalar encoding rules apply (obviously)</li> </ul> <h4 id="abi-for-g1-multiexponentiation">ABI for G1 multiexponentiation</h4> <p>G1 multiplication call expects <code>256*k</code> bytes as an input that is interpreted as the byte concatenation of <code>k</code> slices, each of them being a byte concatenation of the point-encoding of a G1 point (<code>192</code> bytes) and the encoding of a scalar value (<code>64</code> bytes). Output is an encoding of the multiexponentiation operation result.</p> <p>Error cases:</p> <ul> <li>Any of the G1 points being not on the curve</li> <li>Input has invalid length</li> <li>Field element encoding rules apply (obviously)</li> <li>Scalar encoding rules apply (obviously)</li> </ul> <h4 id="abi-for-g2-addition">ABI for G2 addition</h4> <p>G2 addition call expects <code>384</code> bytes as an input that is interpreted as the byte concatenation of two G2 points (point-encoded as <code>192</code> bytes each). Output is a point-encoding of the addition operation result.</p> <p>Error cases:</p> <ul> <li>Either of points being not on the curve</li> <li>Input has invalid length</li> <li>Field elements encoding rules apply (obviously)</li> </ul> <h4 id="abi-for-g2-multiplication">ABI for G2 multiplication</h4> <p>G2 multiplication call expects <code>256</code> bytes as an input that is interpreted as the byte concatenation of the point-encoding of a G2 point (<code>192</code> bytes) and the encoding of a scalar value (<code>64</code> bytes). Output is an encoding of multiplication operation result.</p> <p>Error cases:</p> <ul> <li>Point being not on the curve must result in error</li> <li>Field elements encoding rules apply (obviously)</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-g2-multiexponentiation">ABI for G2 multiexponentiation</h4> <p>G2 multiplication call expects <code>240*k</code> bytes as an input that is interpreted as byte concatenation of <code>k</code> slices each of them being a byte concatenation of encoding of G2 point (<code>192</code> bytes) and encoding of a scalar value (<code>48</code> bytes). Output is an encoding of multiexponentiation operation result.</p> <p>Error cases:</p> <ul> <li>Any of G2 points being not on the curve must result in error</li> <li>Field elements encoding rules apply (obviously)</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-pairing">ABI for pairing</h4> <p>Pairing call expects <code>384*k</code> bytes as an input, that is interpreted as the byte concatenation of <code>k</code> slices. Each slice has the following structure:</p> <ul> <li><code>192</code> bytes G1 point encoding</li> <li><code>192</code> bytes G2 point encoding</li> </ul> <p>Output is <code>32</code> bytes representing a boolean:</p> <ul> <li><code>0x0000000000000000000000000000000000000000000000000000000000000001</code> if the pairing result is equal the to multiplicative identity in the pairing target field; and</li> <li><code>0x0000000000000000000000000000000000000000000000000000000000000000</code> otherwise.</li> </ul> <p>Error cases:</p> <ul> <li>Any of the G1 or G2 points being not on the curve</li> <li>Any of the G1 or G2 points being not in the correct subgroup</li> <li>Input has invalid length</li> <li>Field elements encoding rules apply (obviously)</li> </ul> <h3 id="prevention-of-ddos-on-error-handling">Prevention of DDoS on error handling</h3> <p>This precompile performs extensive computations and in case of any errors during execution it <strong>MUST</strong> consume all gas from the gas schedule for the corresponding operation.</p> <h3 id="gas-schedule">Gas schedule</h3> <h4 id="g1-addition">G1 addition</h4> <p><code>180</code> gas</p> <h4 id="g1-multiplication">G1 multiplication</h4> <p><code>64000</code> gas</p> <h4 id="g2-addition">G2 addition</h4> <p><code>180</code> gas</p> <h4 id="g2-multiplication">G2 multiplication</h4> <p><code>64000</code> gas</p> <h4 id="g1-g2-multiexponentiation">G1/G2 Multiexponentiation</h4> <p>Discounts table as a vector of pairs <code>[k, discount]</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[[1, 1266], [2, 733], [3, 561], [4, 474], [5, 422], [6, 387], [7, 362], [8, 344], [9, 329], [10, 318], [11, 308], [12, 300], [13, 296], [14, 289], [15, 283], [16, 279], [17, 275], [18, 272], [19, 269], [20, 266], [21, 265], [22, 260], [23, 259], [24, 256], [25, 255], [26, 254], [27, 252], [28, 251], [29, 250], [30, 249], [31, 249], [32, 220], [33, 228], [34, 225], [35, 223], [36, 219], [37, 216], [38, 214], [39, 212], [40, 209], [41, 209], [42, 205], [43, 203], [44, 202], [45, 200], [46, 198], [47, 196], [48, 199], [49, 195], [50, 192], [51, 192], [52, 191], [53, 190], [54, 187], [55, 186], [56, 185], [57, 184], [58, 184], [59, 181], [60, 181], [61, 181], [62, 180], [63, 178], [64, 179], [65, 176], [66, 177], [67, 176], [68, 175], [69, 174], [70, 173], [71, 171], [72, 171], [73, 170], [74, 170], [75, 169], [76, 168], [77, 168], [78, 167], [79, 167], [80, 166], [81, 165], [82, 167], [83, 166], [84, 166], [85, 165], [86, 165], [87, 164], [88, 164], [89, 163], [90, 163], [91, 162], [92, 162], [93, 160], [94, 163], [95, 159], [96, 162], [97, 159], [98, 160], [99, 159], [100, 159], [101, 158], [102, 158], [103, 158], [104, 158], [105, 157], [106, 157], [107, 156], [108, 155], [109, 155], [110, 156], [111, 155], [112, 155], [113, 154], [114, 155], [115, 154], [116, 153], [117, 153], [118, 153], [119, 152], [120, 152], [121, 152], [122, 152], [123, 151], [124, 151], [125, 151], [126, 151], [127, 151], [128, 150]]</span></span></code></pre> <p><code>max_discount = 150</code></p> <h4 id="pairing-operation">Pairing operation</h4> <p>Base cost of the pairing operation is <code>120000*k + 320000</code> where <code>k</code> is a number of pairs.</p> <h2 id="rationale">Rationale</h2> <p>Gas costs are based on <a href="https://wg-eips.ritovision.com/1962/">EIP-1962</a> estimation strategy (but do not fully include yet parsing of ABI, decoding and encoding of the result as a byte array).</p> <h3 id="gas-estimation-strategy">Gas estimation strategy</h3> <p>Gas cost is derived by taking the average timing of the same operations over different implementations and assuming a constant <code>30 MGas/second</code>. Since the execution time is machine-specific, this constant is determined based on execution times of <em>ECRECOVER</em> and <em>BNPAIR</em> precompiles on my machine and their proposed gas price (<code>43.5 MGas/s</code> for ECRECOVER and <code>16.5 MGas/s</code> for BNPAIR). Following are the proposed methods to time the precompile operations:</p> <ul> <li>G1 addition: Average timing of 1000 random samples.</li> <li>G1 multiplication: Average timing of 1000 samples of random worst-case of double-and-add algorithm (scalar of max bit length and max hamming weight and random base points in G1)</li> <li>G2 addition: Average timing of 1000 random samples</li> <li>G2 multiplication: Average timing of 1000 samples of random worst-case of double-and-add algorithm (scalar of max bit length and max hamming weight and random base points in G2)</li> <li>G1 and G2 multiexponentiations: Expected to be performed by the Peppinger algorithm, with a table prepared for discount in case of <code>k &lt;= 128</code> points in the multiexponentiation with a discount cup <code>max_discount</code> for <code>k &gt; 128</code>. To avoid non-integer arithmetic call cost is calculated as <code>k * multiplication_cost * discount / multiplier</code> where <code>multiplier = 1000</code>, <code>k</code> is a number of (scalar, point) pairs for the call, <code>multiplication_cost</code> is a corresponding single multiplication call cost for G1/G2.</li> <li>Pairing: Average timing of 1000 random samples (random points in G1 and G2) for different number of pairs with linear lifting.</li> </ul> <h3 id="multiexponentiation-as-a-separate-call">Multiexponentiation as a separate call</h3> <p>Explicit separate multiexponentiation operation that allows one to save execution time (so gas) by both the algorithm used (namely Peppinger algorithm) and (usually forgotten) by the fact that <code>CALL</code> operation in Ethereum is expensive (at the time of writing), so one would have to pay non-negigible overhead if e.g. for multiexponentiation of <code>100</code> points would have to call the multiplication precompile <code>100</code> times and addition for <code>99</code> times (roughly <code>138600</code> would be saved).</p> <h3 id="explicit-subgroup-checks">Explicit subgroup checks</h3> <p>G2 subgroup check has the same cost as G1 subgroup check. Endomorphisms can be leverages to optimize this operation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backward compatibility questions.</p> <h2 id="test-cases">Test Cases</h2> <p>Due to the large test parameters space we first provide properties that various operations must satisfy. We use additive notation for point operations, capital letters (<code>P</code>, <code>Q</code>) for points, small letters (<code>a</code>, <code>b</code>) for scalars. Generator for G1 is labeled as <code>G</code>, generator for G2 is labeled as <code>H</code>, otherwise we assume random point on a curve in a correct subgroup. <code>0</code> means either scalar zero or point of infinity. <code>1</code> means either scalar one or multiplicative identity. <code>group_order</code> is a main subgroup order. <code>e(P, Q)</code> means pairing operation where <code>P</code> is in G1, <code>Q</code> is in G2.</p> <p>Requeired properties for basic ops (add/multiply):</p> <ul> <li>Commutativity: <code>P + Q = Q + P</code></li> <li>Additive negation: <code>P + (-P) = 0</code></li> <li>Doubling <code>P + P = 2*P</code></li> <li>Subgroup check: <code>group_order * P = 0</code></li> <li>Trivial multiplication check: <code>1 * P = P</code></li> <li>Multiplication by zero: <code>0 * P = 0</code></li> <li>Multiplication by the unnormalized scalar <code>(scalar + group_order) * P = scalar * P</code></li> </ul> <p>Required properties for pairing operation:</p> <ul> <li>Degeneracy <code>e(P, 0*Q) = e(0*P, Q) = 1</code></li> <li>Bilinearity <code>e(a*P, b*Q) = e(a*b*P, Q) = e(P, a*b*Q)</code> (internal test, not visible through ABI)</li> </ul> <h2 id="reference-implementation">Reference Implementation</h2> <p>There is a various choice of existing implementations:</p> <p><strong>Libraries:</strong></p> <ul> <li>Rust implementation (EY/Zexe): github.com/yelhousni/zexe/tree/youssef/BW6-761-Fq-ABLR-2ML-M</li> <li>C++ implementation (EY/libff): github.com/EYBlockchain/zk-swap-libff</li> <li>Golang implementation (Consensys/gurvy): github.com/ConsenSys/gurvy</li> </ul> <p><strong>Stand-alone implementation:</strong></p> <ul> <li>Golang implementation with Intel assembly (Onur Kilic): github.com/kilic/bw6</li> </ul> <p><strong>Precompiles:</strong></p> <ul> <li>OpenEthereum (EY/Parity): github.com/EYBlockchain/solidity-elliptic-curves</li> <li>Frontier (Parity): github.com/paritytech/frontier/pull/1049/files</li> </ul> <p><strong>Scripts:</strong></p> <ul> <li>SageMath and Magma scripts: gitlab.inria.fr/zk-curves/bw6-761/</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Strictly following the spec will eliminate security implications or consensus implications in a contrast to the previous BN254 precompile.</p> <p>Important topic is a "constant time" property for performed operations. We explicitly state that this precompile <strong>IS NOT REQUIRED</strong> to perform all the operations using constant time algorithms.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Peter Grassbergerhttps://github.com/PeterTheOne https://wg-eips.ritovision.com/3014/ <h2 id="simple-summary">Simple Summary</h2> <p>Add <code>eth_symbol</code> method to the JSON-RPC that returns the symbol of the native coin of the network.</p> <h2 id="abstract">Abstract</h2> <p>The new method <code>eth_symbol</code> (<code>eth_</code>-namespaced) has no parameters and returns a string of the native coin of the network. For the Ethereum mainnet this will be <code>ETH</code>, other networks will have other symbols.</p> <h2 id="motivation">Motivation</h2> <p>Wallets that deal with multiple networks need some basic information for every blockchain that they connect to. One of those things is the symbol of the native coin of the network. Instead of requiring the user to research and manually add the symbol it could be provided to the wallet via this proposed JSON-RPC endpoint and used automatically. There are lists of networks with symbols like https://github.com/ethereum-lists/chains where a user can manually look up the correct values. But this information could easily come from the network itself.</p> <h2 id="specification">Specification</h2> <p>Method: <code>eth_symbol</code>.</p> <p>Params: none.</p> <p>Returns: <code>result</code> - the native coin symbol, string</p> <p>Example:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">curl</span><span class="z-keyword"> -</span><span class="z-variable z-other z-constant">X</span><span class="z-variable z-other z-constant"> POST</span><span class="z-keyword"> --</span><span class="z-variable z-other">data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{&quot;jsonrpc&quot;:&quot;2.0&quot;,&quot;method&quot;:&quot;eth_symbol&quot;,&quot;params&quot;:[],&quot;id&quot;:1}</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Result</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">id</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-constant">1</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">jsonrpc</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">result</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ETH</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This endpoint is similar to <a href="https://wg-eips.ritovision.com/695/">EIP-695</a> but it provides the symbol instead of <code>chainId</code>. It provides functionality that is already there for <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> tokens, but not yet for the native coin of the network. Alternative naming of <code>eth_nativeCurrencySymbol</code> was considered, but the context and the fact that it just returns one value makes it clear that that it returns the symbol for the native coin of the network.</p> <h2 id="security-considerations">Security Considerations</h2> <p>It is a read only endpoint. The information is only as trusted as the JSON-RPC node itself, it could supply wrong information and thereby trick the user in believing he/she is dealing with another native coin.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Herman Jungehttps://github.com/hermanjunge https://wg-eips.ritovision.com/3030/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP defines a HTTP API standard for a BLS remote signer, consumed by validator clients to sign block proposals and attestations in the context of Ethereum 2.0 (eth2).</p> <h2 id="abstract">Abstract</h2> <p>A <a rel="external" href="https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/validator.md">validator</a> client contributes to the consensus of the Eth2 blockchain by signing proposals and attestations of blocks, using a BLS private key which must be available to this client at all times.</p> <p>The BLS remote signer API is designed to be consumed by validator clients, looking for a more secure avenue to store their BLS12-381 private key(s), enabling them to run in more permissive and scalable environments.</p> <h2 id="motivation">Motivation</h2> <p>Eth2 utilizes <a rel="external" href="https://github.com/cfrg/draft-irtf-cfrg-bls-signature/">BLS12-381</a> signatures.</p> <p>Consensus on the eth2 Blockchain is achieved via the proposal and attestation of blocks from validator clients, using a BLS private key (<em>signing</em> key) which must be available each time a message is signed: that is, at least once every epoch (6.4 minutes), during a small window of time within this epoch (a <em>slot</em>, i.e. 12 seconds), as each validator is expected to attest exactly once per epoch.</p> <p>The <a rel="external" href="https://github.com/ethereum/eth2.0-specs">eth2 specification</a> does not explicitly provide a directive on where this BLS private key must/should be stored, leaving this implementation detail to the client teams, who assume that this cryptographic secret is stored on the same host as the validator client.</p> <p>This assumption is sufficient in the use case where the validator client is running in a physically secure network (i.e. nobody, but the operator, has a chance to log-in into the machine hosting the validator client), as such configuration would only allow <em>outbound</em> calls from the validator client. In this situation, only a physical security breach, or a Remote Code Execution (RCE) vulnerability can allow an attacker to either have arbitrary access to the storage or to the memory of the device.</p> <p>There are, however, use cases where it is required by the operator to run a validator client node in less constrained security environments, as the ones given by a cloud provider. Notwithstanding any security expectation, nothing prevents a rogue operator from gaining arbitrary access to the assets running inside a node.</p> <p>The situation is not better when the requirement is to execute the validators by leveraging a container orchestration solution (e.g. Kubernetes). The handling of secret keys across nodes can become a burden both from an operational as well as a security perspective.</p> <p>The proposed solution comprises running a specialized node with exclusive access to the secret keys, listening to a simple API (defined in the <a href="https://wg-eips.ritovision.com/3030/#specification">Specification</a> section), and returning the requested signatures. Operators working under this schema must utilize clients with the adequate feature supporting the consumption of this API.</p> <p>The focus of this specification is the supply of BLS signatures <em>on demand</em>. The aspects of authentication, key management (creation, update, and deletion), and transport encryption are discussed in the <a href="https://wg-eips.ritovision.com/3030/#rationale">Rationale</a> section of this document. Moreover, the <a href="https://wg-eips.ritovision.com/3030/#threat-model">Threat Model</a> section of this document provides a (non-exhaustive) list of threats and attack vectors, along with the suggested related mitigation strategy.</p> <h2 id="specification">Specification</h2> <h3 id="get-upcheck"><code>GET /upcheck</code></h3> <p><em><strong>Responses</strong></em></p> <table><thead><tr><th>Success</th><th><br></th></tr></thead><tbody> <tr><td>Code</td><td><code>200</code></td></tr> <tr><td>Content</td><td><code>{"status": "OK"}</code></td></tr> </tbody></table> <hr /> <h3 id="get-keys"><code>GET /keys</code></h3> <p>Returns the identifiers of the keys available to the signer.</p> <p><em><strong>Responses</strong></em></p> <table><thead><tr><th>Success</th><th><br></th></tr></thead><tbody> <tr><td>Code</td><td><code>200</code></td></tr> <tr><td>Content</td><td><code>{"keys": "[identifier]"}</code></td></tr> </tbody></table> <hr /> <h3 id="post-sign-identifier"><code>POST /sign/:identifier</code></h3> <table><thead><tr><th>URL Parameter</th><th><br></th></tr></thead><tbody> <tr><td><code>:identifier</code></td><td><code>public_key_hex_string_without_0x</code></td></tr> </tbody></table> <p><em><strong>Request</strong></em></p> <table><thead><tr><th>JSON Body</th><th><br></th><th><br></th></tr></thead><tbody> <tr><td><code>bls_domain</code></td><td><strong>Required</strong></td><td>The BLS Signature domain.<br>As defined in the <a rel="external" href="https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/beacon-chain.md#domain-types">specification</a>, in lowercase, omitting the <code>domain</code> prefix.<br>Supporting <code>beacon_proposer</code>, <code>beacon_attester</code>, and <code>randao</code>.</td></tr> <tr><td><code>data</code></td><td><strong>Required</strong></td><td>The data to be signed.<br>As defined in the specifications for <a rel="external" href="https://github.com/ethereum/eth2.0-APIs/blob/master/types/block.yaml">block</a>, <a rel="external" href="https://github.com/ethereum/eth2.0-APIs/blob/master/types/attestation.yaml">attestation</a>, and <a rel="external" href="https://github.com/ethereum/eth2.0-APIs/blob/master/types/misc.yaml">epoch</a>.</td></tr> <tr><td><code>fork</code></td><td><strong>Required</strong></td><td>A <code>Fork</code> object containing previous and current versions.<br>As defined in the <a rel="external" href="https://github.com/ethereum/eth2.0-APIs/blob/master/types/misc.yaml">specification</a></td></tr> <tr><td><code>genesis_validators_root</code></td><td><strong>Required</strong></td><td>A <code>Hash256</code> for domain separation and chain versioning.</td></tr> <tr><td><br></td><td>Optional</td><td>Any other field will be ignored by the signer</td></tr> </tbody></table> <p><em><strong>Responses</strong></em></p> <table><thead><tr><th>Success</th><th><br></th></tr></thead><tbody> <tr><td>Code</td><td><code>200</code></td></tr> <tr><td>Content</td><td><code>{"signature": "&lt;signature_hex_string&gt;"}</code></td></tr> </tbody></table> <p>Where signature is a <a rel="external" href="https://github.com/ethereum/eth2.0-specs/blob/dev/specs/phase0/beacon-chain.md#bls-signatures">BLS signature</a> byte array encoded as a hexadecimal string.</p> <p><em>or</em></p> <table><thead><tr><th>Error</th><th><br></th></tr></thead><tbody> <tr><td>Code</td><td><code>400</code></td></tr> <tr><td>Content</td><td><code>{"error": "&lt;Bad Request Error Message&gt;"}</code></td></tr> </tbody></table> <p><em>or</em></p> <table><thead><tr><th>Error</th><th><br></th></tr></thead><tbody> <tr><td>Code</td><td><code>404</code></td></tr> <tr><td>Content</td><td><code>{"error": "Key not found: &lt;identifier&gt;"}</code></td></tr> </tbody></table> <hr /> <h2 id="rationale">Rationale</h2> <h3 id="unix-philosophy-simple-api">UNIX philosophy: Simple API</h3> <p>This API specification contains only three methods: one for <strong>status</strong>, one for <strong>listing the available keys</strong>, and one to <strong>produce a signature</strong>. There are no methods for authentication, key management, nor transport encryption.</p> <p>The following subsections discuss aspects to be considered by the client implementers relative to these subjects.</p> <h4 id="implementation-of-additional-features">Implementation of additional features</h4> <p>From an API pipeline view, we have two nodes: The validator client (1) that makes requests to the remote signer (2). A more sophisticated chain can be built by introducing elements between these two nodes. Either by setting up reverse proxy services, or by adding plugins to the remote signer implementation.</p> <h4 id="authentication">Authentication</h4> <p>Can be accomplished through the use of an HTTP Request Header. There are several ways to negotiate and issue a valid token to authenticate the communication between the validator client and the remote signer, each of them with potential drawbacks (e.g replay attacks, challenges in distributing the token to the validator client, etc.). In general, any method of authentication must be combined with transport encryption to be effective.</p> <p>The operator can also implement network Access Control Lists (ACLs) between the validator client's network and the remote signer's network, reducing the attack surface by requiring a potential attacker to be positioned in the same network as the validator client.</p> <h4 id="key-management">Key management</h4> <p>There are several ways to store secret keys, namely Hardware Security Modules (HSM), Secrets management applications (e.g. Hashicorp Vault), cloud storage with tight private network ACL rules, or even raw files in a directory. In general the remote signer implementers will abstract the storage medium from the HTTP API.</p> <p>It is in this perspective, that any procedure to create, update, or delete keys should be built separate from the client implementation.</p> <h4 id="transport-encryption">Transport Encryption</h4> <p>If the operator is working with self-signed certificates, it is required that the client enhancement consuming the remote signer allows this option.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="test-data">Test Data</h3> <ul> <li>BLS Pair <ul> <li>Public key: <code>0xb7354252aa5bce27ab9537fd0158515935f3c3861419e1b4b6c8219b5dbd15fcf907bddf275442f3e32f904f79807a2a</code>.</li> <li>Secret key: <code>0x68081afeb7ad3e8d469f87010804c3e8d53ef77d393059a55132637206cc59ec</code>.</li> </ul> </li> <li>Signing root: <code>0xb6bb8f3765f93f4f1e7c7348479289c9261399a3c6906685e320071a1a13955c</code>.</li> <li>Expected signature: <code>0xb5d0c01cef3b028e2c5f357c2d4b886f8e374d09dd660cd7dd14680d4f956778808b4d3b2ab743e890fc1a77ae62c3c90d613561b23c6adaeb5b0e288832304fddc08c7415080be73e556e8862a1b4d0f6aa8084e34a901544d5bb6aeed3a612</code>.</li> </ul> <h3 id="get-upcheck-1"><code>GET /upcheck</code></h3> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Success</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">v</span><span class="z-string"> localhost:9000/upcheck</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Response</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Trying 127.0.0.1:9000...</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> TCP_NODELAY set</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connected to localhost (</span><span class="z-entity z-name">127.0.0.1</span><span>) port 9000 (</span><span>#0)</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span class="z-entity z-name"> GET</span><span class="z-string"> /upcheck</span><span class="z-string"> HTTP/1.1</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Host: localhost:9000</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> User-Agent: curl/7.68.0</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Accept: </span><span class="z-keyword">*</span><span>/</span><span class="z-keyword">*</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Mark bundle as not supporting multiuse</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> HTTP/1.1 200 OK</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-type: application/json</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-length: 15</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> date: Wed, 30 Sep 2020 02:25:08 GMT</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connection</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment">0 to host localhost left intact</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">status</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">OK</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span></code></pre><h3 id="get-keys-1"><code>GET /keys</code></h3> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Success</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">v</span><span class="z-string"> localhost:9000/keys</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Response</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Trying 127.0.0.1:9000...</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> TCP_NODELAY set</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connected to localhost (</span><span class="z-entity z-name">127.0.0.1</span><span>) port 9000 (</span><span>#0)</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span class="z-entity z-name"> GET</span><span class="z-string"> /publicKeys</span><span class="z-string"> HTTP/1.1</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Host: localhost:9000</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> User-Agent: curl/7.68.0</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Accept: </span><span class="z-keyword">*</span><span>/</span><span class="z-keyword">*</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Mark bundle as not supporting multiuse</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> HTTP/1.1 200 OK</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-type: application/json</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-length: 116</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> date: Wed, 30 Sep 2020 02:25:36 GMT</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connection</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment">0 to host localhost left intact</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">keys</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string">[</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">b7354252aa5bce27ab9537fd0158515935f3c3861419e1b4b6c8219b5dbd15fcf907bddf275442f3e32f904f79807a2a</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">]}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Server Error</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Preparation</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># `chmod` keys directory to the octal 311 (-wx--x--x).</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">v</span><span class="z-string"> localhost:9000/keys</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Response</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Trying 127.0.0.1:9000...</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> TCP_NODELAY set</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connected to localhost (</span><span class="z-entity z-name">127.0.0.1</span><span>) port 9000 (</span><span>#0)</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span class="z-entity z-name"> GET</span><span class="z-string"> /publicKeys</span><span class="z-string"> HTTP/1.1</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Host: localhost:9000</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> User-Agent: curl/7.68.0</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Accept: </span><span class="z-keyword">*</span><span>/</span><span class="z-keyword">*</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Mark bundle as not supporting multiuse</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> HTTP/1.1 500 Internal Server Error</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-length: 43</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> date: Wed, 30 Sep 2020 02:26:09 GMT</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connection</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment">0 to host localhost left intact</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">error</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">Storage error: PermissionDenied</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span></code></pre><h3 id="post-sign-identifier-1"><code>POST /sign/:identifier</code></h3> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Success</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">v</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">d</span><span class="z-string"> @payload.json</span><span class="z-constant"> -</span><span class="z-constant">H</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Content-Type: application/json</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string"> localhost:9000/sign/b7354252aa5bce27ab9537fd0158515935f3c3861419e1b4b6c8219b5dbd15fcf907bddf275442f3e32f904f79807a2a</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Response</span></span> <span class="giallo-l"><span class="z-entity z-name">Note:</span><span class="z-string"> Unnecessary</span><span class="z-string"> use</span><span class="z-string"> of</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> or</span><span class="z-constant"> -</span><span class="z-constant">-request,</span><span class="z-string"> POST</span><span class="z-string"> is</span><span class="z-string"> already</span><span class="z-string"> inferred.</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Trying 127.0.0.1:9000...</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> TCP_NODELAY set</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connected to localhost (</span><span class="z-entity z-name">127.0.0.1</span><span>) port 9000 (</span><span>#0)</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span class="z-entity z-name"> POST</span><span class="z-string"> /sign/b7354252aa5bce27ab9537fd0158515935f3c3861419e1b4b6c8219b5dbd15fcf907bddf275442f3e32f904f79807a2a</span><span class="z-string"> HTTP/1.1</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Host: localhost:9000</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> User-Agent: curl/7.68.0</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Accept: </span><span class="z-keyword">*</span><span>/</span><span class="z-keyword">*</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Content-Type: application/json</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Content-Length: 84</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> upload completely sent off: 84 out of 84 bytes</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Mark bundle as not supporting multiuse</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> HTTP/1.1 200 OK</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-type: application/json</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-length: 210</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> date: Wed, 30 Sep 2020 02:16:02 GMT</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connection</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment">0 to host localhost left intact</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">signature</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0xb5d0c01cef3b028e2c5f357c2d4b886f8e374d09dd660cd7dd14680d4f956778808b4d3b2ab743e890fc1a77ae62c3c90d613561b23c6adaeb5b0e288832304fddc08c7415080be73e556e8862a1b4d0f6aa8084e34a901544d5bb6aeed3a612</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Bad Request Error</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">v</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">d</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">foobar</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-constant"> -</span><span class="z-constant">H</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Content-Type: application/json</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string"> localhost:9000/sign/b7354252aa5bce27ab9537fd0158515935f3c3861419e1b4b6c8219b5dbd15fcf907bddf275442f3e32f904f79807a2a</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Response</span></span> <span class="giallo-l"><span class="z-entity z-name">Note:</span><span class="z-string"> Unnecessary</span><span class="z-string"> use</span><span class="z-string"> of</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> or</span><span class="z-constant"> -</span><span class="z-constant">-request,</span><span class="z-string"> POST</span><span class="z-string"> is</span><span class="z-string"> already</span><span class="z-string"> inferred.</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Trying 127.0.0.1:9000...</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> TCP_NODELAY set</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connected to localhost (</span><span class="z-entity z-name">127.0.0.1</span><span>) port 9000 (</span><span>#0)</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span class="z-entity z-name"> POST</span><span class="z-string"> /sign/b7354252aa5bce27ab9537fd0158515935f3c3861419e1b4b6c8219b5dbd15fcf907bddf275442f3e32f904f79807a2a</span><span class="z-string"> HTTP/1.1</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Host: localhost:9000</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> User-Agent: curl/7.68.0</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Accept: </span><span class="z-keyword">*</span><span>/</span><span class="z-keyword">*</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Content-Type: application/json</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Content-Length: 23</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> upload completely sent off: 23 out of 23 bytes</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Mark bundle as not supporting multiuse</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> HTTP/1.1 400 Bad Request</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-length: 38</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> date: Wed, 30 Sep 2020 02:15:05 GMT</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connection</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment">0 to host localhost left intact</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">error</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">Unable to parse body message from JSON: Error(</span><span class="z-constant">\&quot;</span><span class="z-entity z-name">expected ident</span><span class="z-constant">\&quot;</span><span class="z-entity z-name">, line: 1, column: 2)</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> No Keys Available</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">v</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">d</span><span class="z-string"> @payload.json</span><span class="z-constant"> -</span><span class="z-constant">H</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Content-Type: application/json</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string"> localhost:9000/sign/000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Response</span></span> <span class="giallo-l"><span class="z-entity z-name">Note:</span><span class="z-string"> Unnecessary</span><span class="z-string"> use</span><span class="z-string"> of</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> or</span><span class="z-constant"> -</span><span class="z-constant">-request,</span><span class="z-string"> POST</span><span class="z-string"> is</span><span class="z-string"> already</span><span class="z-string"> inferred.</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Trying 127.0.0.1:9000...</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> TCP_NODELAY set</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connected to localhost (</span><span class="z-entity z-name">127.0.0.1</span><span>) port 9000 (</span><span>#0)</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span class="z-entity z-name"> POST</span><span class="z-string"> /sign/000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</span><span class="z-string"> HTTP/1.1</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Host: localhost:9000</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> User-Agent: curl/7.68.0</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Accept: </span><span class="z-keyword">*</span><span>/</span><span class="z-keyword">*</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Content-Type: application/json</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Content-Length: 84</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> upload completely sent off: 84 out of 84 bytes</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Mark bundle as not supporting multiuse</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> HTTP/1.1 404 Not Found</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-length: 123</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> date: Wed, 30 Sep 2020 02:18:53 GMT</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connection</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment">0 to host localhost left intact</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">error</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">Key not found: 000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Server Error</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Preparation</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># `chmod` both keys directory and file to the octal 311 (-wx--x--x).</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># `chmod` back to 755 to delete them afterwards.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">v</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">d</span><span class="z-string"> @payload.json</span><span class="z-constant"> -</span><span class="z-constant">H</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Content-Type: application/json</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string"> localhost:9000/sign/b7354252aa5bce27ab9537fd0158515935f3c3861419e1b4b6c8219b5dbd15fcf907bddf275442f3e32f904f79807a2a</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"># Response</span></span> <span class="giallo-l"><span class="z-entity z-name">Note:</span><span class="z-string"> Unnecessary</span><span class="z-string"> use</span><span class="z-string"> of</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> or</span><span class="z-constant"> -</span><span class="z-constant">-request,</span><span class="z-string"> POST</span><span class="z-string"> is</span><span class="z-string"> already</span><span class="z-string"> inferred.</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Trying 127.0.0.1:9000...</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> TCP_NODELAY set</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connected to localhost (</span><span class="z-entity z-name">127.0.0.1</span><span>) port 9000 (</span><span>#0)</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span class="z-entity z-name"> POST</span><span class="z-string"> /sign/b7354252aa5bce27ab9537fd0158515935f3c3861419e1b4b6c8219b5dbd15fcf907bddf275442f3e32f904f79807a2a</span><span class="z-string"> HTTP/1.1</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Host: localhost:9000</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> User-Agent: curl/7.68.0</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Accept: </span><span class="z-keyword">*</span><span>/</span><span class="z-keyword">*</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Content-Type: application/json</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> Content-Length: 84</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> upload completely sent off: 84 out of 84 bytes</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Mark bundle as not supporting multiuse</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> HTTP/1.1 500 Internal Server Error</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> content-length: 43</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span><span> date: Wed, 30 Sep 2020 02:21:08 GMT</span></span> <span class="giallo-l"><span class="z-keyword">&lt;</span></span> <span class="giallo-l"><span class="z-keyword">*</span><span> Connection</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment">0 to host localhost left intact</span></span> <span class="giallo-l"><span>{</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">error</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">Storage error: PermissionDenied</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">}</span></span></code></pre><h2 id="implementation">Implementation</h2> <table><thead><tr><th>Repository Url</th><th>Language</th><th>Organization</th><th>Commentary</th></tr></thead><tbody> <tr><td><a rel="external" href="https://github.com/sigp/rust-bls-remote-signer">BLS Remote Signer</a></td><td>Rust</td><td>Sigma Prime</td><td>Supports proposed specification.</td></tr> <tr><td><a rel="external" href="https://github.com/PegaSysEng/web3signer">Web3signer</a></td><td>Java</td><td>PegaSys</td><td>Supports proposed specification, although with <a rel="external" href="https://pegasyseng.github.io/web3signer/web3signer-eth2.html">slightly different methods</a>:<br>{<code>/sign</code> =&gt; <code>/api/v1/eth2/sign</code>, <code>/publicKeys</code> =&gt; <code>/api/v1/eth2/publicKeys</code>}.</td></tr> <tr><td><a rel="external" href="https://docs.prylabs.network/docs/wallet/remote/">Remote Signing Wallet</a></td><td>Golang</td><td>Prysmatics Labs</td><td>Supports both gRPC and JSON over HTTP.</td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <h3 id="threat-model">Threat model</h3> <p>Let's consider the following threats and their mitigations:</p> <table><thead><tr><th>Threat</th><th>Mitigation(s)</th></tr></thead><tbody> <tr><td>An attacker can spoof the validator client.</td><td>See the discussion at <a href="https://wg-eips.ritovision.com/3030/#authentication">Authentication</a>.</td></tr> <tr><td>An attacker can send a crafted message to the signer, leading to a slashing offense.</td><td>It is the responsibility of the operator of the remote signer to add a validation module, as discussed at <a href="https://wg-eips.ritovision.com/3030/#implementation-of-additional-features">Implementation of additional features</a>.</td></tr> <tr><td>An attacker can create, update, or delete secret keys.</td><td>Keys are not to be writable via any interface of the remote signer.</td></tr> <tr><td>An attacker can repudiate a sent message.</td><td>Implement logging in the signer. Enhance it by sending logs to a syslog box.</td></tr> <tr><td>An attacker can disclose the contents of a private key by retrieving the key from storage.</td><td>Storage in Hardware security module (HSM).<br><em>or</em><br>Storage in Secrets management applications (e.g. Hashicorp Vault).</td></tr> <tr><td>An attacker can eavesdrop on the uploading of a secret key.</td><td>Upload the keys using a secure channel, based on each storage specification.</td></tr> <tr><td>An attacker can eavesdrop on the retrieval of a key from the remote signer.</td><td>Always pass the data between storage and remote signer node using a secure channel.</td></tr> <tr><td>An attacker can dump the memory in the remote signer to disclose a secret key.</td><td>Prevent physical access to the node running the remote signer.<br><em>or</em><br>Prevent access to the terminal of the node running the remote signer: Logs being sent to a syslog box. Deployments triggered by a simple, non-parameterized API.<br><em>or</em><br>Implement zeroization of the secret key at memory.<br><em>or</em><br>Explore the compilation and running of the remote signer in a Trusted execution environment (TEE).</td></tr> <tr><td>An attacker can DoS the remote signer.</td><td>Implement IP filtering.<br><em>or</em><br>Implement Rate limiting.</td></tr> </tbody></table> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Matthttps://github.com/defifuture https://wg-eips.ritovision.com/3005/ <h2 id="simple-summary">Simple Summary</h2> <p>Defines an extension function for ERC-20 (and other fungible token standards), which allows receiving and processing a batch of meta transactions.</p> <h2 id="abstract">Abstract</h2> <p>This EIP defines a new function called <code>processMetaBatch()</code> that extends any fungible token standard, and enables batched meta transactions coming from many senders in one on-chain transaction.</p> <p>The function must be able to receive multiple meta transactions data and process it. This means validating the data and the signature, before proceeding with token transfers based on the data.</p> <p>The function enables senders to make gasless transactions, while reducing the relayer's gas cost due to batching.</p> <h2 id="motivation">Motivation</h2> <p>Meta transactions have proven useful as a solution for Ethereum accounts that don't have any ether, but hold ERC-20 tokens and would like to transfer them (gasless transactions).</p> <p>The current meta transaction relayer implementations only allow relaying one meta transaction at a time. Some also allow batched meta transactions from the same sender. But none offers batched meta transactions from <strong>multiple</strong> senders.</p> <p>The motivation behind this EIP is to find a way to allow relaying batched meta transactions from <strong>many senders</strong> in <strong>one on-chain transaction</strong>, which also <strong>reduces the total gas cost</strong> that a relayer needs to cover.</p> <p><img src="https://wg-eips.ritovision.com/3005/./assets/meta-txs-directly-to-token-smart-contract.png" alt="" /></p> <h2 id="specification">Specification</h2> <p>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> <p>The key words "MUST (BUT WE KNOW YOU WON'T)", "SHOULD CONSIDER", "REALLY SHOULD NOT", "OUGHT TO", "WOULD PROBABLY", "MAY WISH TO", "COULD", "POSSIBLE", and "MIGHT" in this document are to be interpreted as described in RFC 6919.</p> <h3 id="meta-transaction-data">Meta transaction data</h3> <p>In order to successfully validate and transfer tokens, the <code>processMetaBatch()</code> function MUST process the following data about a meta transaction:</p> <ul> <li>sender address</li> <li>receiver address</li> <li>token amount</li> <li>relayer fee</li> <li>a (meta tx) nonce</li> <li>an expiration date (this COULD be a block number, or it COULD be a block timestamp)</li> <li>a token address</li> <li>a relayer address</li> <li>a signature</li> </ul> <p>Not all of the data needs to be sent to the function by the relayer (see the function interface specification). Some of the data can be deduced or extracted from other sources (from transaction data and contract state).</p> <h3 id="processmetabatch-function-input-data"><code>processMetaBatch()</code> function input data</h3> <p>The <code>processMetaBatch()</code> function MUST receive the following data:</p> <ul> <li>sender address</li> <li>receiver address</li> <li>token amount</li> <li>relayer fee</li> <li>an expiration date (this COULD be a block number, or it COULD be a block timestamp)</li> <li>a signature</li> </ul> <p>The following data is OPTIONAL to be sent to the function, because it can be extracted or derived from other sources:</p> <ul> <li>a (meta tx) nonce</li> <li>a token address</li> <li>a relayer address</li> </ul> <h3 id="meta-transaction-data-hash">Meta transaction data hash</h3> <p>The pseudocode for creating a hash of meta transaction data is the following:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>keccak256(address(sender)</span></span> <span class="giallo-l"><span> ++ address(recipient)</span></span> <span class="giallo-l"><span> ++ uint256(amount)</span></span> <span class="giallo-l"><span> ++ uint256(relayerFee)</span></span> <span class="giallo-l"><span> ++ uint256(nonce)</span></span> <span class="giallo-l"><span> ++ uint256(expirationDate)</span></span> <span class="giallo-l"><span> ++ address(tokenContract)</span></span> <span class="giallo-l"><span> ++ address(relayer)</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>The created hash MUST then be signed with the sender's private key.</p> <h3 id="validation-rules">Validation rules</h3> <ul> <li>Nonce of a new transaction MUST always be bigger by exactly 1 from the nonce of the last successfully processed meta transaction of the same sender to the same token contract.</li> <li>Sending to and from a 0x0 address MUST be prohibited.</li> <li>A meta transaction MUST be processed before the expiration date.</li> <li>Each sender's token balance MUST be equal or greater than the sum of their respective meta transaction token amount and relayer fee.</li> <li>A transaction where at least one meta transaction in the batch does not satisfy the above requirements MUST not be reverted. Instead, a failed meta transaction MUST be skipped or ignored.</li> </ul> <h3 id="processmetabatch-function-interface"><code>processMetaBatch()</code> function interface</h3> <p>The <code>processMetaBatch()</code> function MUST have the following interface:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> processMetaBatch</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> senders</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> recipients</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> amounts</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> relayerFees</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> blocks</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sigV</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sigR</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sigS</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre> <p>The overview of parameters that are passed:</p> <ul> <li><code>senders</code>: an array of meta transaction sender addresses (token senders)</li> <li><code>recipients </code>: an array of token recipients addresses</li> <li><code>amounts</code>: an array of token amounts that are sent from each sender to each recipient, respectively</li> <li><code>relayerFees</code>: an array of the relayer fees paid in tokens by senders. The fee receiver is a relayer (<code>msg.address</code>)</li> <li><code>blocks</code>: an array of block numbers that represent an expiration date by which the meta transaction must be processed (alternatively, a timestamp could be used instead of a block number)</li> <li><code>sigV</code>, <code>sigR</code>, <code>sigS</code>: three arrays that represent parts of meta transaction signatures</li> </ul> <p>Each entry in each of the arrays MUST represent data from one meta transaction. The order of the data is very important. Data from a single meta transaction MUST have the same index in every array.</p> <h3 id="meta-transaction-nonce">Meta transaction nonce</h3> <p>The token smart contract must keep track of a meta transaction nonce for each token holder.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">mapping</span><span> (</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _metaNonces</span><span>;</span></span></code></pre> <p>The interface for the <code>nonceOf()</code> function is the following:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> nonceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre><h3 id="token-transfers">Token transfers</h3> <p>After a meta transaction is successfully validated, the meta nonce of the meta transaction sender MUST be increased by 1.</p> <p>Then two token transfers MUST occur:</p> <ul> <li>The specified token amount MUST go to the recipient.</li> <li>The relayer fee MUST go to the relayer (<code>msg.sender</code>).</li> </ul> <h2 id="implementation">Implementation</h2> <p>The <strong>reference implementation</strong> adds a couple of functions to the existing ERC-20 token standard:</p> <ul> <li><code>processMetaBatch()</code></li> <li><code>nonceOf()</code></li> </ul> <p>You can see the implementation of both functions in this file: <a rel="external" href="https://github.com/defifuture/erc20-batched-meta-transactions/blob/master/contracts/ERC20MetaBatch.sol">ERC20MetaBatch.sol</a>. This is an extended ERC-20 contract with added meta transaction batch transfer capabilities.</p> <h3 id="processmetabatch"><code>processMetaBatch()</code></h3> <p>The <code>processMetaBatch()</code> function is responsible for receiving and processing a batch of meta transactions that change token balances.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> processMetaBatch</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> senders</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> recipients</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> amounts</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> relayerFees</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> blocks</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sigV</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sigR</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sigS</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-support"> address</span><span> sender</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> newNonce</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> relayerFeesSum </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> msgHash</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> i</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> loop through all meta txs</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span>i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> senders</span><span>.</span><span>length</span><span>;</span><span> i</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> sender </span><span class="z-keyword">=</span><span> senders</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> newNonce </span><span class="z-keyword">=</span><span> _metaNonces</span><span>[</span><span>sender</span><span>]</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>sender </span><span class="z-keyword">==</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> ||</span><span> recipients</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> ==</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> continue</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> sender or recipient is 0x0 address, skip this meta tx</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> the meta tx should be processed until (including) the specified block number, otherwise it is invalid</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>number </span><span class="z-keyword">&gt;</span><span> blocks</span><span>[</span><span>i</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> continue</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> if current block number is bigger than the requested number, skip this meta tx</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check if meta tx sender&#39;s balance is big enough</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>_balances</span><span>[</span><span>sender</span><span>]</span><span class="z-keyword"> &lt;</span><span> (</span><span>amounts</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> +</span><span> relayerFees</span><span>[</span><span>i</span><span>]</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> continue</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> if sender&#39;s balance is less than the amount and the relayer fee, skip this meta tx</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> check if the signature is valid</span></span> <span class="giallo-l"><span> msgHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>sender</span><span>,</span><span> recipients</span><span>[</span><span>i</span><span>]</span><span>,</span><span> amounts</span><span>[</span><span>i</span><span>]</span><span>,</span><span> relayerFees</span><span>[</span><span>i</span><span>]</span><span>,</span><span> newNonce</span><span>,</span><span> blocks</span><span>[</span><span>i</span><span>]</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>sender </span><span class="z-keyword">!=</span><span class="z-support"> ecrecover</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span class="z-string">&quot;\x19Ethereum Signed Message:\n32&quot;</span><span>,</span><span> msgHash</span><span>)</span><span>)</span><span>,</span><span> sigV</span><span>[</span><span>i</span><span>]</span><span>,</span><span> sigR</span><span>[</span><span>i</span><span>]</span><span>,</span><span> sigS</span><span>[</span><span>i</span><span>]</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> continue</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> if sig is not valid, skip to the next meta tx</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> set a new nonce for the sender</span></span> <span class="giallo-l"><span> _metaNonces</span><span>[</span><span>sender</span><span>]</span><span class="z-keyword"> =</span><span> newNonce</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> transfer tokens</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span>sender</span><span>]</span><span class="z-keyword"> -</span><span class="z-keyword">=</span><span> (</span><span>amounts</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> +</span><span> relayerFees</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span>recipients</span><span>[</span><span>i</span><span>]</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> amounts</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> relayerFeesSum </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> relayerFees</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> give the relayer the sum of all relayer fees</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span> relayerFeesSum</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="nonceof"><code>nonceOf()</code></h3> <p>Nonces are needed due to the replay protection (see <em>Replay attacks</em> under <em>Security Considerations</em>).</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">mapping</span><span> (</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> private</span><span> _metaNonces</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> nonceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _metaNonces</span><span>[</span><span>account</span><span>]</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The link to the complete implementation (along with gas usage results) is here: <a rel="external" href="https://github.com/defifuture/erc20-batched-meta-transactions">https://github.com/defifuture/erc20-batched-meta-transactions</a>.</p> <blockquote> <p>Note that the OpenZeppelin ERC-20 implementation was used here. Some other implementation may have named the <code>_balances</code> mapping differently, which would require minor changes in the <code>processMetaBatch()</code> function.</p> </blockquote> <h2 id="rationale">Rationale</h2> <h3 id="all-in-one">All-in-one</h3> <p>Alternative implementations (like GSN) use multiple smart contracts to enable meta transactions, although this increases gas usage. This implementation (EIP-3005) intentionally keeps everything within one function which reduces complexity and gas cost.</p> <p>The <code>processMetaBatch()</code> function thus does the job of receiving a batch of meta transactions, validating them, and then transferring tokens from one address to another.</p> <h3 id="function-parameters">Function parameters</h3> <p>As you can see, the <code>processMetaBatch()</code> function in the reference implementation takes the following parameters:</p> <ul> <li>an array of <strong>sender addresses</strong> (meta txs senders, not relayers)</li> <li>an array of <strong>receiver addresses</strong></li> <li>an array of <strong>amounts</strong></li> <li>an array of <strong>relayer fees</strong> (relayer is <code>msg.sender</code>)</li> <li>an array of <strong>block numbers</strong> (a due "date" for meta tx to be processed)</li> <li>Three arrays that represent parts of a <strong>signature</strong> (v, r, s)</li> </ul> <p><strong>Each item</strong> in these arrays represents <strong>data of one meta transaction</strong>. That's why the <strong>correct order</strong> in the arrays is very important.</p> <p>If a relayer gets the order wrong, the <code>processMetaBatch()</code> function would notice that (when validating a signature), because the hash of the meta transaction values would not match the signed hash. A meta transaction with an invalid signature is <strong>skipped</strong>.</p> <h3 id="the-alternative-way-of-passing-meta-transaction-data-into-the-function">The alternative way of passing meta transaction data into the function</h3> <p>The reference implementation takes parameters as arrays. There's a separate array for each meta transaction data category (the ones that cannot be deduced or extracted from other sources).</p> <p>A different approach would be to bitpack all data of a meta transaction into one value and then unpack it within the smart contract. The data for a batch of meta transactions would be sent in an array, but there would need to be only one array (of packed data), instead of multiple arrays.</p> <h3 id="why-is-nonce-not-one-of-the-parameters-in-the-reference-implementation">Why is nonce not one of the parameters in the reference implementation?</h3> <p>Meta nonce is used for constructing a signed hash (see the <code>msgHash</code> line where a <code>keccak256</code> hash is constructed - you'll find a nonce there).</p> <p>Since a new nonce has to always be bigger than the previous one by exactly 1, there's no need to include it as a parameter array in the <code>processMetaBatch()</code> function, because its value can be deduced.</p> <p>This also helps avoid the "Stack too deep" error.</p> <h3 id="can-eip-2612-nonces-mapping-be-re-used">Can EIP-2612 nonces mapping be re-used?</h3> <p>The EIP-2612 (<code>permit()</code> function) also requires a nonce mapping. At this point, I'm not sure yet if this mapping should be <strong>re-used</strong> in case a smart contract implements both EIP-3005 and EIP-2612.</p> <p>At the first glance, it seems the <code>nonces</code> mapping from EIP-2612 could be re-used, but this should be thought through (and tested) for possible security implications.</p> <h3 id="token-transfers-1">Token transfers</h3> <p>Token transfers in the reference implementation could alternatively be done by calling the <code>_transfer()</code> function (part of the OpenZeppelin ERC-20 implementation), but it would increase the gas usage and it would also revert the whole batch if some meta transaction was invalid (the current implementation just skips it).</p> <p>Another gas usage optimization is to assign total relayer fees to the relayer at the end of the function, and not with every token transfer inside the for loop (thus avoiding multiple SSTORE calls that cost 5'000 gas).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The code implementation of batched meta transactions is backwards compatible with any fungible token standard, for example, ERC-20 (it only extends it with one function).</p> <h2 id="test-cases">Test Cases</h2> <p>Link to tests: <a rel="external" href="https://github.com/defifuture/erc20-batched-meta-transactions/tree/master/test">https://github.com/defifuture/erc20-batched-meta-transactions/tree/master/test</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Here is a list of potential security issues and how are they addressed in this implementation.</p> <h3 id="forging-a-meta-transaction">Forging a meta transaction</h3> <p>The solution against a relayer forging a meta transaction is for a user to sign the meta transaction with their private key.</p> <p>The <code>processMetaBatch()</code> function then verifies the signature using <code>ecrecover()</code>.</p> <h3 id="replay-attacks">Replay attacks</h3> <p>The <code>processMetaBatch()</code> function is secure against two types of a replay attack:</p> <p><strong>Using the same meta transaction twice in the same token smart contract</strong></p> <p>A nonce prevents a replay attack where a relayer would send the same meta transaction more than once.</p> <p><strong>Using the same meta transaction twice in different token smart contracts</strong></p> <p>A token smart contract address must be added into the signed hash (of a meta transaction).</p> <p>This address does not need to be sent as a parameter into the <code>processMetaBatch()</code> function. Instead, the function uses <code>address(this)</code> when constructing a hash in order to verify the signature. This way a meta transaction not intended for the token smart contract would be rejected (skipped).</p> <h3 id="signature-validation">Signature validation</h3> <p>Signing a meta transaction and validating the signature is crucial for this whole scheme to work.</p> <p>The <code>processMetaBatch()</code> function validates a meta transaction signature, and if it's <strong>invalid</strong>, the meta transaction is <strong>skipped</strong> (but the whole on-chain transaction is <strong>not reverted</strong>).</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>msgHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>sender</span><span>,</span><span> recipients</span><span>[</span><span>i</span><span>]</span><span>,</span><span> amounts</span><span>[</span><span>i</span><span>]</span><span>,</span><span> relayerFees</span><span>[</span><span>i</span><span>]</span><span>,</span><span> newNonce</span><span>,</span><span> blocks</span><span>[</span><span>i</span><span>]</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">if</span><span>(</span><span>sender </span><span class="z-keyword">!=</span><span class="z-support"> ecrecover</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span class="z-string">&quot;\x19Ethereum Signed Message:\n32&quot;</span><span>,</span><span> msgHash</span><span>)</span><span>)</span><span>,</span><span> sigV</span><span>[</span><span>i</span><span>]</span><span>,</span><span> sigR</span><span>[</span><span>i</span><span>]</span><span>,</span><span> sigS</span><span>[</span><span>i</span><span>]</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> continue</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> if sig is not valid, skip to the next meta tx</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Why not reverting the whole on-chain transaction? Because there could be only one problematic meta transaction, and the others should not be dropped just because of one rotten apple.</p> <p>That said, it is expected of relayers to validate meta transactions in advance before relaying them. That's why relayers are not entitled to a relayer fee for an invalid meta transaction.</p> <h3 id="malicious-relayer-forcing-a-user-into-over-spending">Malicious relayer forcing a user into over-spending</h3> <p>A malicious relayer could delay sending some user's meta transaction until the user would decide to make the token transaction on-chain.</p> <p>After that, the relayer would relay the delayed meta transaction which would mean that the user would have made two token transactions (over-spending).</p> <p><strong>Solution:</strong> Each meta transaction should have an "expiry date". This is defined in a form of a block number by which the meta transaction must be relayed on-chain.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> processMetaBatch</span><span>(</span><span>.</span><span>.</span><span>.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> blocks</span><span>,</span></span> <span class="giallo-l"><span> .</span><span>.</span><span>.</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">...</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> loop through all meta txs</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span>i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> senders</span><span>.</span><span>length</span><span>;</span><span> i</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>)</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> the meta tx should be processed until (including) the specified block number, otherwise it is invalid</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>number </span><span class="z-keyword">&gt;</span><span> blocks</span><span>[</span><span>i</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> continue</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> if current block number is bigger than the requested number, skip this meta tx</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">...</span></span></code></pre><h3 id="front-running-attack">Front-running attack</h3> <p>A malicious relayer could scout the Ethereum mempool to steal meta transactions and front-run the original relayer.</p> <p><strong>Solution:</strong> The protection that <code>processMetaBatch()</code> function uses is that it requires the meta transaction sender to add the relayer's Ethereum address as one of the values in the hash (which is then signed).</p> <p>When the <code>processMetaBatch()</code> function generates a hash it includes the <code>msg.sender</code> address in it:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>msgHash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span>sender</span><span>,</span><span> recipients</span><span>[</span><span>i</span><span>]</span><span>,</span><span> amounts</span><span>[</span><span>i</span><span>]</span><span>,</span><span> relayerFees</span><span>[</span><span>i</span><span>]</span><span>,</span><span> newNonce</span><span>,</span><span> blocks</span><span>[</span><span>i</span><span>]</span><span>,</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">if</span><span>(</span><span>sender </span><span class="z-keyword">!=</span><span class="z-support"> ecrecover</span><span>(</span><span class="z-support">keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span class="z-string">&quot;\x19Ethereum Signed Message:\n32&quot;</span><span>,</span><span> msgHash</span><span>)</span><span>)</span><span>,</span><span> sigV</span><span>[</span><span>i</span><span>]</span><span>,</span><span> sigR</span><span>[</span><span>i</span><span>]</span><span>,</span><span> sigS</span><span>[</span><span>i</span><span>]</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> continue</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> if sig is not valid, skip to the next meta tx</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>If the meta transaction was "stolen", the signature check would fail because the <code>msg.sender</code> address would not be the same as the intended relayer's address.</p> <h3 id="a-malicious-or-too-impatient-user-sending-a-meta-transaction-with-the-same-nonce-through-multiple-relayers-at-once">A malicious (or too impatient) user sending a meta transaction with the same nonce through multiple relayers at once</h3> <p>A user that is either malicious or just impatient could submit a meta transaction with the same nonce (for the same token contract) to various relayers. Only one of them would get the relayer fee (the first one on-chain), while the others would get an invalid meta transaction.</p> <p><strong>Solution:</strong> Relayers could <strong>share a list of their pending meta transactions</strong> between each other (sort of an info mempool).</p> <p>The relayers don't have to fear that someone would steal their respective pending transactions, due to the front-running protection (see above).</p> <p>If relayers see meta transactions from a certain sender address that have the same nonce and are supposed to be relayed to the same token smart contract, they can decide that only the first registered meta transaction goes through and others are dropped (or in case meta transactions were registered at the same time, the remaining meta transaction could be randomly picked).</p> <p>At a minimum, relayers need to share this meta transaction data (in order to detect meta transaction collision):</p> <ul> <li>sender address</li> <li>token address</li> <li>nonce</li> </ul> <h3 id="too-big-due-block-number">Too big due block number</h3> <p>The relayer could trick the meta transaction sender into adding too big due block number - this means a block by which the meta transaction must be processed. The block number could be far in the future, for example, 10 years in the future. This means that the relayer would have 10 years to submit the meta transaction.</p> <p><strong>One way</strong> to solve this problem is by adding an upper bound constraint for a block number within the smart contract. For example, we could say that the specified due block number must not be bigger than 100'000 blocks from the current one (this is around 17 days in the future if we assume 15 seconds block time).</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> the meta tx should be processed until (including) the specified block number, otherwise it is invalid</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span>(</span><span class="z-variable z-language">block</span><span>.</span><span>number </span><span class="z-keyword">&gt;</span><span> blocks</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> ||</span><span> blocks</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> &gt;</span><span> (</span><span class="z-variable z-language">block</span><span>.</span><span>number </span><span class="z-keyword">+</span><span class="z-constant"> 100000</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If current block number is bigger than the requested due block number, skip this meta tx.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Also skip if the due block number is too big (bigger than 100&#39;000 blocks in the future).</span></span> <span class="giallo-l"><span class="z-keyword"> continue</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This addition could open new security implications, that's why it is left out of this proof-of-concept. But anyone who wishes to implement it should know about this potential constraint, too.</p> <p><strong>The other way</strong> is to keep the <code>processMetaBatch()</code> function as it is and rather check for the too big due block number <strong>on the relayer level</strong>. In this case, the user could be notified about the problem and could issue a new meta transaction with another relayer that would have a much lower block parameter (and the same nonce).</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights are waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Sergio Demian Lernerhttps://github.com/SergioDemianLerner https://wg-eips.ritovision.com/2997/ <h2 id="abstract">Abstract</h2> <p>Add a new opcode, <code>IMPERSONATECALL</code> at <code>0xf6</code>, which is similar in idea to <code>CALL (0xF1)</code>, except that it impersonates a sender, i.e. the callee sees a sender different from the real caller. The impersonated sender address is derived from the real caller address and a salt.</p> <h2 id="motivation">Motivation</h2> <p>This proposal enables native multi-user wallets (wallets that serve multiple users) that can be commanded by EIP-712 based messages and therefore enable meta-transactions. Multi-user wallets also enable the aggregation of transfer operations in batches similar to rollups, but maintaining the same address space as normal onchain transactions, so the sender's wallet does not need to be upgraded to support sinding ether or tokens to a user of a multi-user wallet. Additionally, many times a sponsor company wants to deploy non-custodial smart wallets for all its users. The sponsor does not want to pay the deployment cost of each user contract in advance. Counterfactual contract creation enables this, yet it forces the sponsor to create the smart wallet (or a proxy contract to it) when the user wants to transfer ether or tokens out of his/her account for the first time. This proposal avoids this extra cost, which is at least 42000 gas per user.</p> <h2 id="specification">Specification</h2> <p><code>IMPERSONATECALL</code>: <code>0xf6</code>, takes 7 operands:</p> <ul> <li><code>gas</code>: the amount of gas the code may use in order to execute;</li> <li><code>to</code>: the destination address whose code is to be executed;</li> <li><code>in_offset</code>: the offset into memory of the input;</li> <li><code>in_size</code>: the size of the input in bytes;</li> <li><code>ret_offset</code>: the offset into memory of the output;</li> <li><code>ret_size</code>: the size of the scratch pad for the output.</li> <li><code>salt</code> is a <code>32</code> bytes value (a stack item).</li> </ul> <h3 id="computation-of-impersonated-sender">Computation of impersonated sender</h3> <p>The impersonated sender address is computed as <code>keccak256( 0xff ++ address ++ salt ++ zeros32)[12:]</code>.</p> <ul> <li> <p><code>0xff</code> is a single byte,</p> </li> <li> <p><code>address</code> is always <code>20</code> bytes, and represents the address of the real caller contract.</p> </li> <li> <p><code>salt</code> is always <code>32</code> bytes.</p> </li> <li> <p>The field zeros32 corresponds to 32 zero bytes.</p> </li> </ul> <p>This scheme emulates <code>CREATE2</code> address derivation, but it cannot practically collude with the <code>CREATE2</code> address space.</p> <h3 id="notes">Notes</h3> <ul> <li>The opcode behaves exactly as <code>CALL</code> in terms of gas consumption.</li> <li>In the called context <code>CALLER (0x33)</code> returns the impersonated address.</li> <li>If value transfer is non-zero in the call, the value is transferred from the impersonated account, and not from the real caller. This can be used to transfer ether out of an impersonated account.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Even if <code>IMPERSONATECALL</code> requires hashing 3 words, implying an additional cost of 180 gas, we think the benefit of accounting for hashing doesn't not compensate increasing the complexity of the implementation.</p> <p>We use the zeros32 field to base address derivation in a pre-image of similar size than CREATE2 and reuse the existing address derivation functions. We also avoid worrying about address collisions between EOA derivation (65 bytes pre-image), CREATE derivation (from 23 to 27 bytes pre-image, for a 32bit nonce) and CREATE2 derivation (85 bytes pre-image).</p> <p>An option is to omit the zeros32 field: the resulting length of the Keccak pre-image for IMPERSONATECALL address is 53 bytes , which does not generate address collision.</p> <p>While the same functionality could be provided in a pre-compiled contract, we believe using a new opcode is a cleaner solution.</p> <h2 id="clarifications">Clarifications</h2> <ul> <li> <p>This EIP makes address collisions possible, yet practically impossible.</p> </li> <li> <p>If a contract already exists with an impersonated address, the <code>IMPERSONATECALL</code> is executed in the same way, and the existing code will not be executed. It should be noted that <code>SELFDESTRUCT</code> (<code>0xff</code>) cannot be executed directly with <code>IMPERSONATECALL</code> as no opcode is executed in the context of the impersonated account.</p> </li> </ul> <h2 id="backward-compatibility">Backward Compatibility</h2> <p>The opcode number <code>0xf6</code> is currently unused and results in an out-of-gas (OOG) exception. Solidity uses the <code>INVALID (0xfe)</code> opcode (called <code>ABORT</code> by EIP-1803) to raise OOG exceptions, so the <code>0xf6</code> opcode does not appear in normal Solidity programs. Programmers are already advised not to include this opcode in contracts written in EVM assembly. Therefore is does not pose any backward compatibility risk.</p> <h2 id="test-cases">Test Cases</h2> <p>We present 4 examples of impersonated address derivation:</p> <p>Example 0</p> <ul> <li>address <code>0x0000000000000000000000000000000000000000</code></li> <li>salt <code>0x0000000000000000000000000000000000000000000000000000000000000000</code></li> <li>result: <code>0xFFC4F52F884A02BCD5716744CD622127366F2EDF</code></li> </ul> <p>Example 1</p> <ul> <li>address <code>0xdeadbeef00000000000000000000000000000000</code></li> <li>salt <code>0x0000000000000000000000000000000000000000000000000000000000000000</code></li> <li>result: <code>0x85F15E045E1244AC03289B48448249DC0A34AA30</code></li> </ul> <p>Example 2</p> <ul> <li>address <code>0xdeadbeef00000000000000000000000000000000</code></li> <li>salt <code>0x000000000000000000000000feed000000000000000000000000000000000000</code></li> <li>result: <code>0x2DB27D1D6BE32C9ABFA484BA3D591101881D4B9F</code></li> </ul> <p>Example 3</p> <ul> <li>address <code>0x00000000000000000000000000000000deadbeef</code></li> <li>salt <code>0x00000000000000000000000000000000000000000000000000000000cafebabe</code></li> <li>result: <code>0x5004E448F43EFE3C7BF32F94B83B843D03901457</code></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The address derivation scheme prevents address collision with another deployed contract or an externally owned account, as the impersonated sender address is derived from the real caller address and a salt.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jorge Izquierdohttps://github.com/izqui Fabien Marinohttps://github.com/bonustrack https://wg-eips.ritovision.com/3000/ <h2 id="simple-summary">Simple Summary</h2> <p>Interface for scheduling, executing and challenging contract executions based on off-chain approval</p> <h2 id="abstract">Abstract</h2> <p>ERC-3000 presents a basic on-chain spec for contracts to optimistically enact governance decisions made off-chain.</p> <p>The standard is opinionated in defining the 6 entrypoint functions to contracts supporting the standard. But it allows for any sort of resolver mechanism for the challenge/response games characteristic of optimistic contracts.</p> <p>While the authors currently believe resolving challenges <a rel="external" href="https://aragon.org/blog/snapshot">using a subjective oracle</a> is the right tradeoff, the standard has been designed such that changing to another mechanism is possible (a deterministic resolver like <a rel="external" href="https://optimism.io">Optimism's OVM</a> uses), even allowing to hot-swap it in the same live instance.</p> <h2 id="specification">Specification</h2> <h3 id="data-structures">Data structures</h3> <p>Some data structures are defined which are later used in the standard interfaces:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">library</span><span class="z-entity z-name"> ERC3000Data</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Container</span><span> {</span></span> <span class="giallo-l"><span> Payload payload</span><span>;</span></span> <span class="giallo-l"><span> Config config</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Payload</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> nonce</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> executionTime</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> submitter</span><span>;</span></span> <span class="giallo-l"><span> IERC3000Executor executor</span><span>;</span></span> <span class="giallo-l"><span> Action</span><span>[</span><span>]</span><span> actions</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> proof</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Action</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> to</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> value</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> data</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Config</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> executionDelay</span><span>;</span></span> <span class="giallo-l"><span> Collateral scheduleDeposit</span><span>;</span></span> <span class="giallo-l"><span> Collateral challengeDeposit</span><span>;</span></span> <span class="giallo-l"><span> Collateral vetoDeposit</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> resolver</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span> rules</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Collateral</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> token</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="interface-and-events">Interface and events</h3> <p>Given the data structures above, by taking advantage of the Solidity ABI encoder v2, we define four required functions and two optional functions as the interface for contracts to comply with ERC-3000.</p> <p>All standard functions are expected to revert (whether to include error messages/revert reasons as part of the standard is yet to be determined) when pre-conditions are not met or an unexpected error occurs. On success, each function must emit its associated event once and only once.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">abstract</span><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> IERC3000</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Schedules an action for execution, allowing for challenges and vetos on a defined time window</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> container</span><span class="z-comment"> A Container struct holding both the paylaod being scheduled for execution and</span></span> <span class="giallo-l"><span class="z-comment"> the current configuration of the system</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> schedule</span><span>(</span><span class="z-storage z-type">ERC3000Data</span><span>.</span><span class="z-support z-variable">Container</span><span class="z-storage z-type"> memory</span><span class="z-variable"> container</span><span>)</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> containerHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Scheduled</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> containerHash</span><span>, </span><span class="z-variable">ERC3000Data</span><span>.</span><span class="z-variable">Payload</span><span class="z-variable"> payload</span><span>, </span><span class="z-variable">ERC3000Data</span><span>.</span><span class="z-variable">Collateral</span><span class="z-variable"> collateral</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Executes an action after its execution delayed has passed and its state hasn&#39;t been altered by a challenge or veto</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> container</span><span class="z-comment"> A ERC3000Data.Container struct holding both the paylaod being scheduled for execution and</span></span> <span class="giallo-l"><span class="z-comment"> the current configuration of the system</span></span> <span class="giallo-l"><span class="z-comment"> * should be a MUST payload.executor.exec(payload.actions)</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> execute</span><span>(</span><span class="z-storage z-type">ERC3000Data</span><span>.</span><span class="z-support z-variable">Container</span><span class="z-storage z-type"> memory</span><span class="z-variable"> container</span><span>)</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> execResults</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Executed</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> containerHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> actor</span><span>, </span><span class="z-support">bytes</span><span>[</span><span>]</span><span class="z-variable"> execResults</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Challenge a container in case its scheduling is illegal as per Config.rules. Pulls collateral and dispute fees from sender into contract</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> container</span><span class="z-comment"> A ERC3000Data.Container struct holding both the paylaod being scheduled for execution and</span></span> <span class="giallo-l"><span class="z-comment"> the current configuration of the system</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> reason</span><span class="z-comment"> Hint for case reviewers as to why the scheduled container is illegal</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> challenge</span><span>(</span><span class="z-storage z-type">ERC3000Data</span><span>.</span><span class="z-support z-variable">Container</span><span class="z-storage z-type"> memory</span><span class="z-variable"> container</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> reason</span><span>)</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> resolverId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Challenged</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> containerHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> actor</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> reason</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> resolverId</span><span>, </span><span class="z-variable">ERC3000Data</span><span>.</span><span class="z-variable">Collateral</span><span class="z-variable"> collateral</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Apply arbitrator&#39;s ruling over a challenge once it has come to a final ruling</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> container</span><span class="z-comment"> A ERC3000Data.Container struct holding both the paylaod being scheduled for execution and</span></span> <span class="giallo-l"><span class="z-comment"> the current configuration of the system</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> resolverId</span><span class="z-comment"> disputeId in the arbitrator in which the dispute over the container was created</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> resolve</span><span>(</span><span class="z-storage z-type">ERC3000Data</span><span>.</span><span class="z-support z-variable">Container</span><span class="z-storage z-type"> memory</span><span class="z-variable"> container</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> resolverId</span><span>)</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> execResults</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Resolved</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> containerHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> actor</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> approved</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> OPTIONAL</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Apply arbitrator&#39;s ruling over a challenge once it has come to a final ruling</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> payloadHash</span><span class="z-comment"> Hash of the payload being vetoed</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> config</span><span class="z-comment"> A ERC3000Data.Config struct holding the config attached to the payload being vetoed</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> veto</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> payloadHash</span><span>,</span><span class="z-storage z-type"> ERC3000Data</span><span>.</span><span class="z-support z-variable">Config</span><span class="z-storage z-type"> memory</span><span class="z-variable"> config</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> reason</span><span>)</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Vetoed</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> containerHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> actor</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> reason</span><span>, </span><span class="z-variable">ERC3000Data</span><span>.</span><span class="z-variable">Collateral</span><span class="z-variable"> collateral</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> OPTIONAL: implementer might choose not to implement (initial Configured event MUST be emitted)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Apply a new configuration for all *new* containers to be scheduled</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> config</span><span class="z-comment"> A ERC3000Data.Config struct holding all the new params that will control the queue</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> configure</span><span>(</span><span class="z-storage z-type">ERC3000Data</span><span>.</span><span class="z-support z-variable">Config</span><span class="z-storage z-type"> memory</span><span class="z-variable"> config</span><span>)</span><span class="z-storage z-type"> virtual</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> configHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Configured</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> containerHash</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> actor</span><span>, </span><span class="z-variable">ERC3000Data</span><span>.</span><span class="z-variable">Config</span><span class="z-variable"> config</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The authors believe that it is very important that this standard leaves the other open to any resolver mechanism to be implemented and adopted.</p> <p>That's why a lot of the function and variable names were left intentionally bogus to be compatible with future resolvers without changing the standard.</p> <p>ERC-3000 should be seen as a public good of top of which public infrastrastructure will be built, being way more important than any particular implementation or the interests of specific companies or projects.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The standard allows for the resolver for challenges to be configured, and even have different resolvers for coexisting scheduled payloads. Choosing the right resolver requires making the right tradeoff between security, time to finality, implementation complexity, and external dependencies.</p> <p>Using a subjective oracle as resolver has its risks, since security depends on the crypto-economic properties of the system. For an analysis of crypto-economic considerations of Aragon Court, you can check <a rel="external" href="https://github.com/aragon/aragon-court/tree/master/docs/3-cryptoeconomic-considerations">the following doc</a>.</p> <p>On the other hand, implementing a deterministic resolver is prone to dangerous bugs given its complexity, and will rely on a specific version of the off-chain protocol, which could rapidly evolve while the standard matures and gets adopted.</p> <h2 id="implementations">Implementations</h2> <h3 id="1-aragon-govern">1. Aragon Govern</h3> <ul> <li><a rel="external" href="https://github.com/aragon/govern/blob/master/packages/erc3k">ERC-3000 interface (MIT license)</a></li> <li><a rel="external" href="https://github.com/aragon/govern/blob/master/packages/govern-core">Implementation (GPL-3.0 license)</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/2970/ <h2 id="simple-summary">Simple Summary</h2> <p>Add a <code>IS_STATIC (0x4A)</code> opcode that pushes <code>1</code> if the current context is static (ie. the execution is in a <code>STATICCALL</code> or a descendant thereof, so state-changing operations are not possible), and <code>0</code> if it is not.</p> <h2 id="abstract">Abstract</h2> <h2 id="motivation">Motivation</h2> <p>The main intended use case is to allow account abstraction (EIP 2938) to be extended so that accounts can allow static calls from the outside (which are harmless to AA's security model) but not state-changing calls.</p> <h2 id="specification">Specification</h2> <p>Add a <code>IS_STATIC (0x4A)</code> opcode that pushes <code>1</code> if the current context is static (ie. the execution is in a <code>STATICCALL</code> or a descendant thereof, so state-changing operations are not possible), and <code>0</code> if it is not.</p> <h2 id="rationale">Rationale</h2> <p>Determining staticness is already possibly using the following hacky technique: make a <code>CALL</code> with limited gas, and inside that <code>CALL</code> issue one <code>LOG</code> and exit. If the context is static, the <code>CALL</code> would fail and leave a 0 on the stack; if the context is non-static, the <code>CALL</code> would succeed. However, this technique is fragile against changes to gas costs, and is needlessly wasteful. Hence, the status quo neither allows a reasonably effective way of determining whether or not the context is static, nor provides any kind of invariant that executions that do not fail outright will execute the same way in a static and non-static context. This EIP provides a cleaner way of determining staticness.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gianluca Perlettihttps://github.com/Perlets9 Alan Scarpellinihttps://github.com/alanscarpellini Roberto Gorinihttps://github.com/robertogorini Manuel Olivihttps://github.com/manvel79 https://wg-eips.ritovision.com/2980/

An interface for asset tokens, compliant with Swiss Law and compatible with [ERC-20](../00020.md).

<h2 id="abstract">Abstract</h2> <p>This new standard is an <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> compatible token with restrictions that comply with the following Swiss laws: the <a href="https://wg-eips.ritovision.com/2980/./assets/Swiss-Confederation-SESTA.pdf">Stock Exchange Act</a>, the <a href="https://wg-eips.ritovision.com/2980/./assets/Swiss-Confederation-BA.pdf">Banking Act</a>, the <a href="https://wg-eips.ritovision.com/2980/./assets/Swiss-Confederation-FMIA.pdf">Financial Market Infrastructure Act</a>, the <a href="https://wg-eips.ritovision.com/2980/./assets/Swiss-Confederation-CISA.pdf">Act on Collective Investment Schemes</a> and the <a href="https://wg-eips.ritovision.com/2980/./assets/Swiss-Confederation-AMLA.pdf">Anti-Money Laundering Act</a>. The <a href="https://wg-eips.ritovision.com/2980/./assets/Swiss-Confederation-FINSA.pdf">Financial Services Act</a> and the <a href="https://wg-eips.ritovision.com/2980/./assets/Swiss-Confederation-FINIA.pdf">Financial Institutions Act</a> must also be considered. The solution achieved meet also the European jurisdiction.</p> <p>This new standard meets the new era of asset tokens (known also as "security tokens"). These new methods manage securities ownership during issuance and trading. The issuer is the only role that can manage a white-listing and the only one that is allowed to execute “freeze” or “revoke” functions.</p> <h2 id="motivation">Motivation</h2> <p>In its ICO guidance dated February 16, 2018, FINMA (Swiss Financial Market Supervisory Authority) defines asset tokens as tokens representing assets and/or relative rights (<a href="https://wg-eips.ritovision.com/2980/./assets/Finma-ICO-Guidelines.pdf">FINMA ICO Guidelines</a>). It explicitly mentions that asset tokens are analogous to and can economically represent shares, bonds, or derivatives. The long list of relevant financial market laws mentioned above reveal that we need more methods than with Payment and Utility Token.</p> <h2 id="specification">Specification</h2> <p>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> <p>The words "asset tokens" and "security tokens" can be considered synonymous.</p> <p>Every ERC-2980 compliant contract MUST implement the ERC-2980 interface.</p> <h3 id="erc-2980-token-contract">ERC-2980 (Token Contract)</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC2980</span><span> extends ERC20 </span><span>{</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when funds are reassigned</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundsReassigned</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>, </span><span class="z-support">address</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when funds are revoked</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundsRevoked</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when an address is frozen</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundsFrozen</span><span>(</span><span class="z-support">address</span><span class="z-variable"> target</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> getter to determine if address is in frozenlist</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> frozenlist</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> getter to determine if address is in whitelist</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> whitelist</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The ERC-2980 extends <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. Due to the indivisible nature of asset tokens, the decimals number MUST be zero.</p> <h3 id="whitelist-and-frozenlist">Whitelist and Frozenlist</h3> <p>The accomplishment of the Swiss Law requirements is achieved by the use of two distinct lists of address: the Whitelist and the Frozenlist. Addresses can be added to one or the other list at any time by operators with special privileges, called Issuers, and described below. Although these lists may look similar, they differ for the following reasons: the Whitelist members are the only ones who can receive tokens from other addresses. There is no restriction on the possibility that these addresses can transfer the tokens already in their ownership. This can occur when an address, present in the Whitelist, is removed from this list, without however being put in the Frozenlist and remaining in possession of its tokens. On the other hand, the addresses assigned to the Frozenlist, as suggested by the name itself, have to be considered "frozen", so they cannot either receive tokens or send tokens to anyone.</p> <p>Below is an example interface for the implementation of a whitelist-compatible and a frozenlist-compratible contract.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>Interface Whitelistable </span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> add an address to the whitelist</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is an Issuer operator</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> address to add</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> true</span><span class="z-comment"> if the address was added to the whitelist, false if the address was already in the whitelist</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addAddressToWhitelist</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> remove an address from the whitelist</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is an Issuer operator</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> address to remove</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> true</span><span class="z-comment"> if the address was removed from the whitelist, false if the address wasn&#39;t in the whitelist in the first place</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeAddressFromWhitelist</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Interface Freezable </span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> add an address to the frozenlist</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is an Issuer operator</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> address to add</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> true</span><span class="z-comment"> if the address was added to the frozenlist, false if the address was already in the frozenlist</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addAddressToFrozenlist</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> remove an address from the frozenlist</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is an Issuer operator</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> address to remove</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> true</span><span class="z-comment"> if the address was removed from the frozenlist, false if the address wasn&#39;t in the frozenlist in the first place</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeAddressFromFrozenlist</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="issuers">Issuers</h3> <p>A key role is played by the Issuer. This figure has the permission to manage Whitelists and Frozenlists, to revoke tokens and reassign them and to transfer the role to another address. No restrictions on the possibility to have more than one Issuer per contract. Issuers are nominated by the Owner of the contract, who also is in charge of remove the role. The possibility of nominating the Owner itself as Issuer at the time of contract creation (or immediately after) is not excluded.</p> <p>Below is an example interface for the implementation of the Issuer functionalities.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>Interface Issuable </span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> getter to determine if address has issuer role</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isIssuer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _addr</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> add a new issuer address</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is the contract owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> true</span><span class="z-comment"> if the address was not an issuer, false if the address was already an issuer</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addIssuer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> remove an address from issuers</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is the contract owner</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> true</span><span class="z-comment"> if the address has been removed from issuers, false if the address wasn&#39;t in the issuer list in the first place</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeIssuer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows the current issuer to transfer its role to a newIssuer</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is an Issuer operator</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _newIssuer</span><span class="z-comment"> The address to transfer the issuer role to</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferIssuer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _newIssuer</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="revoke-and-reassign">Revoke and Reassign</h3> <p>Revoke and Reassign methods allow Issuers to move tokens from addresses, even if they are in the Frozenlist. The Revoke method transfers the entire balance of the target address to the Issuer who invoked the method. The Reassign method transfers the entire balance of the target address to another address. These rights for these operations MUST be allowed only to Issuers.</p> <p>Below is an example interface for the implementation of the Revoke and Reassign functionalities.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>Interface RevokableAndReassignable </span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows the current Issuer to transfer token from an address to itself</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is an Issuer operator</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> The address from which the tokens are withdrawn</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revoke</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Allows the current Issuer to transfer token from an address to another</span></span> <span class="giallo-l"><span class="z-comment"> * Throws unless `msg.sender` is an Issuer operator</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> The address from which the tokens are withdrawn</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address who receives the tokens</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> reassign</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>There are currently no token standards that expressly facilitate conformity to securities law and related regulations. EIP-1404 (Simple Restricted Token Standard) it’s not enough to address FINMA requirements around re-issuing securities to Investors. In Swiss law, an issuer must eventually enforce the restrictions of their token transfer with a “freeze” function. The token must be “revocable”, and we need to apply a white-list method for AML/KYC checks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP does not introduce backward incompatibilities and is backward compatible with the older ERC-20 token standard. This standard allows the implementation of ERC-20 functions transfer, transferFrom, approve and allowance alongside to make a token fully compatible with ERC-20. The token MAY implement decimals() for backward compatibility with ERC-20. If implemented, it MUST always return 0.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The security considerations mainly concern the role played by the Issuers. This figure, in fact, is not generally present in common ERC-20 tokens but has very powerful rights that allow him to move tokens without being in possession and freeze other addresses, preventing them from transferring tokens. It must be the responsibility of the owner to ensure that the addresses that receive this charge remain in possession of it only for the time for which they have been designated to do so, thus preventing any abuse.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/2937/ <h2 id="simple-summary">Simple Summary</h2> <p>Add a <code>SET_INDESTRUCTIBLE (0xA8)</code> opcode that prevents the contract from calling <code>SELFDESTRUCT (0xFF)</code>.</p> <h2 id="abstract">Abstract</h2> <h2 id="motivation">Motivation</h2> <p>The intended use case would be for contracts to make their first byte of code be the <code>SET_INDESTRUCTIBLE</code> opcode if they wish to serve as libraries that guarantee to users that their code will exist unmodified forever. This is useful in account abstraction as well as other contexts.</p> <p>Unlike EIPs that disable the <code>SELFDESTRUCT</code> opcode entirely, this EIP does not modify behavior of any existing contracts.</p> <h2 id="specification">Specification</h2> <p>Add a transaction-wide global variable <code>globals.indestructible: Set[Address]</code> (i.e. a variable that operates the same way as the selfdestructs set), initialized to the empty set.</p> <p>Add a <code>SET_INDESTRUCTIBLE</code> opcode at <code>0xA8</code>, with gas cost <code>G_base</code>, that adds the current <code>callee</code> to the <code>globals.indestructible</code> set. If in the current execution context the <code>callee</code> is in <code>globals.indestructible</code>, the <code>SELFDESTRUCT</code> opcode throws an exception.</p> <h2 id="rationale">Rationale</h2> <p>Alternative proposals to this include:</p> <ul> <li>Simply banning <code>SELFDESTRUCT</code> outright. This would be ideal, but has larger backwards compatibility issues.</li> <li>Using a local variable instead of a global variable. This is problematic because it would be broken by <code>DELEGATECALL</code>.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>This breaks forward compatibility with <em>some</em> forms of state rent, which would simply delete contracts that get too old without paying some maintenance fee. However, this is not the case with all state size control schemes; for example this is not an issue if we use <a rel="external" href="https://ledgerwatch.github.io/regenesis_plan.html">ReGenesis</a>.</p> <p>If <code>SELFDESTRUCT</code> is ever removed in the future, this EIP would simply become a no-op.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Gheorghitahttps://github.com/njgheorghita Piper Merriamhttps://github.com/pipermerriam g. nicholas d'andreahttps://github.com/gnidan Benjamin Hauserhttps://github.com/iamdefinitelyahuman https://wg-eips.ritovision.com/2942/ <h2 id="simple-summary">Simple Summary</h2> <p>A custom URI scheme to identify an EthPM registry, package, release, or specific contract asset within a release.</p> <h2 id="abstract">Abstract</h2> <p>When interacting with the EthPM ecosystem, users and tooling can benefit from a URI scheme to identify EthPM assets. Being able to specify a package, registry, or release with a single string makes simplifies the steps required to install, publish, or distribute EthPM packages.</p> <h2 id="specification">Specification</h2> <p><code>scheme://registry_address[:chain_id][/package_name[@package_version[/json_pointer]]]</code></p> <h4 id="scheme"><code>scheme</code></h4> <ul> <li>Required</li> <li>Must be one of <code>ethpm</code> or <code>erc1319</code>. If future versions of the EthPM registry standard are designed and published via the ERC process, those ERCs will also be valid schemes.</li> </ul> <h4 id="registry-address"><code>registry_address</code></h4> <ul> <li>Required</li> <li>This <strong>SHOULD</strong> be either an ENS name or a 0x-prefixed, checksummed address. ENS names are more suitable for cases where mutability of the underlying asset is acceptable and there is implicit trust in the owner of the name. 0x prefixed addresses are more preferable in higher security cases to avoid needing to trust the controller of the name.</li> </ul> <h4 id="chain-id"><code>chain_id</code></h4> <ul> <li>Optional</li> <li>Integer representing the chain id on which the registry is located</li> <li>If omitted, defaults to <code>1</code> (mainnet).</li> </ul> <h4 id="package-name"><code>package_name</code></h4> <ul> <li>Optional</li> <li>String of the target package name</li> </ul> <h4 id="package-version"><code>package_version</code></h4> <ul> <li>Optional</li> <li>String of the target package version</li> <li>If the package version contains any <a rel="external" href="https://en.wikipedia.org/wiki/Percent-encoding">url unsafe characters</a>, they <strong>MUST</strong> be safely escaped</li> <li>Since semver is not strictly enforced by the ethpm spec, if the <code>package_version</code> is omitted from a uri, tooling <strong>SHOULD</strong> avoid guessing in the face of any ambiguity and present the user with a choice from the available versions.</li> </ul> <h4 id="json-pointer"><code>json_pointer</code></h4> <ul> <li>Optional</li> <li>A path that identifies a specific asset within a versioned package release.</li> <li>This path <strong>MUST</strong> conform to the <a rel="external" href="https://tools.ietf.org/html/rfc6901">JSON pointer</a> spec and resolve to an available asset within the package.</li> </ul> <h2 id="rationale">Rationale</h2> <p>Most interactions within the EthPM ecosystem benefit from a single-string representation of EthPM assets; from installing a package, to identifying a registry, to distributing a package. A single string that can faithfully represent any kind of EthPM asset, across the mainnet or testnets, reduces the mental overload for new users, minimizes configuration requirements for frameworks, and simplifies distribution of packages for package authors.</p> <h2 id="test-cases">Test Cases</h2> <p>A JSON file for testing various URIs can be found in the <a rel="external" href="https://github.com/ethpm/ethpm-spec/"><code>ethpm-spec</code></a> repository fixtures.</p> <h2 id="implementation">Implementation</h2> <p>The EthPM URI scheme has been implemented in the following libraries:</p> <ul> <li><a rel="external" href="https://eth-brownie.readthedocs.io/en/stable/">Brownie</a></li> <li><a rel="external" href="https://www.trufflesuite.com/docs/truffle/overview">Truffle</a></li> <li><a rel="external" href="https://ethpm-cli.readthedocs.io/en/latest/">EthPM CLI</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>In most cases, an EthPM URI points to an immutable asset, giving full security that the target asset has not been modified. However, in the case where an EthPM URI uses an ENS name as its registry address, it is possible that the ENS name has been redirected to a new registry, in which case the guarantee of immutability no longer exists.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/2936/ <h2 id="simple-summary">Simple Summary</h2> <p>Enable new opcode to clear storage for <code>SELFDESTRUCTED</code>ed contracts.</p> <h2 id="abstract">Abstract</h2> <p>Changes <code>SELFDESTRUCT</code> (<code>0xff</code>) to not clear any storage and adds a new <code>EXTCLEAR</code> (<code>0x5c</code>) opcode that will clear a specific storage slot for a contract that has previously been self destructed.</p> <h2 id="motivation">Motivation</h2> <p><code>SELFDESTRUCT</code> (<code>0xFF</code>) is unnecessarily complex because it clears an unbounded amount of contract storage. It is computationally expensive for nodes to track all of the storage used in every contract in case the contract <code>SELFDESTRUCT</code>s. Further, contracts can be re-initialized using <code>CREATE2</code> (<code>0xF5</code>), and then <code>SLOAD</code> (<code>0x54</code>) prior storage. Therefore, several ethereum clients do not clear storage at all, and just check if the contract was initiated since <code>SSTORE</code> (<code>0x55</code>) during <code>SLOAD</code>. <code>CREATE2</code> was not intended to complicate <code>SLOAD</code>, and this change reverts that complexity. Also, bugs in this implementation could split the network.</p> <p>Instead this defers the time of storage cleanup, and leaves the storage in-place, which reduces the complexity of <code>SLOAD</code> and <code>SELFDESTRUCT</code>.</p> <p>This empowers the <code>CREATE2</code> reincarnation proxy pattern by retaining storage during upgrade, which would otherwise have to be reset again. An atomic reincarnation upgrade could clear a subset of storage during the upgrade, while the contract is destroyed, before reinstating it.</p> <h2 id="specification">Specification</h2> <p>After <code>FORK_BLOCK_NUM</code>, a new opcode, <code>EXTCLEAR</code>, is enabled at <code>0x5C</code> to clear storage for <code>SELFDESTRUCT</code>ed contracts. <code>EXTCLEAR</code>:</p> <ul> <li>does not push any words onto the stack</li> <li>pops two words off the stack: the destroyed contract address and a storage address</li> <li>if the contract exists, charge the same gas cost as <code>EXTCODEHASH</code> (<code>0x3F</code>)</li> <li>otherwise, if the storage is zero, charge the same gas as <code>EXTCODEHASH</code> plus <code>SLOAD</code></li> <li>otherwise, the destroyed contract's slot is reset to 0, charging the same gas as <code>EXTCODEHASH</code> and <code>SSTORE</code> when resetting storage, while also refunding the amount specified in <code>SSTORE</code>.</li> </ul> <p><code>SELFDESTRUCT</code> is modified to not clear contract storage. This change also works retroactively: all prior destroyed contracts can be cleaned up.</p> <h2 id="rationale">Rationale</h2> <p><code>0x5C</code> is available in the same range as <code>SSTORE</code> and <code>SLOAD</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>A reincarnation upgrade mechanism that expects all internal storage to be cleared might break, but such an upgrade mechanism would allow adaptation to this new behavior.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO</p> <h2 id="implementation">Implementation</h2> <p>Implementation is required on all major clients to add the opcode.</p> <h2 id="security-considerations">Security Considerations</h2> <p>A reincarnated contract that does not expect its state to be cleared by malicious actors SHOULD reinitialize itself to avoid antagonistic <code>EXTCLEAR</code>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-09-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Guillaume Ballethttps://github.com/gballet Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/3102/ <h2 id="simple-summary">Simple Summary</h2> <p>Change the storage structure from hexary to binary, merge the account and storage tries, and use blake2b.</p> <h2 id="abstract">Abstract</h2> <p>This proposal presents a binary structure and merkelization rule for the account and storage tries, which are merged into a single “state” trie. RLP and most of the MPT’s optimizations are dropped to simplify the design. Keccak256 is replaced with blake2b.</p> <h2 id="motivation">Motivation</h2> <p>The current design of the Merkle Patricia Trie (MPT) uses an hexary trie. Hexary Merkle trees are more shallow than their binary counterparts, which means less hashing. Over the course of the 5 years of Ethereum’s existence, it has become apparent that disk accesses are a greater bottleneck than hashing. Clients are therefore moving away from a storage model in which all internal nodes are stored, in favor of a flat (key, value) storage model first used by turbo-geth, in which the intermediate nodes are recalculated only when needed.</p> <p>There is a push for making Ethereum easier to use in a stateless fashion. Binary tries make for smaller (~4x) proofs than hexary tries, making it the design of choice for a stateless-friendly Ethereum.</p> <p>For that same reason, the account and storage tries are merged in order to have a single proof for all changes.</p> <p>The MPT design is also rife with uncanny optimizations for size, that have a limited effect - at the cost of prohibitive complexity. For example, nesting for children whose RLP is less than 32 bytes saves an estimated 1MB of disk space. A paltry compared to the 300GB required by a fast sync at the time of this writing. These optimizations are a significant source of errors, and therefore a consensus-breaking risk. The reliance on RLP has also been criticized for its complexity, while the overhead of a general-purpose encoding scheme isn’t warranted for the rigid structure of a Merkle trie.</p> <p>The desire to switch the storage model from an hexary trie to a binary trie provides an opportunity to adopt a simpler trie architecture that pushes optimizations from the protocol level down to that of the client implementors.</p> <h2 id="specification">Specification</h2> <h3 id="conventions">Conventions</h3> <table><thead><tr><th style="text-align: center">Code</th><th>Description</th></tr></thead><tbody> <tr><td style="text-align: center"><code>u256(x)</code></td><td>Big endian, 32-byte representation of number <em>x</em></td></tr> <tr><td style="text-align: center">`</td><td></td></tr> <tr><td style="text-align: center"><code>++</code></td><td>Bit-wise concatenation operator</td></tr> <tr><td style="text-align: center"><code>0b0101</code></td><td>The binary string <code>0101</code></td></tr> <tr><td style="text-align: center"><code>hash()</code></td><td>The usual hashing function</td></tr> <tr><td style="text-align: center"><code>empty_hash</code></td><td>The empty hash: <code>hash("")</code></td></tr> <tr><td style="text-align: center"><code>length(x)</code></td><td>The byte length of object <code>x</code></td></tr> <tr><td style="text-align: center"><code>d[a..b]</code></td><td>The big-endian bit sequence taken from byte sequence <code>d</code>, starting at bit index <code>a</code>, up to and including the bit at index <code>b</code>.</td></tr> </tbody></table> <h3 id="notable-changes-from-the-hexary-structure">Notable changes from the hexary structure</h3> <ul> <li>Account and storage tries are merged, with key length between 32 and 64 bytes;</li> <li>RLP is no longer used;</li> <li>The "leaf marker" bit used in the hex prefix is also dropped. Leaves are identified as nodes with no children;</li> <li>Serialized nodes are hashed, no matter how small the byte length of the serialized nodes.</li> </ul> <h3 id="the-trie">The trie</h3> <h4 id="structure">Structure</h4> <p>The trie structure is made up of <em>nodes</em>. A node <code>N ≡ (N_l,N_r,N_p,N_v)</code> has the following 4 components:</p> <ul> <li><code>N_l</code> is the hash to the node's <em>left child</em>. If the node does not have a left child, then <code>N_l</code> is the empty hash <code>empty_hash</code>;</li> <li><code>N_r</code> is the hash to the node's <em>right child</em>. If the node does not have a right child, then <code>N_r</code> is the empty hash <code>empty_hash</code>;</li> <li>the optional <code>N_p</code> is the node's <em>prefix</em> : every key into the subtrie rooted at <code>N</code> is prefixed by this bit string;</li> <li><code>N_v</code> is the <em>value</em> stored at this node. The value is <strong>only present in leaf nodes</strong>.</li> </ul> <p>Nodes with <code>empty_hash</code> as both children are called <em>leaf nodes</em>, and the remaining nodes are known as <em>internal nodes</em>.</p> <h4 id="accessing-account-s-balance-nonce-code-storage-root-and-storage-slots">Accessing account's balance, nonce, code, storage root and storage slots</h4> <p>Assuming an account <code>A ≡ (A_b, A_n, A_c, A_s)</code> at address <code>A_a</code>, the following elements can be found at the following addresses:</p> <ul> <li>The account balance <code>A_b</code> can be found at key <code>hash(A_a)[0..253] ++ 0b00</code> and is of type <code>uint256</code>;</li> <li>The account nonce <code>A_n</code> can be found at key <code>hash(A_a)[0..253] ++ 0b01</code> and is of type <code>uint64</code>;</li> <li>The code <code>A_c</code> is an arbitrary-length byte sequence that can be found at key <code>hash(A_a)[0..253] ++ 0b10</code>;</li> <li>The root of the storage trie <code>A_s</code> can be found at key <code>hash(A_a)[0..253] ++ 0b11</code> <ul> <li>The storage slot number <code>k</code> can be found at key <code>hash(A_a)[0..253] ++ 0b11 ++ hash(k)</code>.</li> </ul> </li> </ul> <p>After <a href="https://wg-eips.ritovision.com/2926/">EIP-2926</a> has been rolled out, <code>A_c</code> will represent the root of the code merkelization tree. The key accessing code chunk number <code>c</code> is <code>hash(A_a)[0..253] ++ 0b10 ++ u256(c)</code>.</p> <p>In the unlikely future case that extra items are to be added to the trie at account level, a third bit can be reserved for future use.</p> <h3 id="node-merkelization-rule">Node merkelization rule</h3> <p>Leaves and nodes that have no prefix are hashed according to the rule below:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>internal_hash = hash(left_child_hash || right_child_hash)</span></span> <span class="giallo-l"><span>leaf_hash = hash(hash(key) || hash(leaf_value))</span></span></code></pre> <p>If a prefix is present, the length of the path from the root to the prefixed node is further concatenated with the output of the prefix-less rule, and hashed again:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>internal_hash_with_prefix = hash(u256(path_length_u256 - 1) || internal_hash)</span></span> <span class="giallo-l"><span>leaf_hash_with_prefix = hash(u256(path_length_u256 - 1) || leaf_hash)</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="blake2b">blake2b</h3> <p>BLAKE2 offers better performance, which is key to compensate for the loss of performance associated to a ~4x increase in the number of nodes.</p> <p>BLAKE3 offers even better performance. No official golang release exists at the time of the writing of this document. This presents a security risk, and therefore BLAKE2 is considered instead.</p> <h3 id="merging-of-the-account-and-storage-tries">Merging of the account and storage tries</h3> <p>The trend in clients is to store the keys and values in a "flat" database. Having the key of any storage slot prefixed with the address key of the account it belongs to helps grouping all of an account's data on disk, as well as simplifying the witness structure.</p> <h3 id="prefixes-and-extension-nodes">Prefixes and extension nodes</h3> <p>An alternative proposal has been made, which provides optimal witnesses. The trade-off is that extension nodes must be removed.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>node_hash = hash(left_child_hash || right_child_hash)</span></span> <span class="giallo-l"><span>leaf_hash = hash(0 || leaf_value)</span></span></code></pre> <p>The removal of extension nodes induces 40x higher hashing costs (on the order of 25ms for a trie with only 1k leaves) and as a result they have been kept.</p> <p>An attempt to keep extension nodes for witness and not the merkelization rule can be found <a rel="external" href="https://notes.ethereum.org/m5VMkX8FRvi0Q_OOR7TF4A">here</a>.</p> <p>Getting rid of complex methods like RLP, the hex prefix and children nesting is already offering great simplification.</p> <h3 id="2x32-byte-inputs">2x32-byte inputs</h3> <p>It has been requested to keep each node hash calculation as a function that takes two 256-bit integer as an input and outputs one 256-bit integer. This property is expected to play nice with circuit constructions and is therefore expected to greatly help with future zero-knowledge applications.</p> <h3 id="binary-tries">Binary tries</h3> <p>Binary tries have been chosen primarily because they reduce the witness size. In general, in an <code>N</code>-element tree with each element having <code>k</code> children, the average length of a branch is roughly <code>32 * (k-1) * log(N) / log(k)</code> plus a few percent for overhead. 32 is the length of a hash; the <code>k-1</code> refers to the fact that a Merkle proof needs to provide all <code>k-1</code> sister nodes at each level, and <code>log(N) / log(k)</code> is an approximation of the number of levels in the tree (eg. a tree where each node has 5 children, with 625 nodes total, would have depth 4, as <code>625 = 5**4</code> and so <code>log(625) / log(5) = 4</code>).</p> <p>For any <code>N</code>, the expression is minimized at <code>k = 2</code>. Here's a table of branch lengths for different <code>k</code> values assuming <code>N = 2**24</code>:</p> <table><thead><tr><th><code>k</code> (children per node)</th><th>Branch length (chunks)</th><th>Branch length (bytes)</th></tr></thead><tbody> <tr><td>2</td><td>1 * 24 = 24</td><td>768</td></tr> <tr><td>4</td><td>3 * 12 = 36</td><td>1152</td></tr> <tr><td>8</td><td>7 * 8 = 56</td><td>1792</td></tr> <tr><td>16</td><td>15 * 6 = 90</td><td>2880</td></tr> </tbody></table> <p>Actual branch lengths will be slightly larger than this due to uneven distribution and overhead, but the pattern of <code>k=2</code> being by far the best remains.</p> <p>The ethereum tree was originally hexary because this would reduce the number of database reads (eg. 6 instead of 24 in the above example). It is now understood that this reasoning was flawed, because nodes can still "pretend" that a binary tree is a hexary (or even 256-ary) tree at the database layer (eg. see https://ethresear.ch/t/optimizing-sparse-merkle-trees/3751), and thereby get the best-of-both-worlds of having the low proof sizes of the tree being binary from a hash-structure perspective and at the same time a much more efficient representation in the database.</p> <p>Additionally, binary trees are expected to be widely used in Eth2, so this path improves forward-compatibility and reduces long-run total complexity for the protocol.</p> <h3 id="path-length-instead-of-bit-prefix">Path length instead of bit prefix</h3> <p>In order to remove the complexity associated with byte manipulation, only the bit-length of the extension is used to merkelize a node with a prefix.</p> <p>Storing the length of the path from the root node instead of that from the parent node has the nice property that siblings need not be hashed when deleting a leaf.</p> <p><img src="https://wg-eips.ritovision.com/3102/./assets/sibling.svg" alt="Sibling deletion diagram" /></p> <p><em>On the left, a trie with the prefix length, and on the right, a trie with the full path length. Each both have values <code>10000100</code> and <code>10000000</code>. After deleting <code>10000100</code>,the sibling node has to be updated in the left tree, while it need not be in the case on the right.</em></p> <h3 id="value-hashing">Value hashing</h3> <p>Except for the code, all values in the trie are less than 32 bytes. EIP-2926 introduces code chunks, with <code>CHUNK_SIZE = 32 bytes</code>. The hashing of the leaf's value could therefore be saved. The authors of the EIP are however considering a future increase of <code>CHUNK_SIZE</code>, making <code>hash(value)</code> the future-proof choice.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>A hard fork is required in order for blocks to have a trie root using a different structure.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <ul> <li>As of <a rel="external" href="https://github.com/gballet/multiproof-rs/commit/6d22b1aef9548581826b3c04b3e00d6cc709388c">commit 0db87e187dc0bfb96046a47e3d6768c93a2e3331</a>, <a rel="external" href="https://github.com/gballet/multiproof-rs">multiproof-rs</a> implements this merkelization rule in the <code>hash_m5()</code> function, found in file <code>src/binary_tree.rs</code>.</li> <li>An implementation of this structure for go-ethereum is available <a rel="external" href="https://github.com/gballet/go-ethereum/tree/rebased-binary-trie-m5-full-path">in this branch</a>.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Issues could arise when performing the transition. In particular, a heavy conversion process could incentivize clients to wait the transition out. This could lead to a lowered network security at the time of the transition. A transition process has been proposed with <a href="https://wg-eips.ritovision.com/2584/">EIP-2584</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-08-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Tony Carsontony.carsonn@gmail.com Mehmet Sabir Kirazm.kiraz@gmail.com Süleyman Kardaşskardas@gmail.com https://wg-eips.ritovision.com/2917/ <h2 id="simple-summary">Simple Summary</h2> <p>ERC2917 is a new standardization for on-chain calculation of staking reward.</p> <h2 id="abstract">Abstract</h2> <p>Based on the product of effective collateral and time, ERC2917 calculates the reward a user can get at any time, and realize the real decentralized DeFi. Here below is the formula for the calculation of reward for a user U:</p> <p><img src="https://wg-eips.ritovision.com/2917/./assets/erc-reward-formula.png" alt="concept image" title="erc-reward-formula" /></p> <p>where ∆p<sub>i</sub> denotes individual productivity of the user U between the consecutive block numbers t<sub>i-1</sub> and t<sub>i</sub>, ∆P<sub>i</sub> denotes global productivity between the consecutive block numbers t<sub>i-1</sub> and t<sub>i</sub>, and ∆G<sub>i</sub> denotes gross product between the consecutive block numbers t<sub>i-1</sub> and t<sub>i</sub>. The formula ensures that there is no benefit in case of exiting earlier or entering later in the computation. The reward a user can get for a period is based on his total productivity during that specific time. The formula has been simplified through Solidity and generalized design to make it available across all DeFi products. We note that the smart contract can be triggered for every computation of on the following events:</p> <ul> <li>whenever the productivity of a user changes (increase/decrease),</li> <li>whenever a user withdraws.</li> </ul> <h2 id="motivation">Motivation</h2> <p>One of the main drawbacks of many DeFi projects is the reward distribution mechanism within the smart contract. In fact, there are two main mechanisms are adopted so far.</p> <ol> <li>Distribution of rewards is only given when all users exit the contract</li> <li>The project collects on-chain data, conducts calculation off-chain, and sends the results to the chain before starting rewards distribution accordingly</li> </ol> <p>The first approach conducts all calculation in an on-chain fashion, the cycle of its rewards distribution is too long. Furthermore, users need to remove their collateral before getting the rewards, which can be harmful for their rewards. The second approach is a semi-decentralized model since the main algorithm involves an off-chain computation. Therefore, the fairness and transparency properties cannot be reflected and this can even create the investment barrier for users.</p> <p>Since there is more DeFi projects coming out everyday, users could not find a proper way to get to know:</p> <ol> <li>amount of interests he/she would get</li> <li>how the interest calculated</li> <li>what is his/her contribution compare to the overall</li> </ol> <p>By standardizing ERC2917, it abstracts the interface for interests generation process. Making wallet applications easier to collect each DeFi's metrics, user friendlier.</p> <h2 id="specification">Specification</h2> <p>Every ERC-2917 compliant contract must implement the ERC2917 and ERC20 interfaces (if necessary):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC2917</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC20</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emit when interests amount per block is </span><span class="z-keyword">changed</span><span class="z-comment"> by the owner of the contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> It emits with the old interests amount and the new interests amount.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> InterestRatePerBlockChanged</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> oldValue</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> newValue</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emit when a users&#39; productivity has </span><span class="z-keyword">changed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> It emits with the user&#39;s address and the value after the change.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ProductivityIncreased</span><span> (</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emit when a users&#39; productivity has </span><span class="z-keyword">changed</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> It emits with the user&#39;s address and the value after the change.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ProductivityDecreased</span><span> (</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Return the current contract&#39;s interests rate per block.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> amount of interests currently producing per each block.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> interestsPerBlock</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Change the current contract&#39;s interests rate.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-keyword"> Note</span><span class="z-comment"> the best practice will be restrict the gross product provider&#39;s contract address to call this.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> true/false to notice that the value has successfully </span><span class="z-keyword">changed</span><span class="z-comment"> or not, when it succeed, it will emite the InterestRatePerBlockChanged event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> changeInterestRatePerBlock</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> It will get the productivity of given user.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> it will return 0 if user has no productivity proved in the contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> user</span><span class="z-comment">&#39;s productivity and overall productivity.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getProductivity</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>,</span><span class="z-support"> uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> increase a user&#39;s productivity.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-keyword"> Note</span><span class="z-comment"> the best practice will be restrict the callee to prove of productivity&#39;s contract address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> true</span><span class="z-comment"> to confirm that the productivity added success.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> increaseProductivity</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> decrease a user&#39;s productivity.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-keyword"> Note</span><span class="z-comment"> the best practice will be restrict the callee to prove of productivity&#39;s contract address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> true</span><span class="z-comment"> to confirm that the productivity removed success.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> decreaseProductivity</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> take() will return the interests that callee will get at current block height.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> it will always calculated by block.number, so it will change when block height changes.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> amount</span><span class="z-comment"> of the interests that user are able to mint() at current block height.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> take</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> similar to take(), but with the block height joined to calculate return.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> for instance, it returns (_amount, _block), which means at block height _block, the callee has accumulated _amount of interests.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> amount</span><span class="z-comment"> of interests and the block height.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> takeWithBlock</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>,</span><span class="z-support"> uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> mint the available interests to callee.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> once it mint, the amount of interests will transfer to callee&#39;s address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> amount of interests minted.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mint</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="interestrateperblockchanged">InterestRatePerBlockChanged</h3> <p>This emit when interests amount per block is changed by the owner of the contract. It emits with the old interests amount and the new interests amount.</p> <h3 id="productivityincreased">ProductivityIncreased</h3> <p>It emits with the user's address and the value after the change.</p> <h3 id="productivitydecreased">ProductivityDecreased</h3> <p>It emits with the user's address and the value after the change.</p> <h3 id="interestsperblock">interestsPerBlock</h3> <p>It returns the amount of interests currently producing per each block.</p> <h3 id="changeinterestrateperblock">changeInterestRatePerBlock</h3> <p>Note the best practice will be restrict the gross product provider's contract address to call this.</p> <p>The true/false to notice that the value has successfully changed or not, when it succeed, it will emite the InterestRatePerBlockChanged event.</p> <h3 id="getproductivity">getProductivity</h3> <p>It returns user's productivity and overall productivity. It returns 0 if user has no productivity proved in the contract.</p> <h3 id="increaseproductivity">increaseProductivity</h3> <p>It increases a user's productivity.</p> <h3 id="decreaseproductivity">decreaseProductivity</h3> <p>It decreases a user's productivity.</p> <h3 id="take">take</h3> <p>It returns the interests that callee will get at current block height.</p> <h3 id="takewithblock">takeWithBlock</h3> <p>Similar to take(), but with the block height joined to calculate return.</p> <p>For instance, it returns (_amount, _block), which means at block height _block, the callee has accumulated _amount of interests.</p> <p>It returns amount of interests and the block height.</p> <h3 id="mint">mint</h3> <p>it mints the amount of interests will transfer to callee's address. It returns the amount of interests minted.</p> <h2 id="rationale">Rationale</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>The implementation code is on the github:</p> <ul> <li><a rel="external" href="https://github.com/gnufoo/ERC3000-Proposal">ERC2917 Demo</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-08-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jonathan Underwoodhttps://github.com/junderw https://wg-eips.ritovision.com/2876/ <h2 id="simple-summary">Simple Summary</h2> <p>This ERC defines a simple contract interface for managing deposits. It also defines a new address format that encodes the extra data passed into the interface's main deposit function.</p> <h2 id="abstract">Abstract</h2> <p>An ERC-2876 compatible <strong>deposit system</strong> can accept ETH payments from multiple depositors without the need for managing multiple keys or requiring use of a hot wallet.</p> <p>An ERC-2876 compatible <strong>wallet application</strong> can send ETH to ERC-2876 compatible <strong>deposit systems</strong> in a way that the <strong>deposit system</strong> can differentiate their payment using the 8 byte id specified in this standard.</p> <p>Adoption of ERC-2876 by all exchanges (as a deposit system and as a wallet for their withdrawal systems), merchants, and all wallet applications/libraries will likely decrease total network gas usage by these systems, since two value transactions cost 42000 gas while a simple ETH forwarding contract will cost closer to 30000 gas depending on the underlying implementation.</p> <p>This also has the benefit for deposit system administrators of allowing for all deposits to be forwarded to a cold wallet directly without any manual operations to gather deposits from multiple external accounts.</p> <h2 id="motivation">Motivation</h2> <p>Centralized exchanges and merchants (Below: "apps") require an address format for accepting deposits. Currently the address format used refers to an account (external or contract), but this creates a problem. It requires that apps create a new account for every invoice / user. If the account is external, that means the app must have the deposit addresses be hot wallets, or have increased workload for cold wallet operators (as each deposit account will create 1 value tx to sweep). If the account is contract, generating an account costs at least 60k gas for a simple proxy, which is cost-prohibitive.</p> <p>Therefore, merchant and centralized exchange apps are forced between taking on one of the following:</p> <ul> <li>Large security risk (deposit accounts are hot wallets)</li> <li>Large manual labor cost (cold account manager spends time sweeping thousands of cold accounts)</li> <li>Large service cost (deploying a contract-per-deposit-address model).</li> </ul> <p>The timing of this proposal is within the context of increased network gas prices. During times like this, more and more services who enter the space are being forced into hot wallets for deposits, which is a large security risk.</p> <p>The motivation for this proposal is to lower the cost of deploying and managing a system that accepts deposits from many users, and by standardizing the methodology for this, services across the world can easily use this interface to send value to and from each other without the need to create multiple accounts.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <ul> <li>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.</li> <li><code>The contract interface</code> is the contract component of this ERC.</li> <li><code>The deposit address format</code> is the newly made format described in "Deposit Address Format" for encoding the 20 byte account address and the 8 byte id.</li> <li><code>The contract</code> refers to the contract that implements <code>the contract interface</code> of this ERC.</li> <li><code>The 8 byte "id"</code> is an 8 byte id used as the input parameter for the contract interface.</li> <li><code>The 5 byte "nonce"</code> is the first 5 most significant bytes of the <code>"id"</code>.</li> <li><code>The 3 byte "checksum"</code> is the last 3 least significant bytes of the <code>"id"</code></li> <li><code>deposit(bytes8)</code> refers to the function of that signature, which is defined in <code>the contract interface</code>.</li> <li><code>The parent application</code> refers to the application that will use the information gained within the <code>deposit(bytes8)</code> function. (ie. an exchange backend or a non-custodial merchant application)</li> <li><code>The depositor</code> refers to the person that will send value to <code>the contract</code> via the <code>deposit(bytes8)</code> call.</li> <li><code>The wallet</code> refers to any application or library that sends value transactions upon the request of <code>the depositor</code>. (ie. MyEtherWallet, Ledger, blockchain.com, various libraries)</li> </ul> <h3 id="deposit-address-format">Deposit Address Format</h3> <p>In order to add the 8 byte "id" data, we need to encode it along with the 20 byte account address. The 8 bytes are appended to the 20 byte address.</p> <p>A 3 byte checksum is included in the id, which is the first 3 bytes of the keccak256 hash of the 20 byte address and first 5 byte nonce of the id concatenated (25 bytes).</p> <p>The Deposit Address format can be generated with the following JavaScript code:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * Converts a 20 byte account address and a 5 byte nonce to a deposit address.</span></span> <span class="giallo-l"><span class="z-comment"> * The format of the return value is 28 bytes as follows. The + operator is byte</span></span> <span class="giallo-l"><span class="z-comment"> * concatenation.</span></span> <span class="giallo-l"><span class="z-comment"> * (baseAddress + nonce + keccak256(baseAddress + nonce)[:3])</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">param</span><span class="z-entity z-name"> {</span><span class="z-entity z-name">String</span><span class="z-entity z-name">}</span><span class="z-variable z-other"> baseAddress</span><span class="z-comment"> the given HEX address (20 byte hex string with 0x prepended)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">param</span><span class="z-entity z-name"> {</span><span class="z-entity z-name">String</span><span class="z-entity z-name">}</span><span class="z-variable z-other"> nonce</span><span class="z-comment"> the given HEX nonce (5 byte hex string with 0x prepended)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">return</span><span class="z-entity z-name"> {</span><span class="z-entity z-name">String</span><span class="z-entity z-name">}</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> generateAddress</span><span> (</span><span class="z-variable">baseAddress</span><span>,</span><span class="z-variable"> nonce</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span></span> <span class="giallo-l"><span class="z-keyword"> !</span><span class="z-variable z-other">baseAddress</span><span>.</span><span class="z-entity z-name">match</span><span>(</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-string z-regexp">0x</span><span class="z-constant">[</span><span class="z-constant">0-9</span><span class="z-constant">a-f</span><span class="z-constant">A-F</span><span class="z-constant">]</span><span class="z-keyword">{40}</span><span class="z-keyword">$</span><span class="z-punctuation z-definition z-string">/</span><span>)</span><span class="z-keyword"> ||</span></span> <span class="giallo-l"><span class="z-keyword"> !</span><span class="z-variable z-other">nonce</span><span>.</span><span class="z-entity z-name">match</span><span>(</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-string z-regexp">0x</span><span class="z-constant">[</span><span class="z-constant">0-9</span><span class="z-constant">a-f</span><span class="z-constant">A-F</span><span class="z-constant">]</span><span class="z-keyword">{10}</span><span class="z-keyword">$</span><span class="z-punctuation z-definition z-string">/</span><span>)</span></span> <span class="giallo-l"><span> )</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> throw</span><span class="z-keyword"> new</span><span class="z-entity z-name"> Error</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">Base Address and nonce must be 0x hex strings</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ret</span><span class="z-keyword"> =</span></span> <span class="giallo-l"><span class="z-variable z-other"> baseAddress</span><span>.</span><span class="z-entity z-name">toLowerCase</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span class="z-variable z-other"> nonce</span><span>.</span><span class="z-entity z-name">toLowerCase</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">replace</span><span>(</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-string z-regexp">0x</span><span class="z-punctuation z-definition z-string">/</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> myHash</span><span class="z-keyword"> =</span><span class="z-variable z-other"> web3</span><span>.</span><span class="z-variable z-other">utils</span><span>.</span><span class="z-entity z-name">keccak256</span><span>(</span><span class="z-variable z-other">ret</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> ret</span><span class="z-keyword"> +</span><span class="z-variable z-other"> myHash</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">2</span><span>,</span><span class="z-constant"> 8</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> first 3 bytes from the 0x hex string</span></span> <span class="giallo-l"><span>}</span><span>;</span></span></code></pre> <p>The checksum can be verified within the deposit contract itself using the following:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> checksumMatch</span><span>(</span><span class="z-support">bytes8</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> chkhash </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span class="z-support">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-support"> bytes5</span><span>(</span><span>id</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes3</span><span> chkh </span><span class="z-keyword">=</span><span class="z-support"> bytes3</span><span>(</span><span>chkhash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes3</span><span> chki </span><span class="z-keyword">=</span><span class="z-support"> bytes3</span><span>(</span><span class="z-support">bytes8</span><span>(</span><span class="z-support">uint64</span><span>(</span><span>id</span><span>)</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 40</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> chkh </span><span class="z-keyword">==</span><span> chki</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="the-contract-interface">The Contract Interface</h3> <p>A contract that follows this ERC:</p> <ul> <li><code>The contract</code> MUST revert if sent a transaction where <code>msg.data</code> is null (A pure value transaction).</li> <li><code>The contract</code> MUST have a deposit function as follows:</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> DepositEIP</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deposit</span><span>(</span><span class="z-support">bytes8</span><span class="z-variable"> id</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li><code>deposit(bytes8)</code> MUST return <code>false</code> when the contract needs to keep the value, but signal to the depositor that the deposit (in terms of the parent application) itself has not yet succeeded. (This can be used for partial payment, ie. the invoice is for 5 ETH, sending 3 ETH returns false, but sending a second tx with 2 ETH will return true.)</li> <li><code>deposit(bytes8)</code> MUST revert if the deposit somehow failed and the contract does not need to keep the value sent.</li> <li><code>deposit(bytes8)</code> MUST return <code>true</code> if the value will be kept and the payment is logically considered complete by the parent application (exchange/merchant).</li> <li><code>deposit(bytes8)</code> SHOULD check the checksum contained within the 8 byte id. (See "Deposit Address Format" for an example)</li> <li><code>The parent application</code> SHOULD return any excess value received if the deposit id is a one-time-use invoice that has a set value and the value received is higher than the set value. However, this SHOULD NOT be done by sending back to <code>msg.sender</code> directly, but rather should be noted in the parent application and the depositor should be contacted out-of-band to the best of the application manager's ability.</li> </ul> <h3 id="depositing-value-to-the-contract-from-a-wallet">Depositing Value to the Contract from a Wallet</h3> <ul> <li><code>The wallet</code> MUST accept <code>the deposit address format</code> anywhere the 20-byte address format is accepted for transaction destination.</li> <li><code>The wallet</code> MUST verify the 3 byte checksum and fail if the checksum doesn't match.</li> <li><code>The wallet</code> MUST fail if the destination address is <code>the deposit address format</code> and the <code>data</code> field is set to anything besides null.</li> <li><code>The wallet</code> MUST set the <code>to</code> field of the underlying transaction to the first 20 bytes of the deposit address format, and set the <code>data</code> field to <code>0x3ef8e69aNNNNNNNNNNNNNNNN000000000000000000000000000000000000000000000000</code> where <code>NNNNNNNNNNNNNNNN</code> is the last 8 bytes of the deposit address format. (ie. if the deposit address format is set to <code>0x433e064c42e87325fb6ffa9575a34862e0052f26913fd924f056cd15</code> then the <code>to</code> field is <code>0x433e064c42e87325fb6ffa9575a34862e0052f26</code> and the <code>data</code> field is <code>0x3ef8e69a913fd924f056cd15000000000000000000000000000000000000000000000000</code>)</li> </ul> <h2 id="rationale">Rationale</h2> <p>The contract interface and address format combination has one notable drawback, which was brought up in discussion. This ERC can only handle deposits for native value (ETH) and not other protocols such as ERC-20. However, this is not considered a problem, because it is best practice to logically AND key-wise separate wallets for separate currencies in any exchange/merchant application for accounting reasons and also for security reasons. Therefore, using this method for the native value currency (ETH) and another method for ERC-20 tokens etc. is acceptable. Any attempt at doing something similar for ERC-20 would require modifying the ERC itself (by adding the id data as a new input argument to the transfer method etc.) which would grow the scope of this ERC too large to manage. However, if this address format catches on, it would be trivial to add the bytes8 id to any updated protocols (though adoption might be tough due to network effects).</p> <p>The 8 byte size of the id and the checksum 3 : nonce 5 ratio were decided with the following considerations:</p> <ul> <li>24 bit checksum is better than the average 15 bit checksum of an EIP-55 address.</li> <li>40 bit nonce allows for over 1 trillion nonces.</li> <li>64 bit length of the id was chosen as to be long enough to support a decent checksum and plenty of nonces, but not be too long. (Staying under 256 bits makes hashing cheaper in gas costs as well.)</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>An address generated with the deposit address format will not be considered a valid address for applications that don't support it. If the user is technical enough, they can get around lack of support by verifying the checksum themselves, creating the needed data field by hand, and manually input the data field. (assuming the wallet app allows for arbitrary data input on transactions) A tool could be hosted on github for users to get the needed 20 byte address and msg.data field from a deposit address.</p> <p>Since a contract following this ERC will reject any plain value transactions, there is no risk of extracting the 20 byte address and sending to it without the calldata.</p> <p>However, this is a simple format, and easy to implement, so the author of this ERC will first implement in web3.js and encourage adoption with the major wallet applications.</p> <h2 id="test-cases">Test Cases</h2> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;address&quot;: &quot;0x083d6b05729c58289eb2d6d7c1bb1228d1e3f795&quot;,</span></span> <span class="giallo-l"><span> &quot;nonce&quot;: &quot;0xbdd769c69b&quot;,</span></span> <span class="giallo-l"><span> &quot;depositAddress&quot;: &quot;0x083d6b05729c58289eb2d6d7c1bb1228d1e3f795bdd769c69b3b97b9&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;address&quot;: &quot;0x433e064c42e87325fb6ffa9575a34862e0052f26&quot;,</span></span> <span class="giallo-l"><span> &quot;nonce&quot;: &quot;0x913fd924f0&quot;,</span></span> <span class="giallo-l"><span> &quot;depositAddress&quot;: &quot;0x433e064c42e87325fb6ffa9575a34862e0052f26913fd924f056cd15&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;address&quot;: &quot;0xbbc6597a834ef72570bfe5bb07030877c130e4be&quot;,</span></span> <span class="giallo-l"><span> &quot;nonce&quot;: &quot;0x2c8f5b3348&quot;,</span></span> <span class="giallo-l"><span> &quot;depositAddress&quot;: &quot;0xbbc6597a834ef72570bfe5bb07030877c130e4be2c8f5b3348023045&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;address&quot;: &quot;0x17627b07889cd22e9fae4c6abebb9a9ad0a904ee&quot;,</span></span> <span class="giallo-l"><span> &quot;nonce&quot;: &quot;0xe619dbb618&quot;,</span></span> <span class="giallo-l"><span> &quot;depositAddress&quot;: &quot;0x17627b07889cd22e9fae4c6abebb9a9ad0a904eee619dbb618732ef0&quot;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> &quot;address&quot;: &quot;0x492cdf7701d3ebeaab63b4c7c0e66947c3d20247&quot;,</span></span> <span class="giallo-l"><span> &quot;nonce&quot;: &quot;0x6808043984&quot;,</span></span> <span class="giallo-l"><span> &quot;depositAddress&quot;: &quot;0x492cdf7701d3ebeaab63b4c7c0e66947c3d202476808043984183dbe&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>A sample implementation with an example contract and address generation (in the tests) is located here:</p> <p>https://github.com/junderw/deposit-contract-poc</p> <h2 id="security-considerations">Security Considerations</h2> <p>In general, contracts that implement the contract interface should forward funds received to the deposit(bytes8) function to their cold wallet account. This address SHOULD be hard coded as a constant OR take advantage of the <code>immutable</code> keyword in solidity versions <code>&gt;=0.6.5</code>.</p> <p>To prevent problems with deposits being sent after the parent application is shut down, a contract SHOULD have a kill switch that will revert all calls to deposit(bytes8) rather than using <code>selfdestruct(address)</code> (since users who deposit will still succeed, since an external account will receive value regardless of the calldata, and essentially the self-destructed contract would become a black hole for any new deposits)</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-08-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Zhenyu Sunhttps://github.com/Ungigdu https://wg-eips.ritovision.com/3135/ <h2 id="simple-summary">Simple Summary</h2> <p>This standard defines a token which can be claimed only by token issuer with payer's signature.</p> <h2 id="abstract">Abstract</h2> <p>This EIP defines a set of additions to the default token standard such as ERC-20, that allows online/offline service providers establish micropayment channels with any number of users by signing and verifying messages about the consumption of token off chain. Using this mechanism will reduce interactions with blockchain to minimal for both participants, thus saving gas and improve performance.</p> <h2 id="motivation">Motivation</h2> <p>There are two main purposes of this EIP, one is to reduce interactions with blockchain, the second is to link Ethereum to real-world payment problems.</p> <p>Many small businesses want to build payment system based on blockchain but find it difficult. There are basically two ways:</p> <ol> <li>Directly pay with token. There are many wallet can receive and transfer token but transactions on Ethereum cost gas and take time to confirm.</li> <li>User lock token on payment smart contract and service provider use payment messages signed by user to release token, establishing a micropayment channel. The advantage is interactions with blockchain is reduced and the signing/verifying process is off-chain. But interact with payment contract needs service provider to build a DApp, which require resources many small businesses do not have. Even if they managed to build DApps, they are all different, not standardized. Also, user should have a wallet with DApp browser and has to learn how to use it.</li> </ol> <p>This EIP helps to standardize the interactions of micropayment system, and make it possible for wallet build a universal UI in the future.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Image</span><span class="z-comment"> url of this token or descriptive resources</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> iconUrl</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Issuer</span><span class="z-comment"> of this token. Only issuer can execute claim function</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> issuer</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Remove consumption from payer&#39;s deposite</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Check if msg.sender == issuer</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> from</span><span class="z-comment"> Payer&#39;s address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> consumption</span><span class="z-comment"> How many token is consumed in this epoch, specified</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> epoch</span><span class="z-comment"> Epoch increased by 1 after claim or withdraw, at the beginning of each epoch, consumption goes back to 0</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> signature</span><span class="z-comment"> Signature of payment message signed by payer</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> claim</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> consumption</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> epoch</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transferIssuer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newIssuer</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Move amount from payer&#39;s token balance to deposite balance to ensure payment is sufficient</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> deposit</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Give remaining deposite balance back to &quot;to&quot; account, act as &quot;refund&quot; function</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> In prepayment module, withdraw is executed from issuer account</span></span> <span class="giallo-l"><span class="z-comment"> * In lock-release module, withdraw is executed from user account</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> to</span><span class="z-comment"> the account receiving remaining deposite</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> amount</span><span class="z-comment"> how many token is returned</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> withdraw</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> depositBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> depositBalance</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> epoch</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Deposit</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amount</span></span> <span class="giallo-l"><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Withdraw</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amount</span></span> <span class="giallo-l"><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> TransferIssuer</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> oldIssuer</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newIssuer</span></span> <span class="giallo-l"><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Claim</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> epoch</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> consumption</span></span> <span class="giallo-l"><span>)</span><span>;</span></span> <span class="giallo-l"></span></code></pre><h3 id="signature">signature</h3> <p>the pseudo code generating an ECDSA signature:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>sign(keccak256(abi_encode(</span></span> <span class="giallo-l"><span> &quot;\x19Ethereum Signed Message:\n32&quot;, </span></span> <span class="giallo-l"><span> keccak256(abi_encode(</span></span> <span class="giallo-l"><span> token_address,</span></span> <span class="giallo-l"><span> payer_address,</span></span> <span class="giallo-l"><span> token_issuer,</span></span> <span class="giallo-l"><span> token_consumption, //calculated by user client</span></span> <span class="giallo-l"><span> epoch</span></span> <span class="giallo-l"><span> ))</span></span> <span class="giallo-l"><span> ))</span></span> <span class="giallo-l"><span>,private_key)</span></span> <span class="giallo-l"></span></code></pre><h3 id="verification-process">verification process</h3> <p>the verification contains check about both signature and token_consumption</p> <p>the pseudo code run by verification server is as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"></span> <span class="giallo-l"><span>serving_loop:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> for {</span></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * unpaied_consumption is calculated by provider</span></span> <span class="giallo-l"><span> * signed_consumption is claimable amount</span></span> <span class="giallo-l"><span> * tolerance allows payer &quot;owes&quot; provider to a certain degree</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> //getSignedConsumption returns amount that are already claimable </span></span> <span class="giallo-l"><span> if(unpaied_consumption &lt; signed_consumption + tolerance){</span></span> <span class="giallo-l"><span> informUser(&quot;user need charge&quot;, unpaied_consumption)</span></span> <span class="giallo-l"><span> interruptService() </span></span> <span class="giallo-l"><span> }else{</span></span> <span class="giallo-l"><span> isServing() || recoverService()</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>verification_loop:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> for {</span></span> <span class="giallo-l"><span> message = incomingMessage()</span></span> <span class="giallo-l"><span> if(recover_signer(message, signature) != payer_address){</span></span> <span class="giallo-l"><span> informUser(&quot;check signature failed&quot;, hash(message))</span></span> <span class="giallo-l"><span> continue</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * optional: when using echo server to sync messages between verification servers</span></span> <span class="giallo-l"><span> * more info about this in Security Considerations section</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> if(query(message) != message){</span></span> <span class="giallo-l"><span> informUser(&quot;message outdate&quot;, hash(message))</span></span> <span class="giallo-l"><span> continue </span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if(epoch != message.epoch || message.consumption &gt; getDepositBalance()){</span></span> <span class="giallo-l"><span> informUser(&quot;invalid message&quot;, epoch, unpaied_consumption)</span></span> <span class="giallo-l"><span> continue</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> signed_consumption = message.consumption</span></span> <span class="giallo-l"><span> save(message)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span>claim_process:</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if(claim()){</span></span> <span class="giallo-l"><span> unpaied_consumption -= signed_consumption</span></span> <span class="giallo-l"><span> signed_consumption = 0</span></span> <span class="giallo-l"><span> epoch+=1</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span></code></pre><h3 id="about-withdraw">About withdraw</h3> <p>The withdraw function is slightly different based on business models</p> <ol> <li>prepayment model</li> </ol> <p>In prepayment business model such as using token as recharge card of general store, the user pays (crypto)currency to store in advance for claimable token as recharge card (with bonus or discount). When checking out, the customer signs a message with updated consumption (old consumption + consumption this time) to store and store verifies this message off chain. The shopping process loops without any blockchain involved, until the customer wants to return the card and get money back. Because the store already holds all currency, the withdraw function should be executed by token issuer (store) to return remaining deposit balance after claim. The prepayment model can easily be built into a wallet with QR-code scanning function.</p> <ol start="2"> <li>lock-release model</li> </ol> <p>If we run a paid end-to-end encrypted e-mail service that accepts token as payment, we can use lock-release model. Unlike prepayment, we charge X * N token for an e-mail sent to N recipients. In this "pay for usage" scenario, the counting of services happens on both client and server side. The client should not trust charge amount given by server in case the it's malfunctioning or malicious. When client decide not to trust server, it stops signing messages, but some of token is taken hostage in deposit balance. To fix this problem, the withdraw function should be executed by payer account with limitation such as epoch didn't change in a month.</p> <h2 id="rationale">Rationale</h2> <p>This EIP targets on ERC-20 tokens due to its widespread adoption. However, this extension is designed to be compatible with other token standard.</p> <p>The reason we chose to implement those functions in token contract rather than a separate record contract is as follows:</p> <ul> <li>Token can transfer is more convenient and more general than interact with DApp</li> <li>Token is more standardized and has better UI support</li> <li>Token is equal to service, make token economy more prosperous</li> <li>Remove the approve process</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible as its implementation extends the functionality of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <h2 id="implementation">Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">mapping</span><span> (</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span> StampBalance</span><span>)</span><span class="z-storage z-type"> private</span><span> _depositBalance</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> StampBalance</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> balance</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> epoch</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> deposit</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> override</span><span class="z-storage z-type"> external</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>value </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> _balances</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span> _balances</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span class="z-entity z-name">sub</span><span>(</span><span>value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _depositBalance</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>balance </span><span class="z-keyword">=</span><span> _depositBalance</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>.</span><span>balance</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span>value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Deposit</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> withdraw</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> onlyIssuer</span><span class="z-storage z-type"> external</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>value </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> _depositBalance</span><span>[</span><span>to</span><span>]</span><span>.</span><span>balance</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _depositBalance</span><span>[</span><span>to</span><span>]</span><span>.</span><span>balance </span><span class="z-keyword">=</span><span> _depositBalance</span><span>[</span><span>to</span><span>]</span><span>.</span><span>balance</span><span>.</span><span class="z-entity z-name">sub</span><span>(</span><span>value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _depositBalance</span><span>[</span><span>to</span><span>]</span><span>.</span><span>epoch </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span>to</span><span>]</span><span class="z-keyword"> =</span><span> _balances</span><span>[</span><span>to</span><span>]</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span>value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Withdraw</span><span>(</span><span>to</span><span>,</span><span> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> depositBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span class="z-storage z-type"> override</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> depositBalance</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> epoch</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>_depositBalance</span><span>[</span><span>user</span><span>]</span><span>.</span><span>balance</span><span>,</span><span> _depositBalance</span><span>[</span><span>user</span><span>]</span><span>.</span><span>epoch</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> prepayment model</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> claim</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> credit</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> epoch</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> override</span><span class="z-entity z-name"> onlyIssuer</span><span class="z-storage z-type"> external</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>credit </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_depositBalance</span><span>[</span><span>from</span><span>]</span><span>.</span><span>epoch </span><span class="z-keyword">+</span><span class="z-constant"> 1</span><span class="z-keyword"> ==</span><span> epoch</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>_depositBalance</span><span>[</span><span>from</span><span>]</span><span>.</span><span>balance </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> credit</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> message </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span> from</span><span>,</span><span> _issuer</span><span>,</span><span> credit</span><span>,</span><span> epoch</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> msgHash </span><span class="z-keyword">=</span><span class="z-entity z-name"> prefixed</span><span>(</span><span>message</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">recoverSigner</span><span>(</span><span>msgHash</span><span>,</span><span> signature</span><span>)</span><span class="z-keyword"> ==</span><span> from</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _depositBalance</span><span>[</span><span>from</span><span>]</span><span>.</span><span>balance </span><span class="z-keyword">=</span><span> _depositBalance</span><span>[</span><span>from</span><span>]</span><span>.</span><span>balance</span><span>.</span><span class="z-entity z-name">sub</span><span>(</span><span>credit</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _balances</span><span>[</span><span>_issuer</span><span>]</span><span class="z-keyword"> =</span><span> _balances</span><span>[</span><span>_issuer</span><span>]</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span>credit</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _depositBalance</span><span>[</span><span>from</span><span>]</span><span>.</span><span>epoch </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Claim</span><span>(</span><span>from</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> credit</span><span>,</span><span> epoch</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> prefixed</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> hash</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encode</span><span>(</span><span class="z-string">&quot;\x19Ethereum Signed Message:\n32&quot;</span><span>,</span><span> hash</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> recoverSigner</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> message</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sig</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> (</span><span class="z-support">uint8</span><span> v</span><span>,</span><span class="z-support"> bytes32</span><span> r</span><span>,</span><span class="z-support"> bytes32</span><span> s</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> splitSignature</span><span>(</span><span>sig</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> ecrecover</span><span>(</span><span>message</span><span>,</span><span> v</span><span>,</span><span> r</span><span>,</span><span> s</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> splitSignature</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> sig</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>sig</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 65</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> r </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>sig</span><span>,</span><span class="z-constant"> 32</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> s </span><span class="z-keyword">:=</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>sig</span><span>,</span><span class="z-constant"> 64</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> v </span><span class="z-keyword">:=</span><span class="z-entity z-name"> byte</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span class="z-entity z-name">add</span><span>(</span><span>sig</span><span>,</span><span class="z-constant"> 96</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>v</span><span>,</span><span> r</span><span>,</span><span> s</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>By restricting claim function to issuer, there is no race condition on chain layer. However double spending problem may occur when the issuer use multiple verifiers and payer signs many payment messages simultaneously. Some of those messages may get chance to be checked valid though only the message with the largest consumption can be claimed. This problem can be fixed by introducing an echo server which accepts messages from verifiers, returns the message sequentially with largest consumption and biggest epoch number. If a verifier gets an answer different from the message he send, it updates the message from echo server as the last message it receives along with local storage of the status about this payer. Then the verifier asks the payer again for a new message.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-08-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Giuseppe Bertonehttps://github.com/Neurone https://wg-eips.ritovision.com/2848/ <h2 id="simple-summary">Simple Summary</h2> <p>My Own Messages (MOM) is a standard to create your very own public, always updated, unstoppable, verifiable, message board.</p> <h2 id="abstract">Abstract</h2> <p>My Own Messages (MOM) use Ethereum as a certification layer for commands and multihash of your messages. It don't use smart contracts but simple self-send transactions with specific payload attached.</p> <p>To ge more insights, you can test a <a rel="external" href="http://internetofpeers.org/mom-client/">live client</a>, watch a <a rel="external" href="https://www.youtube.com/watch?v=z1SnoQkQYkU">full video overview and demo</a> and read a <a href="https://wg-eips.ritovision.com/2848/./assets/presentation.pdf">brief presentation</a>.</p> <h2 id="motivation">Motivation</h2> <p>As a <em>developer</em> or <em>pool's owner</em>, I'd like to send messages to my users in a decentralized way. They must be able to easily verify my role in the smart contract context (owner, user, and so on) and they must be able to do it without relying on external, insecure and hackable social media sites (Facebook, Twitter, you name it). Also, I'd like to read messages from my userbase, in the same secure and verifiable manner.</p> <p>As a <em>user</em>, I want a method to easily share my thoughts and idea, publish content, send messages, receive feedback, receive tips, and so on, without dealing with any complexity: just write a message, send it and it's done. Also, I want to write to some smart contract's owner or to the sender of some transaction.</p> <p>As an <em>explorer service</em>, I want to give my users an effective way to read information by smart contract owners and a place to share ideas and information without using third party services (i.e. Etherscan uses Disqus, and so on)</p> <p>And in <em>any role</em>, I want a method that does not allow scams - transactions without values, no smart contract's address to remember or to fake - and it does not allow spam - it's cheap but not free, and even if you can link/refer other accounts, you cannot send them messages directly, and others must explicitly follow and listen to your transactions if they want to read your messages.</p> <p>Main advantages:</p> <ul> <li>You can send messages to users of your ÐApp or Smart Contract, and they always know it is a voice reliable as the smart contract is.</li> <li>Create your Ethereum account dedicated to your personal messages, say something only once and it can be seen on every social platform (no more reply of the same post/opinion on dozens of sites like Reddit, Twitter, Facebook, Medium, Disqus, and so on...)</li> <li>Small fee to be free: pay just few cents of dollar to notarize your messages, and distribute them with IPFS, Swarm or any other storage you prefer. Because the multihash of the content is notarized, you can always check the integrity of the message you download even from centralized storage services.</li> <li>Finally, you can ask and get tips for your words directly into your wallet.</li> </ul> <p>I know, My Own Messages (MOM) sounds like <em>mom</em>. And yes, pun intended :)</p> <h2 id="specification">Specification</h2> <p>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 <a rel="external" href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119</a> when, and only when, they appear in all capitals as shown here.</p> <p>Clients following MOM standard <strong>MUST</strong> allow users to send and to read MOM transaction, creating an <em>updated message list</em> for each address the users are interested in.</p> <p>Reading MOM transactions, MOM clients <strong>MUST</strong> be able to show the current and updated message list, and they <strong>SHOULD</strong> be able to show also all the message history if users ask for it.</p> <p>Apart from message list, MOM clients <strong>SHOULD</strong> be able to download the content of the messages and to show them to the user.</p> <p>Clients <strong>SHOULD</strong> allow users to choose and set the source to download content from, and they <strong>SHOULD</strong> be able to use common Content Addressable Networks - i.e. IPFS or Swarm - or HTTP servers. If content is downloaded from HTTP servers, clients <strong>MUST</strong> check the content against the declared multihash.</p> <p>As the default setting, clients <strong>MUST</strong> consider <code>text/markdown</code> (<a rel="external" href="https://www.ietf.org/rfc/rfc7763.txt">RFC 7763</a>) as the media type of the content represented by a multihash, and in particular <a rel="external" href="https://en.wikipedia.org/wiki/Markdown">Markdown</a> text in <a rel="external" href="https://en.wikipedia.org/wiki/UTF-8">UTF-8</a> without <a rel="external" href="https://en.wikipedia.org/wiki/Byte_order_mark">BOM</a>.</p> <p>Clients <strong>MAY</strong> let users choose to parse messages considering other content types. In this case they <strong>SHOULD</strong> cast a warning to users stating that a content type other than <code>text/markdown</code> is used while processing messages.</p> <p>It's <strong>RECOMMENDED</strong> that clients inform users about the actual setting of the default content type.</p> <h3 id="mom-transactions">MOM transactions</h3> <p>Clients <strong>MUST</strong> assume that <strong>invalid MOM transactions don't exist</strong>. If a transaction does not strictly follow the MOM standard, clients <strong>MUST</strong> ignore it and they <strong>MUST NOT</strong> consider it a MOM transaction at all.</p> <p>Because there can be security implications parsing data sent by users, clients <strong>SHOULD NOT</strong> try to keep track or interpret transactions as <em>invalid</em> MOM transactions.</p> <h4 id="valid-mom-transaction-s-data-structure">Valid MOM transaction's data structure</h4> <table><thead><tr><th style="text-align: left">ATTRIBUTE</th><th style="text-align: left">VALUE</th></tr></thead><tbody> <tr><td style="text-align: left"><code>to</code></td><td style="text-align: left"><strong>MUST</strong> be the same account signing the transaction.</td></tr> <tr><td style="text-align: left"><code>value</code></td><td style="text-align: left"><strong>MUST</strong> be <code>0</code> wei.</td></tr> <tr><td style="text-align: left"><code>data</code></td><td style="text-align: left"><strong>MUST</strong> be at least <code>2</code> bytes. The first byte <strong>MUST</strong> be operational code and following bytes <strong>MUST</strong> be based on the operational codes listed below.</td></tr> </tbody></table> <h4 id="list-of-supported-operations-and-messages">List of supported operations and messages</h4> <p>Each operational code has one or more parameters, and all parameters <strong>MUST</strong> be considered mandatory.</p> <p>Optional parameters don't exist: if parameters for the specific operational code are not all present or they don't follow the rules, clients <strong>MUST</strong> ignore the transaction completely.</p> <p>Messages <strong>MUST</strong> be always referenced with the multihash of their content.</p> <p>Operations are divided into two sets: <strong>CORE</strong> and <strong>EXTENDED</strong> operations.</p> <ul> <li>Clients <strong>MUST</strong> support all core operations and they <strong>SHOULD</strong> support as much extended operations as possible.</li> <li>Clients <strong>SHOULD</strong> support and implement as much extended operations as possible, but they <strong>MAY</strong> choose to implement only some specific extended operations they are interested in.</li> </ul> <h4 id="core-operations">Core operations</h4> <table><thead><tr><th>OPERATION</th><th style="text-align: center">CODE</th><th>PARAMETERS</th><th>MEANING</th><th>EFFECT</th></tr></thead><tbody> <tr><td>ADD</td><td style="text-align: center"><code>0x00</code></td><td>multihash</td><td>Add a message. The parameter <strong>MUST</strong> be the multihash of the message.</td><td>Clients <strong>MUST</strong> add the message to the message list of the sender.</td></tr> <tr><td>UPDATE</td><td style="text-align: center"><code>0x01</code></td><td>multihash, multihash</td><td>Update a message. The first parameter <strong>MUST</strong> be the multihash of the message to be updated. The second parameter <strong>MUST</strong> be the multihash of the updated message.</td><td>Clients <strong>MUST</strong> update the message list to show the updated message.</td></tr> <tr><td>REPLY</td><td style="text-align: center"><code>0x02</code></td><td>multihash, multihash</td><td>Reply to a message. The first parameter <strong>MUST</strong> be the multihash of the message to reply to. The second parameter <strong>MUST</strong> the multihash of the message.</td><td>Clients <strong>MUST</strong> insert a new message in the message list and they <strong>MUST</strong> preserve the relationship with the referenced message.</td></tr> <tr><td>DELETE</td><td style="text-align: center"><code>0x03</code></td><td>multihash</td><td>Delete a message. The parameter <strong>MUST</strong> be the multihash of the message to delete.</td><td>Clients <strong>MUST</strong> remove the message from the message list.</td></tr> <tr><td>CLOSE ACCOUNT</td><td style="text-align: center"><code>0xFD</code></td><td>multihash</td><td>Close an account. The parameter <strong>MUST</strong> be the multihash of the message with the motivations for closing the account.</td><td>Clients <strong>MUST</strong> add the message with motivations to the message list and they <strong>MUST NOT</strong> consider MOM messages sent by that address to be valid anymore, ever. In other words, MOM clients <strong>MUST</strong> ignore any other transaction sent by that address while creating the message list. This is useful when users want to change account, for example because the private key seems compromised.</td></tr> <tr><td>RAW</td><td style="text-align: center"><code>0xFF</code></td><td>any</td><td>The parameter <strong>MUST</strong> be at least <code>1</code> byte. Content type is not disclosed and it <strong>MUST NOT</strong> be considered as <code>text/markdown</code>.</td><td>Clients <strong>MUST</strong> add the message to the message list but they <strong>MUST NOT</strong> try to decode the content. Clients <strong>SHOULD</strong> allow users to see this message only if explicitly asked for. This operation can be used for <em>blind</em> notarization that general client can ignore.</td></tr> </tbody></table> <h4 id="note-about-delete-operational-code">Note about <code>DELETE</code> operational code</h4> <p>Please note that sending a <code>DELETE</code> command users are not asking to actually delete anything from the blockchain, they are just asking clients to hide that specific message because it's not valid anymore for some reasons. You can think of it like if users say: <em>I changed my mind so please ÐApps don't show this anymore</em>. As already stated in the specifications above, clients <strong>MUST</strong> follow this request by the author, unless expressly asked otherwise by the user.</p> <p>Please also note that, because it's usually up to the author of a message to be sure the content is available to everyone, if a <code>DELETE</code> message was sent it's very likely the content referenced by the multihash isn't available anymore, simply because probably it's not shared by anyone.</p> <h4 id="extended-operations">Extended operations</h4> <table><thead><tr><th>OPERATION</th><th style="text-align: center">CODE</th><th>PARAMETERS</th><th>MEANING</th><th>EFFECT</th></tr></thead><tbody> <tr><td>ADD &amp; REFER</td><td style="text-align: center"><code>0x04</code></td><td>multihash, address</td><td>Add a message and refer an account. The first parameter <strong>MUST</strong> be the multihash of the message. The second parameter <strong>MUST</strong> be an address referenced by the message.</td><td>Clients <strong>MUST</strong> add the message to the message list and they <strong>MUST</strong> track the reference to the specified account. This can be useful <em>to invite</em> the owner of the referenced account to read this specific message.</td></tr> <tr><td>UPDATE &amp; REFER</td><td style="text-align: center"><code>0x05</code></td><td>multihash, multihash, address</td><td>Update a message. The first parameter <strong>MUST</strong> be the multihash of the message to be updated. The second parameter <strong>MUST</strong> be the multihash of the updated message. The third parameter <strong>MUST</strong> be an address referenced by the message.</td><td>Clients <strong>MUST</strong> update the message list to show the updated message and they <strong>MUST</strong> track the reference to the specified account. This can be useful <em>to invite</em> the owner of the referenced account to read this specific message.</td></tr> <tr><td>ENDORSE</td><td style="text-align: center"><code>0x06</code></td><td>multihash</td><td>Endorse a message identified by the specified multihash. The parameter <strong>MUST</strong> be the multihash of the message to be endorsed.</td><td>Clients <strong>MUST</strong> record and track the endorsement for that specific message. Think it as a <em>like</em>, a <em>retwitt</em>, etc.</td></tr> <tr><td>REMOVE ENDORSEMENT</td><td style="text-align: center"><code>0x07</code></td><td>multihash</td><td>Remove endorsement to the message identified by the specified multihash. The parameter <strong>MUST</strong> be the multihash of the message.</td><td>Clients <strong>MUST</strong> remove the endorsement for that specific message.</td></tr> <tr><td>DISAPPROVE</td><td style="text-align: center"><code>0x08</code></td><td>multihash</td><td>Disapprove a message identified by the specified multihash. The parameter <strong>MUST</strong> be the multihash of the message to disapprove.</td><td>Clients <strong>MUST</strong> record and track the disapproval for that specific message. Think it as a <em>I don't like it</em>.</td></tr> <tr><td>REMOVE DISAPPROVAL</td><td style="text-align: center"><code>0x09</code></td><td>multihash</td><td>Remove disapproval of a message identified by the specified multihash. The parameter <strong>MUST</strong> be the multihash of the message.</td><td>Clients <strong>MUST</strong> remove the disapproval for that specific message.</td></tr> <tr><td>ENDORSE &amp; REPLY</td><td style="text-align: center"><code>0x0A</code></td><td>multihash, multihash</td><td>Endorse a message and reply to it. The first parameter <strong>MUST</strong> be the multihash of the message to reply to. The second parameter <strong>MUST</strong> be the multihash of the message.</td><td>Clients <strong>MUST</strong> insert a new message in the message list and they <strong>MUST</strong> preserve the relationship with the referenced message. Clients <strong>MUST</strong> also record and track the endorsement for that specific message.</td></tr> <tr><td>DISAPPROVE &amp; REPLY</td><td style="text-align: center"><code>0x0B</code></td><td>multihash, multihash</td><td>Disapprove a message and reply to it. The first parameter <strong>MUST</strong> be the multihash of the message to reply to. The second parameter <strong>MUST</strong> be the multihash of the message.</td><td>Clients <strong>MUST</strong> insert a new message in the message list and they <strong>MUST</strong> preserve the relationship with the referenced message. Clients <strong>MUST</strong> also record and track the disapproval for that specific message.</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>Ethereum is <em>account based</em>, so it's good to be identified as a single source of information.</p> <p>It is also able of doing notarization very well and to impose some restrictions on transaction's structure, so it's good for commands.</p> <p>IPFS, Swarm or other CANs (Content Addressable Networks) or storage methods are good to store a lot of information. So, the union of both worlds it's a good solution to achieve the objectives of this message standard.</p> <p>The objective is also to avoid in the first place any kind of scam and malicious behaviors, so MOM don't allow to send transactions to other accounts and the value of a MOM transaction is always 0.</p> <h3 id="why-not-using-a-smart-contract">Why not using a smart contract?</h3> <p>MOM wants to be useful, easy to implement and read, error proof, fast and cheap, but:</p> <ul> <li>using a smart contract for messages can leads more easily to errors and misunderstandings: <ul> <li>address of the contract can be wrong</li> <li>smart contract must be deployed on that specific network to send messages</li> </ul> </li> <li>executing a smart contract costs much more than sending transactions</li> <li>executing a smart contract just to store static data is the best example of an anti-pattern (expensive and almost useless)</li> </ul> <p>Without a specific smart contract to rely on, the MOM standard can be implemented and used right now in any existing networks, and even in future ones.</p> <p>Finally, if you can achieve exactly the same result without a smart contract, you didn't need a smart contract at the first place.</p> <h3 id="why-not-storing-messages-directly-on-chain">Why not storing messages directly on-chain?</h3> <p>There's no benefit to store <em>static</em> messages on-chain, if they are not related to some smart contract's state or if they don't represent exchange of value. The cost of storing data on-chain is also very high.</p> <h3 id="why-not-storing-op-codes-inside-the-message">Why not storing op codes inside the message?</h3> <p>While cost effectiveness is a very important feature in a blockchain related standard, there's also a compromise to reach with usability and usefulness.</p> <p>Storing commands inside the messages forces the client to actually download messages to understand what to do with them. This is very inefficient, bandwidth and time consuming.</p> <p>Being able to see the commands before downloading the content, it allows the client to recreate the history of all messages and then, at the end, download only updated messages.</p> <p>Creating a structure for the content of the messages leads to many issues and considerations in parsing the content, if it's correct, misspelled, and so on.</p> <p>Finally, the <strong>content must remain clean</strong>. You really want to notarize the content and not to refer to a data structure, because this can lead to possible false-negative when checking if a content is the same of another.</p> <h3 id="why-multihash">Why multihash?</h3> <p><a rel="external" href="https://github.com/multiformats/multihash">Multihash</a> is flexible, future-proof and there are already tons of library supporting it. Ethereum must be easily integrable with many different platforms and architectures, so MOM standard follows that idea.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>You can already find few transactions over the Ethereum network that use a pattern similar to this EIP. Sometimes it's done to invalidate a previous transaction in memory pool, using the same nonce but with more gas price, so that transaction is mined cancelling the previous one still in the memory pool. This kind of transactions can be easily ignored if created before the approval of this EIP or just checking if the payload follows the correct syntax.</p> <h2 id="test-cases">Test Cases</h2> <p>A MOM-compliant client can be found and tested on <a rel="external" href="https://github.com/InternetOfPeers/mom-client">GitHub</a>.</p> <p>You can use the latest version of MOM client directly via <a rel="external" href="https://internetofpeers.github.io/mom-client">GitHub Pages</a> or via IPFS (see the <a rel="external" href="https://github.com/InternetOfPeers/mom-client">client repo</a> for the latest updated address).</p> <h2 id="implementation">Implementation</h2> <p>You can use an already working MOM JavaScript package on <a rel="external" href="https://github.com/InternetOfPeers/mom-js/packages/323930">GitHub Packages</a> or <a rel="external" href="https://www.npmjs.com/package/@internetofpeers/mom-js">npmjs</a>. The package is already used by the MOM client above, and you can use it in your ÐApps too with:</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">npm</span><span class="z-string"> install</span><span class="z-string"> @internetofpeers/mom-js</span></span></code></pre> <p>Transaction <a rel="external" href="https://etherscan.io/tx/0x8e49485c56897757a6f2707b92cd5dad06126afed92261b9fe1a19b110bc34e6"><code>0x8e49485c56897757a6f2707b92cd5dad06126afed92261b9fe1a19b110bc34e6</code></a> is an example of a valid MOM transaction already mined on the Main net; it's an <code>ADD</code> message.</p> <h2 id="security-considerations">Security Considerations</h2> <p>MOM is very simple and it has no real security concerns by itself. The standard already considers valid only transactions with <code>0</code> value and where <code>from</code> and <code>to</code> addresses are equals.</p> <p>The only concerns can come from the payload, but it is more related to the client and not to the standard itself, so here you can find some security suggestions related to clients implementing the standard.</p> <h3 id="parsing-commands">Parsing commands</h3> <p>MOM standard involves parsing payloads generated by potentially malicious clients, so attention must be made to avoid unwanted code execution.</p> <ul> <li>Strictly follow only the standard codes</li> <li>Don't execute any commands outside of the standard ones, unless expressly acknowledged by the user</li> <li>Ignore malformed transactions (transactions that don't strictly follow the rules)</li> </ul> <h3 id="messages">Messages</h3> <p>Default content-type of a message following the MOM standard is Markdown text in UTF8 without BOM. It is highly recommended to disallow the reading of any not-text content-type, unless expressly acknowledged by the user.</p> <p>Because content multihash is always stored into the chain, clients can download that content from Content Addressable Network (like IPFS or Swarm) or from central servers. In the latter case, a client should always check the integrity of the received messages, or it must warn the user if it cannot do that (feature not implemented or in error).</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-08-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Joel Thorstenssonhttps://github.com/oed https://wg-eips.ritovision.com/2844/ <h2 id="simple-summary">Simple Summary</h2> <p>Add new methods to the JSON-RPC for signing and decrypting JOSE objects under a new <code>did_*</code> prefix.</p> <h2 id="abstract">Abstract</h2> <p>This EIP describes three new methods to add to the JSON-RPC that enables wallets to support <em>Decentralized Identifiers</em> (DIDs) as well as <em>JSON Object Signing and Encryption</em> (JOSE). These standards enables wallets to support data decryption as well as authenticated data, both in standard formats using JOSE. With these new methods apps can request the DID from a users wallet, from which a DID document can be resolved. The DID document contains public keys that can be used for encryption and signature verification. This enables Alice to discover Bobs public keys by only knowing Bobs DID. This EIP does not enforce the user of any particular DID method or JOSE algorithms, wallets are free to implement these however they wish.</p> <h2 id="motivation">Motivation</h2> <p>There has been one main previous effort (<a rel="external" href="https://github.com/ethereum/EIPs/issues/130">#130</a>, <a rel="external" href="https://github.com/ethereum/EIPs/pull/1098">#1098</a>) to add decryption to Ethereum wallets in a standard way. This previous approach used a non standard way to encode and represent data encrypted using <code>x25519-xsalsa20-poly1305</code>. While this approach does provide a functional way to add encryption support to wallets, it does not take into account similar work that has gone into standardizing the way encrypted data is represented, namely using <a rel="external" href="https://datatracker.ietf.org/wg/jose/documents/">JOSE</a>. This is a standard from IETF for representing signed and encrypted objects. Another shortcoming of the previous approach is that it's impossible to retrieve the <code>x25519</code> public key from another user if only an Ethereum address is known. Public key discoverability is at the core of the work that is happening with the <a rel="external" href="https://w3c.github.io/did-core">W3C DID standard</a>, where given a DID a document which contains public keys can always be discovered. Implementations of this standard already exist and are adopted within the Ethereum community, e.g. <a rel="external" href="https://github.com/decentralized-identity/ethr-did-resolver/"><code>did:ethr</code></a> and <a rel="external" href="https://github.com/3box/3id-resolver"><code>did:3</code></a>. Interoperability between JOSE and DIDs <a rel="external" href="https://github.com/decentralized-identity/did-jwt">already exists</a>, and work is being done to <a rel="external" href="https://github.com/decentralized-identity/did-jose-extensions">strengthen it</a>. Adding support for JOSE and DIDs will enable Ethereum wallets to support a wide range of new use cases such as more traditional authentication using JWTs, as well as new emerging technologies such as <a rel="external" href="https://identity.foundation/secure-data-store/">Secure Data Stores</a> and <a rel="external" href="https://github.com/ipld/specs/pull/269">encrypted data in IPFS</a>.</p> <h2 id="specification">Specification</h2> <p>Three new JSON-RPC methods are specified under the new <code>did_*</code> prefix.</p> <h3 id="auth">Auth</h3> <p>Authenticate the current rpc connection to the DID methods.</p> <p>Prompt the user to give permission to the current connection to access the user DID and the given <code>paths</code>.</p> <h5 id="method">Method:</h5> <p><code>did_authenticate</code></p> <h5 id="params">Params:</h5> <ul> <li><code>nonce</code> - a random string used as a challenge</li> <li><code>aud</code> - the intended audience of the authentication response</li> <li><code>paths</code> - an array of strings</li> </ul> <h5 id="returns">Returns:</h5> <p>A JWS with general serialization containing the following properties:</p> <ul> <li> <p><code>nonce </code> - the random string which was given as a challenge</p> </li> <li> <p><code>did</code> - the DID which authentication was given for</p> </li> <li> <p><code>paths</code> - the paths which was given permission for</p> </li> <li> <p><code>exp</code> - a unix timestamp after which the JWS should be considered invalid</p> </li> <li> <p><code>aud</code> - optional audience for the JWS, should match the domain which made the request</p> </li> </ul> <p>An additional property <code>kid</code> with the value which represents the DID, and the <code>keyFragment</code> that was used to sign the JWS should be added to the protected header (<a rel="external" href="https://github.com/decentralized-identity/did-jose-extensions/issues/2">details</a>).</p> <h4 id="createjws">CreateJWS</h4> <p>Creates a JSON Web Signature (JWS).</p> <p>An additional property <code>kid</code> with the value which represents the DID, and the <code>keyFragment</code> that was used to sign the JWS should be added to the protected header (<a rel="external" href="https://github.com/decentralized-identity/did-jose-extensions/issues/2">details</a>). When <code>revocable</code> is set to false the JWS signature should not be possible to revoke. For some DID methods like. <code>did:key</code> this is always the case. For other methods which support key revocation it is necessary to include the <code>version-id</code> in the <code>kid</code> to refer to a specific version of the DID document. When <code>revocable</code> is set to true <code>version-id</code> must not be included in the <code>kid</code> for DID methods that support key revocation.</p> <h5 id="method-1">Method:</h5> <p><code>did_createJWS</code></p> <h5 id="params-1">Params:</h5> <ul> <li><code>payload</code> - the payload to sign, json object or <code>base64url</code> encoded string</li> <li><code>protected</code> - the protected header, json object</li> <li><code>did</code> - the DID that should sign the message, may include the key fragment, string</li> <li><code>revocable</code> - makes the JWS revocable when rotating keys, boolean default to <code>false</code></li> </ul> <h5 id="returns-1">Returns:</h5> <p>An object containing a JWS with general serialization on the <code>jws</code> property.</p> <h5 id="recommendation">Recommendation:</h5> <p>Use <code>secp256k1</code> for signing, alternatively <code>ed25519</code>.</p> <h4 id="decryptjwe">DecryptJWE</h4> <p>Decrypt the given JWE.</p> <p>If the cleartext object contains a property <code>paths</code> that contains an array of strings and one of the paths in there are already authenticated using <code>did_authenticate</code> the decryption should happen without user confirmation.</p> <h5 id="method-2">Method:</h5> <p><code>did_decryptJWE</code></p> <h5 id="params-2">Params:</h5> <ul> <li><code>jwe</code> - a JWE with general serialization, string</li> <li><code>did</code> - the DID that should try to decrypt the JWE, string</li> </ul> <h5 id="returns-2">Returns:</h5> <p>An object containing the cleartext, encoded using <a rel="external" href="https://github.com/multiformats/multibase"><code>base64pad</code></a>, assigned to the <code>cleartext</code> property.</p> <h5 id="recommendation-1">Recommendation:</h5> <p>Implement decryption using <code>xchacha20poly1305</code> and <code>x25519</code> for key agreement.</p> <h2 id="rationale">Rationale</h2> <p>This EIP chooses to rely on DIDs and JOSE since there is already support for these standards in many places, by current systems and new systems. By using DIDs and JOSE wallet implementers can also choose which signing and encryption algorithms that they want to support, since these formats are fairly agnostic to specific crypto implementations.</p> <h3 id="permission-system">Permission system</h3> <p>A simple permission system is proposed where clients can request permissions though path prefixes, e.g. <code>/some/permission</code>. When decryption of a JWE is requested the wallet should check if the decrypted payload contains a <code>paths</code> property. If this property doesn't exist the user may be prompted to confirm that the given rpc connection (app) is allowed to read the decrypted data. If the <code>paths</code> property is present in the decrypted data it should contain an array of string paths. If one of the these path prefixes matches with one of the path prefixes the user has already granted permission for then decryption should happen automatically without any user confirmation.</p> <p>This simple permission system was inspired by some previous comments (<a rel="external" href="https://github.com/ethereum/EIPs/issues/130#issuecomment-329770999">1</a>, <a rel="external" href="https://medium.com/@wighawag/3-proposals-for-making-web3-a-better-experience-974f97765700">2</a>) but avoids data lock in around origins.</p> <h2 id="implementation">Implementation</h2> <p><a rel="external" href="https://github.com/3box/identity-wallet-js/">IdentityWallet</a>: An implementation of the wallet side <code>did_*</code> methods using the 3ID DID.</p> <p><a rel="external" href="https://github.com/ceramicnetwork/key-did-provider-ed25519">key-did-provider-ed25519</a>: An implementation of the wallet side <code>did_*</code> methods using the <code>did:key</code> method.</p> <p><a rel="external" href="https://github.com/ceramicnetwork/js-did">js-did</a>: A small library which consumes the <code>did_*</code> methods.</p> <p><a rel="external" href="https://github.com/digitalbazaar/minimal-cipher">MinimalCipher</a>: An implementation of DID related encryption for JWE.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Both JOSE and DIDs are standards that have gone though a lot of scrutiny. Their security will not be considered in this document. In the specification section, recommendations are given for which algorithms to use. For signatures <code>secp256k1</code> is already used by ethereum and for decryption <code>xchacha20poly1305</code> is widely available, very performant, and already used in TLS.</p> <p>The main security consideration of this EIP is the suggested permission system. Here various threat models could be considered. However, this EIP does not go into details about how it should work other than suggesting an approach. In the end it is up to wallet implementations to choose how to ask their users for consent.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-07-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gregory Markouhttps://github.com/GregTheGreek https://wg-eips.ritovision.com/2831/ <h2 id="summary">Summary</h2> <p>An extension to the JavaScript Ethereum Provider API (<a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a>) this creates a new message type in the event a transaction replacement occurs.</p> <h2 id="abstract">Abstract</h2> <p>The current communication between providers and consumers of providers are fundamentally broken in the event that a transaction in the mempool has been superseded by a newer transactions. Providers currently have no way of communicating a transaction replacement, and consumers are required to poll block by block for the resulting transaction.</p> <h2 id="motivation">Motivation</h2> <p>Exert from EIP-1193</p> <blockquote> <p>A common convention in the Ethereum web application ("dapp") ecosystem is for key management software ("wallets") to expose their API via a JavaScript object in the web page. This object is called "the Provider".</p> </blockquote> <p>Many ingenious developments have been made by wallet developers to improve the overall user experience while interacting with the Ethereum blockchain. One specific innovation was transaction replacement, offering users the ability to effectively cancel a previously sent transaction.</p> <p>Transaction replacement is not a new concept, but unfortunately causes major user experience problems for dapp developers as the replaced transaction is near impossible to track.</p> <p>This EIP formalizes a way for both providers and dapp developers to track transaction replacements seamlessly.</p> <h2 id="specification">Specification</h2> <p>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 <a rel="external" href="https://www.ietf.org/rfc/rfc2119.txt">RFC-2119</a>.</p> <h3 id="definitions">Definitions</h3> <p><em>This section is non-normative.</em></p> <ul> <li>Provider <ul> <li>A JavaScript object made available to a consumer, that provides access to Ethereum by means of a Client.</li> </ul> </li> <li>Wallet <ul> <li>An end-user application that manages private keys, performs signing operations, and acts as a middleware between the Provider and the Client.</li> </ul> </li> <li>Transaction Replacement <ul> <li>Submitting a transaction with both: the same nonce and a 10% increase in the gas price, of a previous transaction which a user no longer wishes to send. This must occur before the original transaction is included in the blockchain.</li> </ul> </li> </ul> <h3 id="events">Events</h3> <p>These methods <strong>MUST</strong> be implemented per the Node.js <a rel="external" href="https://nodejs.org/api/events.html"><code>EventEmitter</code> API</a>.</p> <p>The following three events must be implemented: <code>tx_replacement</code>, <code>tx_speedup</code> and <code>tx_cancel</code>.</p> <p>A <code>tx_speedup</code> is defined as a transaction replacement in which the user wishes to adjust the <code>gasPrice</code>, to potentially receive a fast block inclusion. For a <code>tx_speedup</code> to be considered valid, the replacement tx must contain the <strong>same</strong> following properties as the one it supersedes:</p> <ul> <li>Nonce</li> <li>To</li> <li>Value</li> <li>Data</li> </ul> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> txSpeedupInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> oldTx</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> newTx</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> nonce</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> from</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">Provider</span><span>.</span><span class="z-entity z-name">on</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">tx_speedup</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable z-other"> listener</span><span>:</span><span> (</span><span class="z-variable">txSpeedupInfo</span><span class="z-keyword">:</span><span class="z-entity z-name"> txSpeedupInfo</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-keyword"> void</span><span>)</span><span>: </span><span class="z-variable z-other">Provider</span><span>;</span></span></code></pre> <p>This event emits the old transaction hash (<code>oldTx</code>), the new transaction hash (<code>newTx</code>), the nonce used for both transactions (<code>nonce</code>), and the signing address for the transaction (<code>from</code>).</p> <p>A <code>tx_cancel</code> is defined as a transaction replacement in which the user wishes to nullify a previous transaction before its inclusion. For a <code>tx_cancel</code> to be considered valid, the replacement tx must contain the following properties:</p> <ul> <li>The same nonce as the superseded transaction</li> <li>The same From and To</li> <li>Zero value</li> <li>No data</li> </ul> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> txCancelInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> oldTx</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> newTx</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> nonce</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> from</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">Provider</span><span>.</span><span class="z-entity z-name">on</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">tx_cancel</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable z-other"> listener</span><span>:</span><span> (</span><span class="z-variable">txCancelInfo</span><span class="z-keyword">:</span><span class="z-entity z-name"> txCancelInfo</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-keyword"> void</span><span>)</span><span>: </span><span class="z-variable z-other">Provider</span><span>;</span></span></code></pre> <p>This event emits the old transaction hash (<code>oldTx</code>), the new transaction hash (<code>newTx</code>), the nonce used for both transactions (<code>nonce</code>), and the signing address for the transaction (<code>from</code>).</p> <p>A <code>tx_replacement</code> is defined as a transaction replacement in which a user has completely replaced a previous transaction with a completely brand new one. The replacement tx must contain the following properties:</p> <ul> <li>The same nonce as the superseded transaction</li> </ul> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> txReplacementInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> oldTx</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> newTx</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> nonce</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-storage"> readonly</span><span class="z-variable"> from</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">Provider</span><span>.</span><span class="z-entity z-name">on</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">tx_replacement</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable z-other"> listener</span><span>:</span><span> (</span><span class="z-variable">txReplacementInfo</span><span class="z-keyword">:</span><span class="z-entity z-name"> txReplacementInfo</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span class="z-keyword"> void</span><span>)</span><span>: </span><span class="z-variable z-other">Provider</span><span>;</span></span></code></pre> <p>This event emits the old transaction hash (<code>oldTx</code>), the new transaction hash (<code>newTx</code>), the nonce used for both transactions (<code>nonce</code>), and the signing address for the transaction (<code>from</code>).</p> <h2 id="rationale">Rationale</h2> <p>The implementation was chosen to help the ease of implementation for both providers and dapp developers. Since <code>ProviderMessage</code> is widely used by dapp developers already it means that the implementation path would be as trivial as adding and additional <code>if</code> clause to their existing message listener. This also provides a benefit to dapps in the event that a provider has not yet implemented the events, it will not cause the dapp panic with <code>undefined</code> should it be implemented natively (eg: <code>ethereum.txCancel(...)</code> which would error with <code>ethereum.txReplacement()</code> is not a function).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Many Providers adopted EIP-1193, as this EIP extends the same event logic, there should be no breaking changes. All providers that do not support the new events should either I) Ignore the subscription or II) Provide some error to the user.</p> <h2 id="implementations">Implementations</h2> <ul> <li><a rel="external" href="https://github.com/ethereum/web3.js/issues/3723">Web3.js</a></li> <li><a rel="external" href="https://github.com/MetaMask/metamask-extension/issues/9174">MetaMask</a></li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>None at the current time.</p> <h2 id="references">References</h2> <ul> <li><a rel="external" href="https://github.com/ethereum/web3.js/issues/3585">Web3.js issue with metamask tx cancel</a></li> <li><a rel="external" href="https://github.com/MetaMask/metamask-extension/issues/3347">Browser doesn't know when a transaction is replace</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> <h2 id="appendix-i-examples">Appendix I: Examples</h2> <p>These examples assume a web browser environment.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Most Providers are available as window.ethereum on page load.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> This is only a convention, not a standard, and may not be the case in practice.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Please consult the Provider implementation&#39;s documentation.</span></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> ethereum</span><span class="z-keyword"> =</span><span class="z-variable z-other"> window</span><span>.</span><span class="z-variable z-other">ethereum</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> transactionParameters</span><span class="z-keyword"> =</span><span> {</span><span class="z-keyword"> ...</span><span> }</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Fill in parameters</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">ethereum</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">request</span><span>(</span><span>{</span><span> </span></span> <span class="giallo-l"><span> method</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">eth_sendTransaction</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span> params</span><span>:</span><span> [</span><span class="z-variable z-other">transactionParameters</span><span>]</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">then</span><span>(</span><span>(</span><span class="z-variable">txHash</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> ethereum</span><span>.</span><span class="z-entity z-name">on</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">tx_cancel</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> (</span><span class="z-variable">info</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span> {</span><span class="z-variable z-other z-constant"> oldTx</span><span>,</span><span class="z-variable z-other z-constant"> newTx</span><span>,</span><span class="z-variable z-other z-constant"> nonce</span><span>,</span><span class="z-variable z-other z-constant"> from</span><span> }</span><span class="z-keyword"> =</span><span class="z-variable z-other"> message</span><span>.</span><span class="z-variable z-other">data</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> console</span><span>.</span><span class="z-entity z-name">log</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">Tx </span><span class="z-string">${</span><span class="z-variable z-other">oldTx</span><span class="z-string">}</span><span class="z-string"> with nonce </span><span class="z-string">${</span><span class="z-variable z-other">nonce</span><span class="z-string">}</span><span class="z-string"> from </span><span class="z-string">${</span><span class="z-variable z-other">from</span><span class="z-string">}</span><span class="z-string"> was cancelled, the new hash is </span><span class="z-string">${</span><span class="z-variable z-other">newTx</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>)</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> ethereum</span><span>.</span><span class="z-entity z-name">on</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">tx_speedup</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> (</span><span class="z-variable">info</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span> {</span><span class="z-variable z-other z-constant"> oldTx</span><span>,</span><span class="z-variable z-other z-constant"> newTx</span><span>,</span><span class="z-variable z-other z-constant"> nonce</span><span>,</span><span class="z-variable z-other z-constant"> from</span><span> }</span><span class="z-keyword"> =</span><span class="z-variable z-other"> message</span><span>.</span><span class="z-variable z-other">data</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> console</span><span>.</span><span class="z-entity z-name">log</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">Tx </span><span class="z-string">${</span><span class="z-variable z-other">oldTx</span><span class="z-string">}</span><span class="z-string"> with nonce </span><span class="z-string">${</span><span class="z-variable z-other">nonce</span><span class="z-string">}</span><span class="z-string"> from </span><span class="z-string">${</span><span class="z-variable z-other">from</span><span class="z-string">}</span><span class="z-string"> was sped up, the new hash is </span><span class="z-string">${</span><span class="z-variable z-other">newTx</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>)</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> ethereum</span><span>.</span><span class="z-entity z-name">on</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">tx_replacement</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> (</span><span class="z-variable">info</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span> {</span><span class="z-variable z-other z-constant"> oldTx</span><span>,</span><span class="z-variable z-other z-constant"> newTx</span><span>,</span><span class="z-variable z-other z-constant"> nonce</span><span>,</span><span class="z-variable z-other z-constant"> from</span><span> }</span><span class="z-keyword"> =</span><span class="z-variable z-other"> message</span><span>.</span><span class="z-variable z-other">data</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> console</span><span>.</span><span class="z-entity z-name">log</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">Tx </span><span class="z-string">${</span><span class="z-variable z-other">oldTx</span><span class="z-string">}</span><span class="z-string"> with nonce </span><span class="z-string">${</span><span class="z-variable z-other">nonce</span><span class="z-string">}</span><span class="z-string"> from </span><span class="z-string">${</span><span class="z-variable z-other">from</span><span class="z-string">}</span><span class="z-string"> was replaced, the new hash is </span><span class="z-string">${</span><span class="z-variable z-other">newTx</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>)</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> console</span><span>.</span><span class="z-entity z-name">log</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">Transaction hash </span><span class="z-string">${</span><span class="z-variable z-other">txHash</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>)</span></span> <span class="giallo-l"><span> }</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">catch</span><span>(</span><span>(</span><span class="z-variable">error</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> console</span><span>.</span><span class="z-entity z-name">error</span><span>(</span><span class="z-punctuation z-definition z-string">`</span><span class="z-string">Error sending transaction: </span><span class="z-string">${</span><span class="z-variable z-other">error</span><span class="z-string">.</span><span class="z-variable z-other">code</span><span class="z-string">}</span><span class="z-string">: </span><span class="z-string">${</span><span class="z-variable z-other">error</span><span class="z-string">.</span><span class="z-variable z-other">message</span><span class="z-string">}</span><span class="z-punctuation z-definition z-string">`</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span></code></pre> 2020-07-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Micah Zoltuhttps://github.com/MicahZoltu https://wg-eips.ritovision.com/2803/

Support 'rich transactions' by allowing transactions from externally owned accounts to execute bytecode directly.

<h2 id="abstract">Abstract</h2> <p>If a transaction has a <code>to</code> of address <code>x</code>, then the <code>data</code> of the transaction will be treated as EVM bytecode and it will be executed from the context of the <code>CALLER</code> of the transaction (aka: the transaction signer).</p> <h2 id="motivation">Motivation</h2> <p>Many Ethereum DApps presently require users to approve multiple transactions in order to produce one effect - for example, the common pattern of first approving a contract to spend a token, then calling that contract. This results in a poor user-experience, and complicates the experience of interacting with DApps.</p> <p>Making it possible for externally owned accounts to execute EVM bytecode directly allows a single transaction to execute multiple contract calls, allowing DApps to provide a streamlined experience, where every interaction results in at most one transaction.</p> <p>While this is in principle possible today using contract wallets, other UX issues, such as the need to fund a sending account with gas money, lack of support for contract wallets in browser integrations, and lack of a consistent API for contract wallets has led to poor adoption of these.This EIP is a way of enhancing the utility of existing EOAs, in the spirit of "don't let the perfect be the enemy of the good".</p> <h2 id="specification">Specification</h2> <p>A new reserved address is specified at <code>x</code>, in the range used for precompiles. When a transaction is sent to this address from an externally owned account, the payload of the transaction is treated as EVM bytecode, and executed with the signer of the transaction as the current account. For clarity:</p> <ul> <li>The <code>ADDRESS</code> opcode returns the address of the EOA that signed the transaction.</li> <li>The <code>BALANCE</code> opcode returns the balance of the EOA that signed the transaction.</li> <li>Any <code>CALL</code> operations that send value take their value from the EOA that signed the transaction.</li> <li><code>CALL</code> will set the <code>CALLER</code> to the EOA (not <code>x</code>).</li> <li><code>DELEGATECALL</code> preserves the EOA as the owning account.</li> <li>The <code>CALLER</code> and <code>ORIGIN</code> opcodes both return the address of the EOA that signed the transaction.</li> <li>There is no code associated with the precompile address. <code>CODE*</code> and <code>EXTCODE*</code> opcodes behave the same as they do for any empty address.</li> <li><code>CALLDATA*</code> opcodes operate on the transaction payload as expected.</li> <li><code>SLOAD</code> and <code>SSTORE</code> operate on the storage of the EOA. As a result, an EOA can have data in storage, that persists between transactions.</li> <li>The <code>SELFDESTRUCT</code> opcode does nothing.</li> <li>All other opcodes behave as expected for a call to a contract address.</li> <li>The transaction is invalid if there is any value attached.</li> <li>A call to the precompile address from a contract has no special effect and is equivalent to a call to a nonexistent precompile or an empty address.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The intent of this EIP is for the new precompile to act in all ways possible like a <code>DELEGATECALL</code> from an externally owned account. Some changes are required to reflect the fact that the code being executed is not stored on chain, and for special cases such as <code>SELFDESTRUCT</code>, to prevent introducing new edge-cases such as the ability to zero-out an EOA's nonce.</p> <p>A precompile was used rather than a new EIP-2718 transaction type because a precompile allows us to have a rich transaction with any type of EIP-2718 transaction.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a new feature that will need to be implemented in a future hard fork. No backwards compatibility issues with existing code are expected.</p> <p>Contracts or DApps that assume that an EOA cannot atomically perform multiple operations may be affected by this change, as this now makes it possible for EOAs to execute multiple atomic operations together. The authors do not believe this is a significant use-case, as this 'protection' is already trivially defeated by miners.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-07-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Soham Zemsehttps://github.com/zemse Nick Mudgehttps://github.com/mudgen https://wg-eips.ritovision.com/2767/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard for Governance contracts that holds the administrative ownership of other smart contracts with voting power distributed as <code>ERC-20</code> tokens.</p> <h2 id="abstract">Abstract</h2> <p>The following standard defines the implementation of a standard API for a Governance smart contract based on <code>ERC-20</code>. Existing <code>ERC-173</code> compatible contracts can upgrade from private key wallet ownership to a Governance smart contract. Adhering to a standard API enables general tools to populate governance information of various projects, thus increasing transparency.</p> <h2 id="motivation">Motivation</h2> <p>Traditionally, many contracts that require that they be owned or controlled in some way use <code>ERC-173</code> which standardized the use of ownership in the smart contracts. For example to withdraw funds or perform administrative actions.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> dApp</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> doSomethingAdministrative</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> admin logic that can be performed by a single wallet</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Often, such administrative rights for a contract are written for maintenance purpose but users need to trust the owner. Rescue operations by an owner have raised questions on decentralised nature of the projects. Also, there is a possibility of compromise of an owner's private key.</p> <p>At present, many governance implementations by ambitious projects need users to visit a specific UI to see governance information about their project. Some examples of live implementations having different API that does the same thing are <a rel="external" href="https://github.com/compound-finance/compound-protocol/blob/master/contracts/Governance/GovernorAlpha.sol#L27">Compound Governance</a>, <a rel="external" href="https://github.com/Uniswap/governance/blob/master/contracts/GovernorAlpha.sol#L27">Uniswap Governance</a> and <a rel="external" href="https://github.com/sushiswap/sushiswap/blob/master/contracts/GovernorAlpha.sol#L45">Sushiswap Governance</a>. It's just like if the ERC-20 standard wasn't finalized, then token projects would have their own block explorer. Adhering to a standard API would enable general tools (like Etherscan) to populate governance information, thus increasing transparency to users. Using widely popular <code>ERC-20</code> token as a governance token, existing tools built to work with <code>ERC-20</code> can already display voters. This can result in a wide adoption for contract governance over private key based ownership.</p> <h2 id="specification">Specification</h2> <p>A Governance contract that is compliant with <code>ERC-2767</code> shall implement the following interfaces:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-2767 Governance</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> ERC-165 InterfaceID: 0xd8b04e0e</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC2767</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets number votes required for achieving consensus</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Should cost less than 30000 gas</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Required</span><span class="z-comment"> number of votes for achieving consensus</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> quorumVotes</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> The address of the Governance ERC20 token</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> token</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="erc-20-governance-token"><code>ERC-20</code> Governance Token</h3> <p>An <code>ERC-2767</code> Governance Contract should reference an address through <code>token()</code> that implements <code>ERC-20</code> interface. <code>token()</code> is allowed to return self address (<code>address(this)</code>), if <code>ERC-20</code> functionalities are implemented in the same contract (one can consider checking out Diamond Standard <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2535"><code>ERC-2535</code></a> to optimise contract size).</p> <p>Implementations are allowed to have varying <code>ERC-20</code>'s <code>totalSupply()</code> (through any standard of minting or burning). But having a fixed <code>quorumVotes()</code> return value in this case would cause required votes consensus in <code>%</code> with respect to <code>totalSupply()</code> to change. To automatically account for this, any custom logic under <code>quorumVotes()</code> is allowed to return for e.g. <code>51%</code> of <code>totalSupply()</code>.</p> <h3 id="erc-165-interface-identification"><code>ERC-165</code> Interface Identification</h3> <p>An <code>ERC-2767</code> Governance Contract should also implement <code>ERC-165</code>. This helps general tools to identify whether a contract is a <code>ERC-2767</code> Governance contract.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Query if a contract implements an interface</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> interfaceID</span><span class="z-comment"> The interface identifier, as specified in ERC-165</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface identification is specified in ERC-165. This function</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> uses less than 30,000 gas.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-comment"> `true` if the contract implements `interfaceID` and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `interfaceID` is not 0xffffffff, `false` otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The goals of this EIP have been the following:</p> <ul> <li>Standardize API of Governance contracts to make it easy for analysis tools to be built.</li> <li>Encourage use of <code>ERC-20</code> based weighted governance over existing multi-sig (<em>generally limited to 50 max owners</em>) for big projects.</li> <li>Encourage existing <code>ERC-173</code> ownership smart contracts / projects to move to Governance based ownership by removing the effort needed to host custom UI for their project.</li> <li>Encourage availability of publicly audited governance contracts, just like <code>ERC-20</code> which anyone can use.</li> <li>Make it possible to utilize existing <code>ERC-20</code> tools for owners of governance token analysis.</li> <li>Make future protocols possible that need to interact with governances of multiple projects.</li> <li>Keep this EIP minimal and allow another EIPs to standardize any specific functionalities.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Smart contracts that are <code>ERC-173</code> compliant can transfer their ownership to a Governance contract. This enables such contracts to become compatible with <code>ERC-2767</code> Governance.</p> <p>However, there are some existing projects with governance implementations and most of them have custom APIs (<a rel="external" href="https://github.com/compound-finance/compound-protocol/blob/master/contracts/Governance/GovernorAlpha.sol#L27">Compound Governance</a>, <a rel="external" href="https://github.com/Uniswap/governance/blob/master/contracts/GovernorAlpha.sol#L27">Uniswap Governance</a> and <a rel="external" href="https://github.com/sushiswap/sushiswap/blob/master/contracts/GovernorAlpha.sol#L45">Sushiswap Governance</a>), since a standard did not exist. Not having an <code>ERC-2767</code> compatible governance contract means only that general tools might not be able to populate their governance information without including some special code for the project.</p> <p>For existing governance contracts to get compatible with <code>ERC-2767</code>:</p> <ol> <li>Projects can deploy a new governance contract and transfer ownership to it to be <code>ERC-2767</code> compatible. This is suitable for those who use Multi-sig wallets for Governance.</li> <li>It is understood that redeploying governance contracts would be a troublesome task, and contracts who already have functionality similar to <code>ERC-20</code> based (weighted votes) have a bit advanced way to avoid it. Basically, they can create a forwarder contract implements <code>ERC-2767</code> and forwards all calls to the actual non-standard methods. Projects can list the forwarder contract to display the information project's governance info without requiring any custom code in analysys tool, but this might have certain limitations depending on the project's existing governance implementation. Specification of forwarder contract is out of scope for this EIP and it may be addressed in another EIP if required.</li> </ol> <!-- ## Test Cases --> <h2 id="implementation">Implementation</h2> <p>The reference implementations are available in this <a rel="external" href="https://github.com/zemse/contract-ownership-governance">repository</a>. Publicly audited implementations will be included in future.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Implementers are free to choose between On-chain and Off-chain consensus. Exact specification is out of scope for this standard (open for other EIPs to standardize). However, this section mentions points that implementers can consider.</p> <h4 id="on-chain">On-chain</h4> <p>In such implementations, community can create transaction proposals and vote on it by sending on-chain transactions.</p> <ul> <li>OpenZeppelin Snapshots can be used to prevent double voting.</li> </ul> <h4 id="off-chain">Off-chain</h4> <ul> <li>The signatures in off-chain governance implementation can follow recommendations of <code>ERC-191</code> or <code>ERC-712</code>.</li> <li>To prevent replaying signatures, it'd be best if executer is required to sort the signatures based on increasing addresses.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-07-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alex Forshtathttps://github.com/forshtat Dror Tiroshhttps://github.com/drortirosh https://wg-eips.ritovision.com/2770/ <h2 id="simple-summary">Simple Summary</h2> <p>Standardized contract interface for extensible meta-transaction forwarding.</p> <h2 id="abstract">Abstract</h2> <p>This proposal defines an external API of an extensible Forwarder whose responsibility is to validate transaction signatures on-chain and expose the signer to the destination contract, that is expected to accommodate all use-cases. The ERC-712 structure of the forwarding request can be extended allowing wallets to display readable data even for types not known during the Forwarder contract deployment.</p> <h2 id="motivation">Motivation</h2> <p>There is a growing interest in making it possible for Ethereum contracts to accept calls from externally owned accounts that do not have ETH to pay for gas.</p> <p>This can be accomplished with meta-transactions, which are transactions that have been signed as plain data by one externally owned account first and then wrapped into an Ethereum transaction by a different account.</p> <p><code>msg.sender</code> is a transaction parameter that can be inspected by a contract to determine who signed the transaction. The integrity of this parameter is guaranteed by the Ethereum EVM, but for a meta-transaction verifying <code>msg.sender</code> is insufficient, and signer address must be recovered as well.</p> <p>The Forwarder contract described here allows multiple Gas Relays and Relay Recipient contracts to rely on a single instance of the signature verifying code, improving reliability and security of any participating meta-transaction framework, as well as avoiding on-chain code duplication.</p> <h2 id="specification">Specification</h2> <p>The Forwarder contract operates by accepting a signed typed data together with it's ERC-712 signature, performing signature verification of incoming data, appending the signer address to the data field and performing a call to the target.</p> <h3 id="forwarder-data-type-registration">Forwarder data type registration</h3> <p>Request struct MUST contain the following fields in this exact order:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>struct ForwardRequest {</span></span> <span class="giallo-l"><span> address from;</span></span> <span class="giallo-l"><span> address to;</span></span> <span class="giallo-l"><span> uint256 value;</span></span> <span class="giallo-l"><span> uint256 gas;</span></span> <span class="giallo-l"><span> uint256 nonce;</span></span> <span class="giallo-l"><span> bytes data;</span></span> <span class="giallo-l"><span> uint256 validUntil;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>from</code> - an externally-owned account making the request<br /> <code>to</code> - a destination address, normally a smart-contract<br /> <code>value</code> - an amount of Ether to transfer to the destination<br /> <code>gas</code> - an amount of gas limit to set for the execution<br /> <code>nonce</code> - an on-chain tracked nonce of a transaction<br /> <code>data</code> - the data to be sent to the destination<br /> <code>validUntil</code> - the highest block number the request can be forwarded in, or 0 if request validity is not time-limited</p> <p>The request struct MAY include any other fields, including nested structs, if necessary. In order for the Forwarder to be able to enforce the names of the fields of this struct, only registered types are allowed.</p> <p>Registration MUST be performed in advance by a call to the following method:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function registerRequestType(string typeName, string typeSuffix)</span></span></code></pre> <p><code>typeName</code> - a name of a type being registered<br /> <code>typeSuffix</code> - an ERC-712 compatible description of a type</p> <p>For example, after calling</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>registerRequestType(&quot;ExtendedRequest&quot;, &quot;uint256 x,bytes z,ExtraData extraData)ExtraData(uint256 a,uint256 b,uint256 c)&quot;)</span></span></code></pre> <p>the following ERC-712 type will be registered with forwarder:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/* primary type */</span></span> <span class="giallo-l"><span>struct ExtendedRequest {</span></span> <span class="giallo-l"><span> address from;</span></span> <span class="giallo-l"><span> address to;</span></span> <span class="giallo-l"><span> uint256 value;</span></span> <span class="giallo-l"><span> uint256 gas;</span></span> <span class="giallo-l"><span> uint256 nonce;</span></span> <span class="giallo-l"><span> bytes data;</span></span> <span class="giallo-l"><span> uint256 validUntil;</span></span> <span class="giallo-l"><span> uint256 x;</span></span> <span class="giallo-l"><span> bytes z;</span></span> <span class="giallo-l"><span> ExtraData extraData;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>/* subtype */</span></span> <span class="giallo-l"><span>struct ExtraData {</span></span> <span class="giallo-l"><span> uint256 a;</span></span> <span class="giallo-l"><span> uint256 b;</span></span> <span class="giallo-l"><span> uint256 c;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="signature-verification">Signature verification</h3> <p>The following method performs an ERC-712 signature check on a request:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function verify(</span></span> <span class="giallo-l"><span> ForwardRequest forwardRequest,</span></span> <span class="giallo-l"><span> bytes32 domainSeparator,</span></span> <span class="giallo-l"><span> bytes32 requestTypeHash,</span></span> <span class="giallo-l"><span> bytes suffixData,</span></span> <span class="giallo-l"><span> bytes signature</span></span> <span class="giallo-l"><span>) view;</span></span></code></pre> <p><code>forwardRequest</code> - an instance of the <code>ForwardRequest</code> struct<br /> <code>domainSeparator</code> - caller-provided domain separator to prevent signature reuse across dapps (refer to ERC-712) <code>requestTypeHash</code> - hash of the registered relay request type <code>suffixData</code> - RLP-encoding of the remainder of the request struct <code>signature</code> - an ERC-712 signature on the concatenation of <code>forwardRequest</code> and <code>suffixData</code></p> <h3 id="command-execution">Command execution</h3> <p>In order for the Forwarder to perform an operation, the following method is to be called:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function execute(</span></span> <span class="giallo-l"><span> ForwardRequest forwardRequest,</span></span> <span class="giallo-l"><span> bytes32 domainSeparator,</span></span> <span class="giallo-l"><span> bytes32 requestTypeHash,</span></span> <span class="giallo-l"><span> bytes suffixData,</span></span> <span class="giallo-l"><span> bytes signature</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>public</span></span> <span class="giallo-l"><span>payable</span></span> <span class="giallo-l"><span>returns (</span></span> <span class="giallo-l"><span> bool success,</span></span> <span class="giallo-l"><span> bytes memory ret</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Performs the ‘verify’ internally and if it succeeds performs the following call:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>bytes memory data = abi.encodePacked(forwardRequest.data, forwardRequest.from);</span></span> <span class="giallo-l"><span>...</span></span> <span class="giallo-l"><span>(success, ret) = forwardRequest.to.call{gas: forwardRequest.gas, value: forwardRequest.value}(data);</span></span></code></pre> <p>Regardless of whether the inner call succeeds or reverts, the nonce is incremented, invalidating the signature and preventing a replay of the request.</p> <p>Note that <code>gas</code> parameter behaves according to EVM rules, specifically EIP-150. The forwarder validates internally that there is enough gas for the inner call. In case the <code>forwardRequest</code> specifies non-zero value, extra <code>40000 gas</code> is reserved in case inner call reverts or there is a remaining Ether so there is a need to transfer value from the <code>Forwarder</code>:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint</span><span> gasForTransfer </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span> (</span><span> req</span><span>.</span><span>value </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span> )</span><span> {</span></span> <span class="giallo-l"><span> gasForTransfer </span><span class="z-keyword">=</span><span class="z-constant"> 40000</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> buffer in case we need to move Ether after the transaction.</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>.</span><span>.</span><span>.</span></span> <span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span class="z-variable z-language">gasleft</span><span>(</span><span>)</span><span class="z-keyword">*</span><span class="z-constant">63</span><span class="z-keyword">/</span><span class="z-constant">64</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> req</span><span>.</span><span>gas </span><span class="z-keyword">+</span><span> gasForTransfer</span><span>,</span><span class="z-string"> &quot;FWD: insufficient gas&quot;</span><span>)</span><span>;</span></span></code></pre> <p>In case there is not enough <code>value</code> in the Forwarder the execution of the inner call fails.<br /> Be aware that if the inner call ends up transferring Ether to the <code>Forwarder</code> in a call that did not originally have <code>value</code>, this Ether will remain inside <code>Forwarder</code> after the transaction is complete.</p> <h3 id="erc-712-and-suffixdata-parameter">ERC-712 and 'suffixData' parameter</h3> <p><code>suffixData</code> field must provide a valid 'tail' of an ERC-712 typed data. For instance, in order to sign on the <code>ExtendedRequest</code> struct, the data will be a concatenation of the following chunks:</p> <ul> <li><code>forwardRequest</code> fields will be RLP-encoded as-is, and variable-length <code>data</code> field will be hashed</li> <li><code>uint256 x</code> will be appended entirely as-is</li> <li><code>bytes z</code> will be hashed first</li> <li><code>ExtraData extraData</code> will be hashed as a typed data</li> </ul> <p>So a valid <code>suffixData</code> is calculated as following:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function calculateSuffixData(ExtendedRequest request) internal pure returns (bytes) {</span></span> <span class="giallo-l"><span> return abi.encode(request.x, keccak256(request.z), hashExtraData(request.extraData));</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function hashExtraData(ExtraData extraData) internal pure returns (bytes32) {</span></span> <span class="giallo-l"><span> return keccak256(abi.encode(</span></span> <span class="giallo-l"><span> keccak256(&quot;ExtraData(uint256 a,uint256 b,uint256 c)&quot;),</span></span> <span class="giallo-l"><span> extraData.a,</span></span> <span class="giallo-l"><span> extraData.b,</span></span> <span class="giallo-l"><span> extraData.c</span></span> <span class="giallo-l"><span> ));</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="accepting-forwarded-calls">Accepting Forwarded calls</h3> <p>In order to support calls performed via the Forwarder, the Recipient contract must read the signer address from the last 20 bytes of <code>msg.data</code>, as described in ERC-2771.</p> <h2 id="rationale">Rationale</h2> <p>Further relying on <code>msg.sender</code> to authenticate end users by their externally-owned accounts is taking the Ethereum dapp ecosystem to a dead end.</p> <p>A need for users to own Ether before they can interact with any contract has made a huge portion of use-cases for smart contracts non-viable, which in turn limits the mass adoption and enforces this vicious cycle.</p> <p><code>validUntil</code> field uses a block number instead of timestamp in order to allow for better precision and integration with other common block-based timers.</p> <h2 id="security-considerations">Security Considerations</h2> <p>All contracts introducing support for the Forwarded requests thereby authorize this contract to perform any operation under any account. It is critical that this contract has no vulnerabilities or centralization issues.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-06-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Aaron Kendallhttps://github.com/jaerith Juan Blancohttps://github.com/juanfranblanco https://wg-eips.ritovision.com/2746/ <h2 id="simple-summary">Simple Summary</h2> <p>An interface for using a smart contract as a rules engine. A single deployed contract can register a data domain, create sets of rules that perform actions on that domain, and then invoke a set as an atomic transaction.</p> <h2 id="abstract">Abstract</h2> <p>This standard proposes an interface that will allow the creation of hierarchal sets of rules (i.e., RuleTrees) that can be invoked to evaluate and manipulate a registered data domain. At the time of this draft, all intentions to insert additional functionality onto the blockchain requires the coding and creation of a newly deployed contract. However, this standard will allow users to deploy a contract just once, one which will then allow them to create (and invoke) pipelines of commands within that contract.</p> <h2 id="motivation">Motivation</h2> <p>At the time of this draft, all development for Ethereum requires writing the code that forms smart contracts and then deploying those contracts to Ethereum. In order to create a proper contract, many considerations must be taken into account when designing and implementing the code, especially in terms of efficiency (i.e., gas cost) and security. Even the simplest contracts require a certain amount of vigilance and examination, before and after deployment. These requirements pertain to all cases, even for simple cases of examining a value and/or altering it.</p> <p>These technical challenges might form an obstacle for many others who might wish to create software around Ethereum. Less technical companies and users might also want to configure and deploy simple functionality onto the chain, without knowing the relevant languages or details necessary. By having the data domain and the predefined actions (i.e., types of rules) implemented along with this interface, a deployed instance of such a rules engine contract can provide efficient and safe functionality to no-code or little-code clients, allowing more users of various technical proficiency to interact with the Ethereum ecosystem.</p> <h2 id="specification">Specification</h2> <p>For the clarification of terminology, an Attribute is a registered data point within the data domain, representing data that exists either in the rules engine contract or elsewhere. A Rule is an predefined action that occurs upon a single data point (i.e., Attribute) in the predefined data domain. For example, a Rule could check whether the Attribute 'TokenAmt' has a value less than the RHL (i.e., right-hand value) of 10. A RuleSet is a collection of Rules, where their collection invocation creates a boolean result that determines the navigational flow of execution between RuleSets. A RuleTree is a collection of RuleSets that are organized within a hierarchy, where RuleSets can contain other RuleSets.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.6.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-2746 Rules Engine Standard</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> See https://eips.ethereum.org/EIPS/eip-2746</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> interface</span><span class="z-entity z-name"> ERCRulesEngine</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Should emit when a RuleTree is invoked.</span></span> <span class="giallo-l"><span class="z-comment"> The `ruler` is the ID and owner of the RuleTree being invoked. It is also likely msg.sender.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CallRuleTree</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ruler</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Should emit when a RuleSet is invoked.</span></span> <span class="giallo-l"><span class="z-comment"> The `ruler` is the ID and owner of the RuleTree in which the RuleSet is stored. It is also likely msg.sender.</span></span> <span class="giallo-l"><span class="z-comment"> The &#39;ruleSetId&#39; is the ID of the RuleSet being invoked.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CallRuleSet</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ruler</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tmpRuleSetId</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Should emit when a Rule is invoked.</span></span> <span class="giallo-l"><span class="z-comment"> The `ruler` is the ID and owner of the RuleTree in which the RuleSet is stored. It is also likely msg.sender.</span></span> <span class="giallo-l"><span class="z-comment"> The &#39;ruleSetId&#39; is the ID of the RuleSet being invoked.</span></span> <span class="giallo-l"><span class="z-comment"> The &#39;ruleId&#39; is the ID of the Rule being invoked.</span></span> <span class="giallo-l"><span class="z-comment"> The &#39;ruleType&#39; is the type of the rule being invoked. </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CallRule</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ruler</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ruleSetId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ruleId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> ruleType</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Should emit when a RuleSet fails.</span></span> <span class="giallo-l"><span class="z-comment"> The `ruler` is the ID and owner of the RuleTree in which the RuleSet is stored. It is also likely msg.sender.</span></span> <span class="giallo-l"><span class="z-comment"> The &#39;ruleSetId&#39; is the ID of the RuleSet being invoked.</span></span> <span class="giallo-l"><span class="z-comment"> The &#39;severeFailure&#39; is the indicator of whether or not the RuleSet is a leaf with a &#39;severe&#39; error flag.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RuleSetError</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ruler</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ruleSetId</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> severeFailure</span></span> <span class="giallo-l"><span> )</span><span>;</span><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Adds a new Attribute to the data domain.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Caller should be the deployer/owner of the rules engine contract. An Attribute value can be an optional alternative if it&#39;s not a string or numeric.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _attrName</span><span class="z-comment"> Name/ID of the Attribute</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _maxLen</span><span class="z-comment"> Maximum length of the Attribute (if it is a string)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _maxNumVal</span><span class="z-comment"> Maximum numeric value of the Attribute (if it is numeric)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _defaultVal</span><span class="z-comment"> The default value for the Attribute (if one is not found from the source)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _isString</span><span class="z-comment"> Indicator of whether or not the Attribute is a string</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _isNumeric</span><span class="z-comment"> Indicator of whether or not the Attribute is numeric</span></span> <span class="giallo-l"><span class="z-comment"> */</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addAttribute</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _attrName</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _maxLen</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _maxNumVal</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _defaultVal</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _isString</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _isNumeric</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Adds a new RuleTree.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> Owner/ID of the RuleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ruleTreeName</span><span class="z-comment"> Name of the RuleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _desc</span><span class="z-comment"> Verbose description of the RuleTree&#39;s purpose</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addRuleTree</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _ruleTreeName</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _desc</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Adds a new RuleSet onto the hierarchy of a RuleTree.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> RuleSets can have child RuleSets, but they will only be called if the parent&#39;s Rules execute to create boolean &#39;true&#39;.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> Owner/ID of the RuleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ruleSetName</span><span class="z-comment"> ID/Name of the RuleSet</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _desc</span><span class="z-comment"> Verbose description of the RuleSet</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _parentRSName</span><span class="z-comment"> ID/Name of the parent RuleSet, to which this will be added as a child</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _severalFailFlag</span><span class="z-comment"> Indicator of whether or not the RuleSet&#39;s execution (as failure) will result in a failure of the RuleTree. (This flag only applies to leaves in the RuleTree.)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _useAndOp</span><span class="z-comment"> Indicator of whether or not the rules in the RuleSet will execute with &#39;AND&#39; between them. (Otherwise, it will be &#39;OR&#39;.)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _failQuickFlag</span><span class="z-comment"> Indicator of whether or not the RuleSet&#39;s execution (as failure) should immediately stop the RuleTree.</span></span> <span class="giallo-l"><span class="z-comment"> */</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addRuleSet</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _ruleSetName</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _desc</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _parentRSName</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _severalFailFlag</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _useAndOp</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _failQuickFlag</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Adds a new Rule into a RuleSet.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Rule types can be implemented as any type of action (greater than, less than, etc.)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> Owner/ID of the RuleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ruleSetName</span><span class="z-comment"> ID/Name of the RuleSet to which the Rule will be added</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ruleName</span><span class="z-comment"> ID/Name of the Rule being added</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _attrName</span><span class="z-comment"> ID/Name of the Attribute upon which the Rule is invoked</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ruleType</span><span class="z-comment"> ID of the type of Rule</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _rightHandValue</span><span class="z-comment"> The registered value to be used by the Rule when performing its action upon the Attribute</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _notFlag</span><span class="z-comment"> Indicator of whether or not the NOT operator should be performed on this Rule.</span></span> <span class="giallo-l"><span class="z-comment"> */</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addRule</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _ruleSetName</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _ruleName</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _attrName</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _ruleType</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _rightHandValue</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _notFlag</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Executes a RuleTree.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> Owner/ID of the RuleTree</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeRuleTree</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieves the properties of a Rule.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> Owner/ID of the RuleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ruleSetName</span><span class="z-comment"> ID/Name of the RuleSet where the Rule resides</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ruleIdx</span><span class="z-comment"> Index of the rule in the RuleSet&#39;s listing </span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> bytes32</span><span class="z-comment"> ID/Name of Rule</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> uint</span><span class="z-comment"> Type of Rule</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> bytes32</span><span class="z-comment"> Target Attribute of Rule</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> string</span><span class="z-comment"> Value mentioned in Rule</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> bool</span><span class="z-comment"> Flag for NOT operator in Rule</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> bytes32</span><span class="z-comment">[] Values that should be provided in delegated call (if Rule is custom operator)</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRuleProps</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _ruleSetName</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _ruleIdx</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>,</span><span class="z-support"> uint</span><span>,</span><span class="z-support"> bytes32</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> bool</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieves the properties of a RuleSet</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> Owner/ID of the RuleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _ruleSetName</span><span class="z-comment"> ID/Name of the RuleSet</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> string</span><span class="z-comment"> Verbose description of the RuleSet</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> bool</span><span class="z-comment"> Flag that indicates whether this RuleSet&#39;s failure (if a leaf) will cause the RuleTree to fail</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> bool</span><span class="z-comment"> Flag that indicates whether this RuleSet uses the AND operator when executing rules collectively</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> uint</span><span class="z-comment"> Indicates the number of rules hosted by this RuleSet</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> bytes32</span><span class="z-comment">[] The list of RuleSets that are children of this RuleSet</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRuleSetProps</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _ruleSetName</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> bool</span><span>,</span><span class="z-support"> bool</span><span>,</span><span class="z-support"> uint</span><span>,</span><span class="z-support"> uint</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Retrieves the properties of a RuleSet</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> Owner/ID of the RuleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> bytes32</span><span class="z-comment"> Name of the RuleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> string</span><span class="z-comment"> Verbose description of the RuleTree</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> bytes32</span><span class="z-comment"> ID/Name of the RuleSet that serves as the root node for the RuleTree</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getRuleTreeProps</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span>,</span><span class="z-support"> bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Removes a RuleTree.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> Owner/ID of the RuleTree</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeRuleTree</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="considerations">Considerations</h3> <p>An argument could be made for interface functions that allow a RuleTree's owner to include others users as executors of the RuleTree.</p> <p>Another argument could be made for interface functions that allow an administrator to configure the origin point of an Attribute, such as whether the Attribute's value comes from a data structure (internal to the rules engine contract) or from calling a contract method (like an implementation of the <a rel="external" href="https://github.com/ethereum/EIPs/issues/2535">Diamond Standard</a>).</p> <p>Yet another argument could be made for interface functions that allow an administrator to extend the functionality catalog provided by the rules engine, by allowing other contracts' methods to be added as a rule operation.</p> <p>Also, an argument could be made for functions that calculate and report the range of potential cost for invoking a RuleTree. Unlike the normal execution of a contract method, the Ethereum transaction costs of invoking a RuleTree are more dynamic, depending on its depth/breadth and the navigational flow during invocation. Since the general cost of a RuleTree is unknown until the time of invocation, these functions could report the minimal amount of gas for a transaction (i.e., none of the Rules in a RuleTree are invoked) and the maximum amount for a transaction (i.e., all Rules in a RuleTree are invoked).</p> <h3 id="example">Example</h3> <p>A company wishes to deploy a contract with data points and functionality that are predefined and/or under the control of an administrator, and it aims to build a no-code client that will allow less-technical users to define actions within the rules engine contract. In this example, the company wants one of its users to write the rules in a proprietary markup language, in order for the calculation of a VAT to be determined. For the sake of transparency, <a rel="external" href="https://ipfs.infura.io/ipfs/QmPrZ9959c7SzzqdLkVgX28xM7ZrqLeT3ydvRAHCaL1Hsn">these rules</a> are published onto IPFS, so that they are accessible to auditors and possibly government officials. The no-code client will then know how to parse the rules from the markup and communicate with the rules engine contract, establishing the RuleTree to be invoked later by the company's user(s) or off-chain programs.</p> <p>In order to calculate the value of the VAT, these provided rules invoke simple mathematical operations that can perform the calculation. However, the implementation of the rules engine contract could possess other functionality called by rules, ones that could execute more complicated logic or call the methods of other contracts.</p> <h2 id="rationale">Rationale</h2> <h3 id="attributes">Attributes</h3> <p>The data points are abstracted in order to let the implementation provide the mechanism for retrieving/populating the data. Data can be held by an internal data structure, another contract's method, or any number of other options.</p> <h3 id="events">Events</h3> <p>The events specified will help the caller of the RuleTree after execution, so that they may ascertain the navigational flow of RuleSet execution within the RuleTree and so that they may understand which RuleSets failed.</p> <h3 id="right-hand-value">Right-Hand Value</h3> <p>In the function addRule(), the data type for the right-hand value is 'string' since the rule's action depends on its type, meaning that the value must be provided in a generic form. In the case of a Rule that performs numerical operations, the provided value could be transformed into a number when stored in the Rule.</p> <h2 id="implementation">Implementation</h2> <ul> <li><a rel="external" href="https://github.com/Nethereum/Wonka/tree/master/Solidity/WonkaEngine">Wonka</a></li> <li><a rel="external" href="https://github.com/jaerith/WonkaRulesBlazorEditor">Wonka Rules Editor</a></li> </ul> <p>The Wonka implementation supports this proposed interface and also implements all of the additional considerations mentioned above.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The deployer of the contract should be the owner and administrator, allowing for the addition of Attributes and RuleTrees. Since a RuleTree is owned by a particular EOA (or contract address), the only accounts that should be able to execute the RuleTree should be its owner or the contract's owner/administrator. If Attributes are defined to exist as data within other contracts, the implementation must take into account the possibility that RuleTree owners must have the security to access the data in those contracts.</p> <h2 id="references">References</h2> <p><strong>Standards</strong></p> <ul> <li><a href="https://wg-eips.ritovision.com/2535/">EIP-2535 Diamond Standard</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-05-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jim McDonaldJim@mcdee.net https://wg-eips.ritovision.com/2680/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard layout and naming format for walletstore and keystore for both hierarchical (e.g. filesystem, Amazon S3) and non-hierarchical (key/value) storage systems.</p> <h2 id="abstract">Abstract</h2> <p>Ethereum wallets have no standards for their layout in persistent storage, making different wallet implementations incompatible. This defines a standard for the placement of Ethereum walletstores and keystores, making it possible for different software to work with the same wallets and keys.</p> <h2 id="motivation">Motivation</h2> <p>A standard layout for wallets and accounts allows interoperability between validators. This benefits users, as they can move from one validator software to another (and back) without requiring movement of files. This is important because any movement of files containing keys involves danger of either deleting them or duplicating them, both of which could cause loss of access to funds.</p> <h2 id="specification">Specification</h2> <p>There are four elements for a wallet that need to be addressed. These are defined below.</p> <h3 id="base-location">Base location</h3> <p>The base location is required to be well-known, either pre-defined or defined by the storage system's connection parameters.</p> <p>For filesystems the pre-defined base location for different operating systems is as follows:</p> <ul> <li>Windows: <code>%APPDATA%\ethereum2\wallets</code></li> <li>MacOSX: <code>${HOME}/Library/Application Support/ethereum2/wallets</code></li> <li>Linux: <code>${HOME}/.config/ethereum2/wallets</code></li> </ul> <p>For other hierarchical stores, for example Amazon S3, the base location MUST be the lower-case hex string representing the <a href="https://wg-eips.ritovision.com/2680/./assets/sha256-384-512.pdf">SHA-256</a> hash of the string "Ethereum 2 wallet:" appended with the identifier for the hierarchical store. For example, if the account ID for a user's Amazon S3 account is "AbC0438EB" then:</p> <ul> <li>string would be <code>Ethereum 2 wallet:AbC0438EB</code></li> <li>SHA-256 hash of string would be the byte array <code>0x991ec14a8d13836b10d8c3039c9e30876491cb8aa9c9c16967578afc815c9229</code></li> <li>base location would be the string <code>991ec14a8d13836b10d8c3039c9e30876491cb8aa9c9c16967578afc815c9229</code></li> </ul> <p>For non-hierarchical stores there is no base location.</p> <h3 id="wallet-container">Wallet container</h3> <p>The wallet container holds the walletstore and related keystores.</p> <p>The wallet container is identified by the wallet's UUID. It MUST be a string following the syntactic structure as laid out in <a rel="external" href="https://tools.ietf.org/html/rfc4122#section-3">section 3 of RFC 4122</a>.</p> <h3 id="walletstore">Walletstore</h3> <p>The walletstore element contains the walletstore and is held within the wallet container. It is identified by the wallet's UUID. It MUST be a string following the syntactic structure as laid out in <a rel="external" href="https://tools.ietf.org/html/rfc4122#section-3">section 3 of RFC 4122</a>.</p> <h3 id="keystore">Keystore</h3> <p>The keystore element contains the keystore for a given key and is held within the wallet container. It is identified by the key's UUID. It MUST be a string following the syntactic structure as laid out in <a rel="external" href="https://tools.ietf.org/html/rfc4122#section-3">section 3 of RFC 4122</a>.</p> <h2 id="hierarchical-store-example">Hierarchical store example</h2> <p>Hierarchical stores are a common way to store and organize information. The most common example is the filesystem, but a number of object-based stores such as Amazon S3 also provide hierarchical naming.</p> <p>Putting these elements together for a sample wallet with wallet UUID <code>1f031fff-c51d-44fc-8baf-d6b304cb70a7</code> and key UUIDs <code>1302106c-8441-4e2e-b687-6c77f49fc624</code> and <code>4a320100-83fd-4db7-8126-6d6d205ba834</code> gives the following layout:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>- 1f031fff-c51d-44fc-8baf-d6b304cb70a7</span></span> <span class="giallo-l"><span>+- 1302106c-8441-4e2e-b687-6c77f49fc624</span></span> <span class="giallo-l"><span>+- 1f031fff-c51d-44fc-8baf-d6b304cb70a7</span></span> <span class="giallo-l"><span>+- 4a320100-83fd-4db7-8126-6d6d205ba834</span></span></code></pre><h3 id="non-hierarchical-store-example">Non-hierarchical store example</h3> <p>Non-hierarchical stores use a simplified approach where the wallet UUID and key UUIDs are concatenated using the ':' character. Using the same example wallet and key UUIDs as above would result in objects with the following keys:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>1f031fff-c51d-44fc-8baf-d6b304cb70a7:1302106c-8441-4e2e-b687-6c77f49fc624</span></span> <span class="giallo-l"><span>1f031fff-c51d-44fc-8baf-d6b304cb70a7:1f031fff-c51d-44fc-8baf-d6b304cb70a7</span></span> <span class="giallo-l"><span>1f031fff-c51d-44fc-8baf-d6b304cb70a7:4a320100-83fd-4db7-8126-6d6d205ba834</span></span></code></pre><h3 id="protecting-against-concurrent-write-access">Protecting against concurrent write access</h3> <p>TBD</p> <h3 id="iterating-over-wallets">Iterating over wallets</h3> <p>In the case of hierarchical stores and iteration-capable non-hierarchical stores iteration over wallets is a matter of iterating over the files in the root container.</p> <p>An implementer MAY include an index in the base location. If so then it MUST follow the structure as specified in the following "Index format" section.</p> <h3 id="iterating-over-accounts">Iterating over accounts</h3> <p>In the case of hierarchical stores iteration over accounts is a matter of iterating over the files in the wallet container.</p> <p>An implementer MAY include an index within a wallet container for accounts within that wallet. If so then it MUST follow the structure as specified in the following "Index format" section.</p> <h3 id="index-format">Index format</h3> <p>The index format is the same for both wallets and accounts, following a standard JSON schema.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">array</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">items</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">uuid</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uuid</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The index MUST use the identifier 'index'.</p> <p>Public keys must NOT be stored in the index.</p> <h2 id="rationale">Rationale</h2> <p>A standard for walletstores, similar to that for keystores, provides a higher level of compatibility between wallets and allows for simpler wallet and key interchange between them.</p> <h2 id="implementation">Implementation</h2> <p>A Go implementation of the filesystem layout can be found at <a rel="external" href="https://github.com/wealdtech/go-eth2-wallet-filesystem">https://github.com/wealdtech/go-eth2-wallet-filesystem</a>.</p> <p>A Go implementation of the Amazon S3 layout can be found at <a rel="external" href="https://github.com/wealdtech/go-eth2-wallet-s3">https://github.com/wealdtech/go-eth2-wallet-s3</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Locations for wallet stores are defined to be within each user's personal space, reducing the possibility of accidental exposure of information. It is, however, still possible for permissions to be set such that this data is world-readable, and applications implementing this EIP should attempt to set, and reset, permissions to ensure that only the relevant user has access to the information.</p> <p>The names for both wallet and key stores are UUIDs, ensuring that no data is leaked from the metadata.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-05-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Vlasovhttps://github.com/shamatar https://wg-eips.ritovision.com/2666/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP tries to set prices of certain precompiles and built-in EVM function to be in line with their performance, consumed resources and newer changes in EVM itself.</p> <p>New price formulas are proposed for:</p> <ul> <li>SHA256 precompile (<code>0x02</code>)</li> <li>RIPEMD precompile (<code>0x03</code>)</li> <li>KECCAK256 opcode (<code>0x20</code>)</li> </ul> <h2 id="abstract">Abstract</h2> <p>Costs of many precompiles and built-in functions are invalid at the current state of the clients. This EIP contains a list of changes to the pricing formulas to better reflect underlying computations' structure.</p> <h2 id="motivation">Motivation</h2> <p>Historical pricing for these functions in EVM does not reflect inner structure of the underlying computations (inner structure of the hash functions).</p> <ul> <li>EIP-2046 changes a <code>STATICCALL (0xfa)</code> cost to precompile and it may be necessary to adjust costs of some precompiles that <em>may</em> have taken old large cost (<code>700</code> gas) into account and tried to compensate for it</li> <li>Some precompiles are overpriced and their pricing formulas do not reflect the structure of underlying functions</li> <li>Keccak256 built-in function (opcode) in EVM has pricing that does not reflect underlying hash function structure</li> </ul> <h2 id="specification">Specification</h2> <p>If <code>block_number &gt;= X</code> set the gas cost of the following precompiles and Keccak256 opcode:</p> <ul> <li>SHA256 (precompile <code>0x02</code>): <code>10 + ((len(input) + 8)/64 + 1) * 9</code></li> <li>RIPEMD (precompile <code>0x03</code>): <code>6 + ((len(input) + 8)/64 + 1) * 12</code></li> <li>KECCAK256 (<code>0x20</code>): <code>13 + (len(input)/136 + 1)*15</code></li> </ul> <p>This EIP <em>ideally</em> requires that <code>MODEXP</code> repricing is <a href="https://wg-eips.ritovision.com/2565/">implemented</a> to also accurately reflect that there is no implicit compensation for an old <code>STATICCALL (0xfa)</code> cost (pre-2046).</p> <h2 id="rationale">Rationale</h2> <p>Cost of functions being executed must accurately reflect real CPU time spent on computations, so benchmarking was performed for current precompiles and Keccak256 function to measure running time versus input parameters.</p> <h3 id="detailed-summary-of-repricing-approach">Detailed summary of repricing approach</h3> <p>This EIP relies on two facts:</p> <ul> <li>apriori knowledge of the inner strucute of the hash functions</li> <li>benchmarks provided by the client teams for some reasonable range of input lengths for random inputs (random byte strings of a given length)</li> </ul> <h3 id="benchmarks-on-the-most-popular-clients">Benchmarks on the most popular clients</h3> <p>Necessary benchmarks for EIP-2666 were provided by the clients and raw form is assembled in <a rel="external" href="https://docs.google.com/spreadsheets/d/1aCQnk7prrp3Mbcf011BE5zZnkbc3Iw7QAixn6mLbKS0/edit?usp=sharing">here</a></p> <ul> <li>SHA256 precompile</li> </ul> <p>Currently it's <code>60</code> gas + <code>12</code> gas per <code>32</code> byte word (number of words is <code>ceil(len(input)/word_len)</code> here and in similar places. If there is no <code>floor</code> or <code>ceil</code> specifier all divisions below are integer divisions (floor divisions)). Proposed formula is <code>A * ((len(input) + 8) / 64 + 1) + B</code>, with coefficients below</p> <table><thead><tr><th></th><th></th><th>A</th><th>B</th></tr></thead><tbody> <tr><td>Geth</td><td></td><td>5</td><td>3</td></tr> <tr><td>OE</td><td></td><td>9</td><td>4</td></tr> <tr><td>Besu</td><td></td><td>5</td><td>10</td></tr> <tr><td>Nethermind</td><td></td><td>10</td><td>5</td></tr> </tbody></table> <p>EIP-2666 proposes <code>A = 9</code>, <code>B = 10</code>. There are no large one-off costs in this precompile, so it's EIP-2046 - safe.</p> <ul> <li>RIPEMD precompile</li> </ul> <p>Currently it's <code>600</code> gas + <code>120</code> gas per <code>32</code> byte word. Proposed formula is <code>A * ((len(input) + 8) / 64 + 1) + B</code>, with coefficients below</p> <table><thead><tr><th></th><th></th><th>A</th><th>B</th></tr></thead><tbody> <tr><td>Geth</td><td></td><td>12</td><td>6</td></tr> <tr><td>OE</td><td></td><td>8</td><td>2</td></tr> <tr><td>Besu</td><td></td><td>29</td><td>16</td></tr> <tr><td>Nethermind</td><td></td><td>10</td><td>6</td></tr> </tbody></table> <p>EIP-2666 proposes <code>A = 12</code>, <code>B = 6</code>. There are no large one-off costs in this precompile, so it's EIP-2046 - safe. Besu expects to have performance improvements by the end of the year.</p> <ul> <li>Keccak256 performance</li> </ul> <p>Currently it's <code>30</code> gas + <code>6</code> gas per <code>32</code> byte word. Proposed formula is <code>A * (len(input) / 136 + 1) + B</code>, with coefficients below</p> <table><thead><tr><th></th><th></th><th>A</th><th>B</th></tr></thead><tbody> <tr><td>Geth</td><td></td><td>13</td><td>13</td></tr> <tr><td>OE</td><td></td><td>15</td><td>2</td></tr> <tr><td>Besu</td><td></td><td>19</td><td>28</td></tr> <tr><td>Nethermind</td><td></td><td>16</td><td>3</td></tr> </tbody></table> <p>EIP-2666 proposes <code>A = 15</code>, <code>B = 13</code>. There are no large one-off costs in this precompile, so it's EIP-2046 - safe. Besu expects to have performance improvements by the end of the year.</p> <h3 id="tooling-and-data">Tooling and data</h3> <p>Reference material (from benchmarks of different clients) with raw data can be found <a rel="external" href="https://docs.google.com/spreadsheets/d/1aCQnk7prrp3Mbcf011BE5zZnkbc3Iw7QAixn6mLbKS0/edit?usp=sharing">here</a>.</p> <p>There is a repository available with inputs for benchmarking and precompiles testing <a rel="external" href="https://github.com/shamatar/bench_precompiles">here</a> that can be used by client teams to perform all the necessary measurements.</p> <p>Raw Besu <a rel="external" href="https://gist.github.com/shemnon/0ddba91be501fa23291bdec9107fe99a">benchmarks</a>.</p> <h3 id="note-on-formulas-structure">Note on formulas structure</h3> <p>There are terms in formulas that look like <code>A * 1</code> and those are explicitly not combined to the <code>B</code> coefficient to reflect that hash of an empty byte array requires to perform a round of hashing anyway.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Precompile repricings has happened in a past and can be considered standard procedure. Gas costs of many contracts is expected to reduce that may break re-entrancy protection measures based on fixed gas costs. In any case, such protection should have never been considered good and final.</p> <h2 id="test-cases">Test Cases</h2> <p>Let's consider a simple example of Keccak256 hash of <code>0</code>, <code>64</code> and <code>160</code> bytes that can is a simple sanity check for implementation.</p> <ul> <li>Hash <code>0</code> bytes: <ul> <li>Old price: <code>30 + 6 * ceil(0 / 32) = 30</code> gas</li> <li>New price: <code>15 * (0/136 + 1) + 13 = 28</code> gas</li> </ul> </li> <li>Hash <code>64</code> bytes <ul> <li>Old price: <code>30 + 6 * ceil(64 / 32) = 42</code> gas</li> <li>New price: <code>15 * (64/136 + 1) + 13 = 28</code> gas</li> </ul> </li> <li>Hash <code>160</code> bytes <ul> <li>Old price: <code>30 + 6 * ceil(160 / 32) = 60</code> gas</li> <li>New price: <code>15 * (160/136 + 1) + 13 = 43</code> gas</li> </ul> </li> </ul> <h2 id="implementation">Implementation</h2> <p>There is no reference implementation at the time of writing as it requires just a simple change of constants in major clients.</p> <h2 id="security-considerations">Security Considerations</h2> <p>As described in backward compatibility section in some cases reduction of cost may allow e.g. re-entrancy that was not expected before, but we think that re-entrancy protection based on fixed gas costs is anyway flawed design decision.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-05-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Tom Brandtom@starkware.co Louis Guthmannlouis@starkware.co https://wg-eips.ritovision.com/2645/ <h2 id="simple-summary">Simple Summary</h2> <p>In the context of Computation Integrity Proof (CIP) Layer-2 solutions such as ZK-Rollups, users are required to sign messages on new elliptic curves optimized for those environments. We leverage existing work on Key Derivation (<a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki">BIP32</a>, <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki">BIP39</a> and <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki">BIP44</a>) to define an efficient way to securely produce CIP L2s private keys, as well as creating domain separation between Layer-2 applications.</p> <h2 id="abstract">Abstract</h2> <p>We provide a Derivation Path allowing a user to derive hierarchical keys for Layer-2 solutions depending on the zk-technology, the application, the user’s Layer-1 address, as well as an efficient grinding method to enforce the private key distribution within the curve domain. The propose Derivation Path is defined as follow</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>m / purpose&#39; / layer&#39; / application&#39; / eth_address_1&#39; / eth_address_2&#39; / index</span></span></code></pre><h2 id="motivation">Motivation</h2> <p>In the context of Computation Integrity Proof (CIP) Layer-2 solutions such as ZK-Rollups, users are required to sign messages on new elliptic curves optimized for those environments. Extensive work has been done to make it secure on Bitcoin via <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki">BIP32</a>, <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki">BIP39</a> and <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki">BIP44</a>. These protocols are the standard for wallets in the entire industry, independent of the underlying blockchain. As Layer-2 solutions are taking off, it is a necessary requirement to maintain the same standard and security in this new space.</p> <h2 id="specification">Specification</h2> <p>Starkware keys are derived with the following <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki">BIP43</a>-compatible derivation path, with direct inspiration from <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki">BIP44</a>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>m / purpose&#39; / layer&#39; / application&#39; / eth_address_1&#39; / eth_address_2&#39; / index</span></span></code></pre> <p>where:</p> <ul> <li><code>m</code> - the seed.</li> <li><code>purpose</code> - <code>2645</code> (the number of this EIP).</li> <li><code>layer</code> - the 31 lowest bits of sha256 on the layer name. Serve as a domain separator between different technologies. In the context of <code>starkex</code>, the value would be <code>579218131</code>.</li> <li><code>application</code> - the 31 lowest bits of sha256 of the application name. Serve as a domain separator between different applications. In the context of DeversiFi in June 2020, it is the 31 lowest bits of sha256(starkexdvf) and the value would be <code>1393043894</code>.</li> <li><code>eth_address_1 / eth_address_2</code> - the first and second 31 lowest bits of the corresponding eth_address.</li> <li><code>index</code> - to allow multiple keys per eth_address.</li> </ul> <p>As example, the expected path for address 0x0000....0000 assuming seed <code>m</code> and index 0 in the context of DeversiFi in June 2020: <code>m/2645'/579218131'/1393043894'/0'/0'/0</code></p> <p>The key derivation should follow the following algorithm</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>N = 2**256</span></span> <span class="giallo-l"><span>n = Layer2 curve order</span></span> <span class="giallo-l"><span>path = stark derivation path</span></span> <span class="giallo-l"><span>BIP32() = Official BIP-0032 derivation function on secp256k1</span></span> <span class="giallo-l"><span>hash = SHA256</span></span> <span class="giallo-l"><span>i = 0</span></span> <span class="giallo-l"><span>root_key = BIP32(path)</span></span> <span class="giallo-l"><span>while True:</span></span> <span class="giallo-l"><span> key = hash(root_key|i)</span></span> <span class="giallo-l"><span> if (key &lt; (N - (N % n))):</span></span> <span class="giallo-l"><span> return key % n</span></span> <span class="giallo-l"><span> i++</span></span></code></pre> <p>This algorithm has been defined to maintain efficiency on existing restricted devices.</p> <p>Nota Bene: At each round, the probability for a key to be greater than (N - (N % n)) is &lt; 2^(-5).</p> <h2 id="rationale">Rationale</h2> <p>This EIP specifies two aspects of keys derivation in the context of Hierarchical Wallets:</p> <ul> <li>Derivation Path</li> <li>Grinding Algorithm to enforce a uniform distribution over the elliptic curve. The derivation path is defined to allow efficient keys separation based on technology and application while maintaining a 1-1 relation with the Layer-1 wallet. In such a way, losing EIP-2645 wallets falls back to losing the Layer-1 wallet.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This standard complies with BIP43.</p> <h2 id="security-considerations">Security Considerations</h2> <p>This EIP has been defined to maintain separation of keys while providing foolproof logic on key derivation.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-04-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kohshi Shibakohshi.shiba@gmail.com https://wg-eips.ritovision.com/2615/ <h2 id="simple-summary">Simple Summary</h2> <p>This standard proposes an extension to ERC721 Non-Fungible Tokens (NFTs) to support rental and mortgage functions. These functions are necessary for NFTs to emulate real property, just like those in the real world.</p> <h2 id="abstract">Abstract</h2> <p>This standard is an extension of ERC721. It proposes additional roles, the right of tenants to enable rentals, and the right of lien.</p> <p>With ERC2615, NFT owners will be able to rent out their NFTs and take out a mortgage by collateralizing their NFTs. For example, this standard can apply to:</p> <ul> <li>Virtual items (in-game assets, virtual artwork, etc.)</li> <li>Physical items (houses, automobiles, etc.)</li> <li>Intellectual property rights</li> <li>DAO membership tokens</li> </ul> <p>NFT developers are also able to easily integrate ERC2615 since it is fully backwards-compatible with the ERC721 standard.</p> <p>One notable point is that the person who has the right to use an application is not the owner but the user (i.e. tenant). Application developers must implement this specification into their applications.</p> <h2 id="motivation">Motivation</h2> <p>It has been challenging to implement rental and mortgage functions with the ERC721 standard because it only has one role defined (which is the Owner).</p> <p>Currently, a security deposit is needed for trustless renting with ERC721, and ownership lockup within a contract is necessary whenever one chooses to mortgage their ERC721 property. The tracking and facilitation of these relationships must be done separately from the ERC721 standard.</p> <p>This proposal eliminates these requirements by integrating basic rights of tenantship and liens. By standardizing these functions, developers can more easily integrate rental and mortgage functions for their applications.</p> <h2 id="specification">Specification</h2> <p>This standard proposes three user roles: the <strong>Lien Holder</strong>, the <strong>Owner</strong>, and the <strong>User</strong>. Their rights are as follows:</p> <ul> <li> <p>A <strong>Lien Holder</strong> has the right to:</p> <ol> <li>Transfer the <strong>Owner</strong> role</li> <li>Transfer the <strong>User</strong> role</li> </ol> </li> <li> <p>An <strong>Owner</strong> has the right to:</p> <ol> <li>Transfer the <strong>Owner</strong> role</li> <li>Transfer the <strong>User</strong> role</li> </ol> </li> <li> <p>A <strong>User</strong> has the right to:</p> <ol> <li>Transfer the <strong>User</strong> role</li> </ol> </li> </ul> <h3 id="erc-2615-interface">ERC-2615 Interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> TransferUser</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> itemId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> operator</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ApprovalForUser</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> approved</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> TransferOwner</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> itemId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> operator</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ApprovalForOwner</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> approved</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ApprovalForAll</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> approved</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> LienApproval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> itemId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> TenantRightApproval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> itemId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> LienSet</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> itemId</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> TenantRightSet</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> itemId</span><span>,</span><span class="z-support">bool</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOfOwner</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOfUser</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> userOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> safeTransferOwner</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> safeTransferOwner</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> itemId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> safeTransferUser</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> safeTransferUser</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> itemId</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approveForOwner</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getApprovedForOwner</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approveForUser</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getApprovedForUser</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setApprovalForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> approved</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isApprovedForAll</span><span>(</span><span class="z-support">address</span><span class="z-variable"> requester</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> operator</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approveLien</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getApprovedLien</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setLien</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getCurrentLien</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revokeLien</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approveTenantRight</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getApprovedTenantRight</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setTenantRight</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getCurrentTenantRight</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revokeTenantRight</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre><h3 id="erc-2615-receiver">ERC-2615 Receiver</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> onERCXReceived</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> itemId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> layer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes4</span><span>)</span><span>;</span></span></code></pre><h3 id="erc-2615-extensions">ERC-2615 Extensions</h3> <p>Extensions here are provided to help developers build with this standard.</p> <h4 id="1-erc721-compatible-functions">1. ERC721 Compatible functions</h4> <p>This extension makes this standard compatible with ERC721. By adding the following functions, developers can take advantage of the existing tools for ERC721.</p> <p>Transfer functions in this extension will transfer both the <strong>Owner</strong> and <strong>User</strong> roles when the tenant right has not been set. Conversely, when the tenant right has been set, only the <strong>Owner</strong> role will be transferred.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> to</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> itemId</span><span>)</span><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> getApproved</span><span>(</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> from</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> to</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> itemId</span><span>)</span><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> safeTransferFrom</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> from</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> to</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> itemId</span><span>)</span><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-entity z-name">function</span><span class="z-entity z-name"> safeTransferFrom</span><span>(</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> from</span><span>,</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> to</span><span>,</span><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> itemId</span><span>,</span><span class="z-entity z-name"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-entity z-name"> data</span><span>)</span><span class="z-entity z-name"> pubic</span></span></code></pre><h4 id="2-enumerable">2. Enumerable</h4> <p>This extension is analogous to the enumerable extension of the ERC721 standard.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> totalNumberOfItems</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> itemOfOwnerByIndex</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> index</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> layer</span><span>)</span><span class="z-storage z-type">public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> itemByIndex</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> index</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre><h4 id="3-metadata">3. Metadata</h4> <p>This extension is analogous to the metadata extension of the ERC721 standard.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> itemURI</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> itemId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> name</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> symbol</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h2 id="how-rentals-and-mortgages-work">How rentals and mortgages work</h2> <p>This standard does not deal with token or value transfer. Other logic (outside the scope of this standard) must be used to orchestrate these transfers and to implement validation of payment.</p> <h3 id="mortgage-functions">Mortgage functions</h3> <p>The following diagram demonstrates the mortgaging functionality.</p> <p><img src="https://wg-eips.ritovision.com/2615/./assets/mortgage-sequential.jpg" alt="concept image" title="mortgage" /></p> <p>Suppose Alice owns an NFT and wants to take out a mortgage, and Bob wants to earn interest by lending tokens to Alice.</p> <ol> <li>Alice approves the setting of a lien for the NFT Alice owns.</li> <li>Alice sends a loan request to the mortgage contract.</li> <li>Bob fills the loan request and transfers tokens to the mortgage contract. The lien is then set on the NFT by the mortgage contract.</li> <li>Alice can now withdraw the borrowed tokens from the mortgage contract.</li> <li>Alice registers repayment (anyone can pay the repayment).</li> <li>Bob can finish the agreement if the agreement period ends and the agreement is kept (i.e. repayment is paid without delay).</li> <li>Bob can revoke the agreement if the agreement is breached (e.g. repayment is not paid on time) and execute the lien and take over the ownership of the NFT.</li> </ol> <h3 id="rental-functions">Rental functions</h3> <p>The following diagram demonstrates the rental functionality.</p> <p><img src="https://wg-eips.ritovision.com/2615/./assets/rental-sequential.jpg" alt="concept image" title="rental" /></p> <p>Suppose Alice owns NFTs and wants to rent out a NFT, and Bob wants to lease a NFT.</p> <ol> <li>Alice approves the setting of a tenant-right for the NFT Alice owns.</li> <li>Alice sends a rental listing to the rental contract.</li> <li>Bob fills the rental request, and the right to use the NFT is transferred to Bob. At the same time, the tenant-right is set, and Alice becomes not able to transfer the right to use the NFT.</li> <li>Bob registers rent (anyone can pay the rent).</li> <li>Alice can withdraw the rent from the rental contract.</li> <li>Alice can finish the agreement if the agreement period has ended and the agreement is kept (i.e. rent is paid without delay).</li> <li>Alice can revoke the agreement if the agreement is breached (e.g. rent is not paid on time) and revoke the tenant-right and take over the right to use the NFT.</li> </ol> <h2 id="rationale">Rationale</h2> <p>There have been some attempts to achieve rentals or mortgages with ERC721. However, as I noted before, it has been challenging to achieve. I will explain the reasons and advantages of this standard below.</p> <h3 id="no-security-lockup-for-rentals">No security lockup for rentals</h3> <p>To achieve trustless rental of NFTs with ERC721, it has been necessary to deposit funds as security. This is required to prevent malicious activity from tenants, as it is impossible to take back ownership once it is transferred.</p> <p>With this standard, security deposits are no longer needed since the standard natively supports rental and tenantship functions.</p> <h3 id="no-ownership-escrow-when-taking-out-a-mortgage">No ownership escrow when taking out a mortgage</h3> <p>In order to take out a mortgage on NFTs, it has been necessary to transfer the NFTs to a contract as collateral. This is required to prevent the potential default risk of the mortgage.</p> <p>However, secured collateral with ERC721 hurts the utility of the NFT. Since most NFT applications provide services to the canonical owner of a NFT, the NFT essentially cannot be utilized under escrow.</p> <p>With ERC2615, it is possible to collateralize NFTs and use them at the same time.</p> <h3 id="easy-integration">Easy integration</h3> <p>Because of the above reasons, a great deal of effort is required to implement rental and mortgage functions with ERC721. Adopting this standard is a much easier way to integrate rental and mortgage functionality.</p> <h3 id="no-money-token-transactions-within-tokens">No money/token transactions within tokens</h3> <p>A NFT itself does not handle lending or rental functions directly. This standard is open-source, and there is no platform lockup. Developers can integrate it without having to worry about those risks.</p> <h2 id="backward-compatibility">Backward compatibility</h2> <p>As mentioned in the specifications section, this standard can be fully ERC721 compatible by adding an extension function set.</p> <p>In addition, new functions introduced in this standard have many similarities with the existing functions in ERC721. This allows developers to easily adopt the standard quickly.</p> <h2 id="test-cases">Test Cases</h2> <p>When running the tests, you need to create a test network with Ganache-CLI:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ganache-cli -a 15 --gasLimit=0x1fffffffffffff -e 1000000000</span></span></code></pre> <p>And then run the tests using Truffle:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>truffle test -e development</span></span></code></pre> <p>Powered by Truffle and Openzeppelin test helper.</p> <h2 id="implementation">Implementation</h2> <p><a rel="external" href="https://github.com/kohshiba/ERC-X">Github Repository</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Since the external contract will control lien or tenant rights, flaws within the external contract directly lead to the standard's unexpected behavior.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-04-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Hancockhttps://github.com/madeoftin https://wg-eips.ritovision.com/2657/ <p><strong>Disclaimer: This is for testing basic infrastructure. It will be nuked. It is not for deploying dapps, nor does it define what will go into mainnet. For information on network upgrades, please follow the relevant meta EIPs and ongoing discussion on Ethereum/pm.</strong></p> <h2 id="abstract">Abstract</h2> <p>The specification for Ephemeral Testnet Yolo. Clients who wish to sync need to implement the following features into their client. It is for testing basic infrastructure and will be nuked.</p> <h2 id="specification">Specification</h2> <p>Name: Yolo ID: <code>YOLO-v1</code></p> <ul> <li><input disabled="" type="checkbox" checked=""/> EIP 2537 Commit Hash - <a rel="external" href="https://github.com/ethereum/EIPs/commit/5edff4ae6ff62c7e0bbfad624fc3d0ba7dc84392">5edff4ae6ff62c7e0bbfad624fc3d0ba7dc84392</a></li> <li><input disabled="" type="checkbox" checked=""/> EIP 2315 Commit Hash - <a rel="external" href="https://github.com/ethereum/EIPs/commit/e8accf22cdc5562d6982c560080c6cd6b7f94867">e8accf22cdc5562d6982c560080c6cd6b7f94867</a></li> </ul> <p><em>[ ] Proposed - [x] Consensus to include.</em></p> <h2 id="timeline">Timeline</h2> <ul> <li>Deployed: June 3rd 2020</li> </ul> <h2 id="client-consensus-implementation">Client Consensus -&gt; Implementation</h2> <p>YOLO-v1</p> <table><thead><tr><th><strong>Client</strong></th><th>Signal</th><th>Spec</th><th>Merged</th><th>Syncing</th></tr></thead><tbody> <tr><td>Besu</td><td>x</td><td>x</td><td></td><td></td></tr> <tr><td>EthereumJS</td><td>x</td><td></td><td></td><td></td></tr> <tr><td>Geth</td><td>x</td><td>x</td><td>x</td><td>x</td></tr> <tr><td>Nethermind</td><td>x</td><td>x</td><td></td><td></td></tr> <tr><td>OpenEthereum</td><td>x</td><td>x</td><td></td><td></td></tr> <tr><td>Trinity</td><td></td><td></td><td></td><td></td></tr> </tbody></table> <p><strong>Signal</strong> - Client intends to participate. <em>(You are on the bus)</em></p> <p><strong>Spec</strong> - Client is satisfied with the proposed specification. <em>(You agree with the direction)</em></p> <p><strong>Merge</strong> - Changes are implemented in the client and configurable for YOLO. <em>(You are ready to hit the gas and go)</em></p> <p><strong>Syncing</strong> Client syncs with the network</p> <h2 id="syncing-instructions">Syncing Instructions</h2> <p><strong>Geth</strong></p> <ul> <li>Yolo V1 testnet is up and running https://yolonet.xyz/</li> <li>Support is baked into Geth master branch via --yolov1</li> <li>Genesis config json is at https://yolonet.xyz/yolo.json</li> <li>EF bootnode at enode://9e1096aa59862a6f164994cb5cb16f5124d6c992cdbf4535ff7dea43ea1512afe5448dca9df1b7ab0726129603f1a3336b631e4d7a1a44c94daddd03241587f9@35.178.210.161:30303</li> <li>Stats page secret is YOLOv1, with geth you can --ethstats='yournode:YOLOv1@stats.yolonet.xyz'</li> <li>Faucet is unauthenticated, you can reach it from the dashboard</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-04-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Guillaume Ballethttps://github.com/gballet https://wg-eips.ritovision.com/2584/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP proposes a method to convert the state trie format from hexary to binary: new values are directly stored in a binary trie “laid over” the hexary trie. Meanwhile, the hexary trie is converted to a binary trie in the background. When the process is finished, both layers are merged.</p> <h2 id="abstract">Abstract</h2> <p>This EIP describes a four phase process to complete the conversion.</p> <ul> <li>In the first phase, all new state writes are made to an overlay binary trie, while the hexary trie is being converted to binary. The block format is changed to have two storage roots: the root of the hexary trie (hereafter called the "base" trie) and the root of the overlay binary trie.</li> <li>After enough time has been given to miners to perform the conversion, the second phase begins. The overlay tree is progressively merged back into the newly converted binary base trie. A constant number of entries are deleted from the overlay and inserted into the base trie.</li> <li>The third and final phase begins when the overlay trie is empty. The field holding its root is removed from the block header.</li> </ul> <h2 id="motivation">Motivation</h2> <p>There is a long running interest in switching the state trie from a hexary format to a binary format, for reasons pertaining to proof and storage sizes. The conversion process poses a catch-up issue, caused by the sheer size of the full state: it can not be translated in a reasonable time (i.e. on the same order of magnitude as the block time).</p> <h2 id="specification">Specification</h2> <p>This specification follows the notation introduced by the <a rel="external" href="https://ethereum.github.io/yellowpaper">Yellow Paper</a>. Prior to reading it is advisable to be familiar with the Yellow Paper.</p> <h3 id="binary-tries">Binary tries</h3> <p>This EIP assumes that a binary trie is defined like the MPT, except that:</p> <ul> <li>The series of bytes in I₀ is seen as a series of <em>bits</em> and so ∀i≤256, I₀[i] is the ith bit in key I₀</li> <li>The first item of an <strong>extension</strong> or a <strong>leaf</strong> is replacing nibbles with bits;</li> <li>A <strong>branch</strong> is a 2 item structure in which both items correspond to each of the two possible bit values for the keys at this point in their traversal;</li> <li>c(𝕴,i) ≡ RLP((u(0), u(1)) at a branch, where u(j) = n({I : I ∈ 𝕴 ⋀ I₀[i] = j}, i+1)</li> </ul> <p>Let ß be the function that, given a hexary trie, computes the equivalent representation of that trie in the aforementioned binary trie format.</p> <h3 id="phase-1">Phase 1</h3> <p>Let <em>h₁</em> be the previously agreed-upon block height at which phase 1 starts, and <em>h₂</em> the block at which phase 2 starts. For each block of height h₁ ≤ <em>h</em> &lt; h₂:</p> <ol start="0"> <li>A conversion process is started in the background, to turn the hexary trie into its binary equivalent. The end goal of this process is the calculation of the <em>root hash of the converted binary trie</em>, denoted Hᵣ². The root of the hexary trie is hereafter called Hᵣ¹⁶. Formally, this process is written as Hᵣ² ≡ ß(Hᵣ¹⁶).</li> <li>Block headers contain a new Hₒ field, which is the <em>root of the overlay binary trie</em>;</li> <li>Hᵣ ≡ P(H)ᵣ¹⁶, i.e. as long as the conversion from hexary to binary is not complete, the hexary trie root is the same as that of its parent block.</li> </ol> <p>The following is changed in the execution environment:</p> <ul> <li>Upon executing a <em>state read</em>, ϒ first searches for the address in the overlay trie. If the key can not be found there, ϒ then searches the base trie as it did at block heights h' &lt; h₁;</li> <li>Upon executing a <em>state write</em>, ϒ inserts or updates the value into the overlay tree. The base tree is left untouched;</li> <li>If an account is deleted, ϒ inserts the empty hash H(∅) at the address of that account in order to mark its deletion; reads from such an address behave the same as a missing account, regardless of what is present in the base trie.</li> </ul> <p>Phase 1 ends at block height h₂, which is set far enough from h₁ to offer miners enough time to perform the conversion.</p> <h3 id="phase-2">Phase 2</h3> <p>This phase differs from the previous one on the following points:</p> <ul> <li>At block height h₂, before the execution of ϒ, Hᵣ ≡ Hᵣ², i.e. the value before the execution of the transition function is set to the root of the converted <em>binary base trie</em>;</li> <li>Hₒ is still present in the block tree, however the overlay trie content can only be <em>read from or deleted</em>;</li> <li>At block height h ≥ h₂, before the execution of ϒ, N accounts are being deleted from the binary overlay trie and inserted into the binary base trie;</li> <li>Upon executing a <em>state write</em>, ϒ will insert or update the value into the <em>base</em> trie. If the search key exists in the overlay trie, it is deleted.</li> </ul> <p>Account deletion is performed according to the following rules:</p> <ul> <li>The first N accounts (in lexicographic order) remaining in the overlay tree are selected; For each of these accounts:</li> <li>If the value is the empty hash, remove the account at the same address from the binary base trie;</li> <li>Otherwise, insert/update the account at the corresponding address in the base trie with its overlay trie value.</li> </ul> <p>When the overlay trie is empty, phase 2 ends and phase 3 begins.</p> <h3 id="phase-3">Phase 3</h3> <p>Phase 3 is the same as phase 2, except for the following change:</p> <ul> <li>Hₒ is dropped from the block header</li> </ul> <h2 id="rationale">Rationale</h2> <p>Methods that have been discussed until now include a "stop the world" approach, in which the chain is stopped for the significant amount of time that is required by the conversion, and a "copy on write" approach, in which branches are converted upon being accessed. The approach suggested here has the advantage that the chain continues to operate normally during the conversion process, and that the tree is fully converted to a binary format, in a predictable time.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This requires a fork and will break backwards compatibility, as the hashes and block formats will necessarily be different. This will cause a fork in clients that don't implement the overlay tree, and those that do not accept the new binary root. No mitigation is proposed, as this is a hard fork.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li>For testing phase 1, it suffices to check that every key in the hexary trie is also available in the binary trie. A looser but faster test picks 1% of keys in the hexary trie at random, and checks that they are present in the binary trie;</li> <li>TBD for phase 2 &amp; 3</li> </ul> <h2 id="implementation">Implementation</h2> <p>A prototype version of the conversion process (phase 1) is available for <code>geth</code> in <a rel="external" href="https://github.com/holiman/go-ethereum/pull/12">this PR</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are three attack vectors that I can foresee:</p> <ul> <li>A targeted attack that would cause the overlay trie to be unreasonably large. Since gas costs will likely increase during the transition process, lengthening phase 2 will make Ethereum more expensive during an extended period of time. This could be solved by increasing the cost of <code>SSTORE</code> during phase 1.</li> <li>Conversely, if h₂ comes too soon, a majority of miners might not be able to produce the correct value for Hᵣ² in time.</li> <li>If a group of miners representing more than 51% of the network are reporting an invalid value, they could be stealing funds without anyone having a say.</li> </ul> <h2 id="community-feedback">Community feedback</h2> <ul> <li>Preliminary tests indicate that a fast machine can perform the conversion in roughly 30 minutes.</li> <li>The initial version of this EIP expected miners to vote on the value of the binary base root. This has been removed because of the complexity of this process, and because this functionality is already guaranteed by the "longest chain" rule.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-03-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Hua Zhanghttps://github.com/dgczhh Yuefei Tanhttps://github.com/whtyfhas Derek Zhouhttps://github.com/zhous Ran Xinghttps://github.com/lemontreeran https://wg-eips.ritovision.com/2569/

A set of interfaces to save an SVG image in Ethereum, and to retrieve the image file from Ethereum for universal tokens.

<h2 id="abstract">Abstract</h2> <p>This set of interfaces allow a smart contract to save an SVG image in Ethereum and to retrieve an SVG image from Ethereum for fungible tokens, non-fungible tokens and tokens based on standards that will be developed in the future.</p> <p>The interface set has two interfaces: one to save an SVG file in Ethereum and the other to retrieve an SVG file from Ethereum.</p> <p>Typical applications include but not limited to:</p> <ul> <li>A solution for storage of a fungible token's icon.</li> <li>A solution for storage of a non-fungible token's icon.</li> <li>A solution for storage of the icon/logo of a DAO's reputation token.</li> </ul> <h2 id="motivation">Motivation</h2> <p>The ERC-721 token standard is a popular standard to define a non-fungible token in Ethereum. This standard is widely used to specify a crypto gift, crypto medal, crypto collectible etc. The most famous use case is the <a rel="external" href="https://www.cryptokitties.co/">cryptokitty</a>.</p> <p>In most of these applications an image is attached to an ERC-721 token. For example, in the cryptokitty case each kitty has a unique image. While the token's code is saved in Ethereum permanently, the image attached to the token is not.</p> <p>The existing solutions still keep such an image in a centralized server instead of Ethereum. When these applications display an image for a token they retrieve the token's information from Ethereum and search the centralized server for the token's associated image by using the token's information.</p> <p>Although this is an applicable way to display an image for a token, the image is still vulnerable to risks of being damaged or lost when saved in a centralized server.</p> <p>Hence we propose a set of interfaces to save an image for a universal token in Ethereum to keep the image permanent and tamper-resistant, and to retrieve an image for a universal token from Ethereum.</p> <h2 id="specification">Specification</h2> <p>An EIP-2569 compatible contract MUST have a method with the signature getTokenImageSvg(uint256) view returns (string memory) and a method with the signature setTokenImageSvg(uint256 tokenId, string memory imagesvg) internal.</p> <p>These methods define how a smart contract saves an image for a universal token in Ethereum which keeps the image permanent and tamper-resistant, and how a smart contract retrieves an image from Ethereum for a universal token.</p> <p>By calling the methods users should access an SVG image.</p> <ul> <li>getTokenImageSvg(uint256 tokenId) external view returns (string memory): for an ERC-721 or ERC-1155 token or a token implemented by a contract which has a member "ID" to specify its token type or token index we define an interface to get an SVG image by using the token's ID number. For an ERC-20 token or a token implemented by a contract which doesn't have a member "ID" to specify its token type or token index we define an interface to get an SVG image for it if the token has a member variable string to save the image.</li> </ul> <p>It has the following parameter:</p> <p>tokenId: for a non-fungible token such as an ERC-721 token or a multi-token such as an ERC-1155 token which has a member "ID" to specify its token type or token index our proposed interface assigns an SVG image's file content to a string variable of the token's contract and associates the SVG image to this "ID" number. This unique ID is used to access its SVG image in both a "set" operation and a "get" operation. For a fungible token such as an ERC-20 token no such an ID is needed and our proposed interface just assigns an SVG image's file content to a string variable of the token's contract.</p> <ul> <li>setTokenImageSvg(uint256 tokenId, string memory imagesvg) internal: for an ERC-721 or ERC-1155 token or a token implemented by a contract which has a member "ID" to specify its token type or token index we define an interface to associate an SVG image to the token's ID number. For an ERC-20 token or a token implemented by a contract which doesn't have a member "ID" to specify its token type or token index we define an interface to assign an SVG image to a member variable string of this token's contract.</li> </ul> <p>It has the following two parameters:</p> <p>tokenId: for a non-fungible token such as an ERC-721 token or a multi-token such as an ERC-1155 token which has a member "ID" to specify its token type or token index our proposed interface assigns an SVG image's file content to a string variable of the token's contract and associates the SVG image to this "ID" number. This unique ID is used to access its SVG image in both a "set" operation and a "get" operation. For a fungible token such as an ERC-20 token no such an ID is needed and our proposed interface just assigns an SVG image's file content to a string variable of the token's contract.</p> <p>imageSvg: we use a string variable to save an SVG image file's content. An SVG image that will be saved in the imageSvg string should include at least two attributes:"name", "desc"(description).</p> <p>The procedure to save an image for a token in Ethereum is as follows:</p> <p><strong>Step1:</strong> define a string variable or an array of strings to hold an image or an array of images.</p> <p><strong>Step 2:</strong> define a function to set an (SVG) image's file content or an array of image file's contents to the string variable or the array of strings.</p> <p>Step 1: for a token such as an ERC-721 or ERC-1155 token which has a member variable "ID" to specify a token type or index and a member variable string to keep an (SVG) image associated with the "ID", retrieve the (SVG) image from Ethereum by calling our proposed "get" interface with the token's ID; for a token which doesn't have a member variable "ID" to specify a token type of index but has a member variable string to keep an (SVG) image, retrieve the (SVG) image from Ethereum by calling our proposed "get" without an "ID".</p> <h2 id="rationale">Rationale</h2> <p>After Bitcoin was created people have found ways to keep information permanent and tamper-resistant by encoding text messages they want to preserve permanently and tamper-resistantly in blockchain transactions. However existing applications only do this for text information and there are no solutions to keep an image permanent and tamper-resistant.</p> <p>One of the most significant reasons for not doing so is that in general the size of an image is much bigger than the size of a text file, thus the gas needed to save an image in Ethereum would exceed a block's gas limit.</p> <p>However this changed a lot after the SVG(Scalable Vector Graphics) specification was developed by W3C since 1999.</p> <p>The SVG specification offers several advantages (for more details about the advantages please refer to a reference link:https://en.wikipedia.org/wiki/Scalable_Vector_Graphics) over raster images. One of these advantages is its compact file-size.</p> <p>"Compact file-size – Pixel-based images are saved at a large size from the start because you can only retain the quality when you make the image smaller, but not when you make it larger. This can impact a site’s download speed. Since SVGs are scalable, they can be saved at a minimal file size".</p> <p>This feature well fixes the painpoint of saving an image file in Ethereum, therefore we think saving an SVG image in Ethereum is a good solution for keep the image permanent and tamper-resistant.</p> <p>In most ERC-721 related DAPPs they display an image for a non-fungible token. In most ERC-20 related DAPPs they don't have an image for a fungible token. We think displaying an image for a token either based on existing token standards such as ERC-20, ERC-721, ERC-1155 or based on future standards is needed in many use cases. Therefore those DAPPs which currently don't display an image for a token will eventually need such a function.</p> <p>However with regard to most of the existing DAPPs which can display an image for a token they save such an image in a centralized server which, we think, is just a compromised solution. By utilizing the SVG specification we think converting a token's image to an SVG image and saving it in Ethereum provides a better solution for DAPPs to access an image for a token.</p> <p>This solution not only works for tokens based on ERC-721, ERC-1155 and ERC-20 but will work for tokens based on future standards.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backward compatibility issues.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p><code>tokenId</code>: a token index in an ERC-721 token or a token type/index in an ERC-1155 token. It is a uint256 variable.</p> <p><code>imageSvg</code>: an SVG image's file content. It is a string variable. Note: the SVG image should include at least three attributes:"name", "description" and "issuer".</p> <p><code>setTokenImageSvg</code>: interface to set an SVG image to a token with or without an ID number.</p> <p><code>getTokenImageSvg</code>: interface to get an SVG image for a token with or without an ID number.</p> <p>We propose to add three sol files in the existing ERC-721 implementation. Here are the details for the proposed sol files.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ----- IERC721GetImageSvg.sol -------------------------</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC721/IERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-721 Non-Fungible Token Standard, optional retrieving SVG image extension</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See https://eips.ethereum.org/EIPS/eip-721</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> IERC721GetImageSvg</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC721</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenImageSvg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ----- ERC721GetImageSvg.sol -------------------------</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/GSN/Context.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC721/./ERC721.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/introspection/ERC165.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC721GetImageSvg.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC721GetImageSvg</span><span class="z-storage"> is</span><span class="z-entity z-name"> Context</span><span>, </span><span class="z-entity z-name">ERC165</span><span>, </span><span class="z-entity z-name">ERC721</span><span>, </span><span class="z-entity z-name">IERC721GetImageSvg</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mapping for token Images</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> string</span><span>)</span><span class="z-storage z-type"> private</span><span> _tokenImageSvgs</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;getTokenImageSvg(uint256)&#39;)) == 0x87d2f48c</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * =&gt; 0x87d2f48c == 0x87d2f48c</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _INTERFACE_ID_ERC721_GET_TOKEN_IMAGE_SVG </span><span class="z-keyword">=</span><span class="z-constant"> 0x87d2f48c</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Constructor function</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span> (</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> register the supported interfaces to conform to ERC721 via ERC165</span></span> <span class="giallo-l"><span class="z-entity z-name"> _registerInterface</span><span>(</span><span>_INTERFACE_ID_ERC721_GET_TOKEN_IMAGE_SVG</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns an SVG Image for a given token ID.</span></span> <span class="giallo-l"><span class="z-comment"> * Throws if the token ID does not exist. May return an empty string.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> uint256 ID of the token to query</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenImageSvg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC721GetImageSvg: SVG Image query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _tokenImageSvgs</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Internal function to set the token SVG image for a given token.</span></span> <span class="giallo-l"><span class="z-comment"> * Reverts if the token ID does not exist.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> uint256 ID of the token to set its SVG image</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> imagesvg</span><span class="z-comment"> string SVG to assign</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setTokenImageSvg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> imagesvg</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC721GetImageSvg: SVG image set of nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _tokenImageSvgs</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span> imagesvg</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ----- ERC721ImageSvgMintable.sol -------------------------</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC721/ERC721Metadata.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/access/roles/MinterRole.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ERC721GetImageSvg.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC721ImageSvgMintable</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> ERC721 minting logic with imagesvg.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC721ImageSvgMintable</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC721</span><span>, </span><span class="z-entity z-name">ERC721Metadata</span><span>, </span><span class="z-entity z-name">ERC721GetImageSvg</span><span>, </span><span class="z-entity z-name">MinterRole</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to mint tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> to</span><span class="z-comment"> The address that will receive the minted tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The token id to mint.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenImageSvg</span><span class="z-comment"> The token SVG image of the minted token.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintWithTokenImageSvg</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenImageSvg</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyMinter</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _mint</span><span>(</span><span>to</span><span>,</span><span> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> setTokenImageSvg</span><span>(</span><span>tokenId</span><span>,</span><span> tokenImageSvg</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>We propose to add three sol files in the existing ERC</span><span class="z-keyword">-</span><span class="z-constant">1155</span><span> implementation</span><span>.</span></span> <span class="giallo-l"><span>Here are the details </span><span class="z-keyword">for</span><span> the proposed sol files</span><span>.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ----- IERC1155GetImageSvg.sol -------------------------</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC1155.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-1155 Multi Token Standard, retrieving SVG image for a token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See https://github.com/ethereum/EIPs/blob/master/EIPS/./01155.md</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> IERC1155GetImageSvg</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC1155</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenImageSvg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ----- ERC1155GetImageSvg.sol -------------------------</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ERC1155.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC1155GetImageSvg.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC1155GetImageSvg</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC165</span><span>, </span><span class="z-entity z-name">ERC1155</span><span>, </span><span class="z-entity z-name">IERC1155GetImageSvg</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mapping for token Images</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> string</span><span>)</span><span class="z-storage z-type"> private</span><span> _tokenImageSvgs</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * bytes4(keccak256(&#39;getTokenImageSvg(uint256)&#39;)) == 0x87d2f48c</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * =&gt; 0x87d2f48c == 0x87d2f48c</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> private</span><span class="z-storage z-type"> constant</span><span> _INTERFACE_ID_ERC1155_GET_TOKEN_IMAGE_SVG </span><span class="z-keyword">=</span><span class="z-constant"> 0x87d2f48c</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Constructor function</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span> (</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> register the supported interfaces to conform to ERC1155 via ERC165</span></span> <span class="giallo-l"><span class="z-entity z-name"> _registerInterface</span><span>(</span><span>_INTERFACE_ID_ERC1155_GET_TOKEN_IMAGE_SVG</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns an SVG Image for a given token ID.</span></span> <span class="giallo-l"><span class="z-comment"> * Throws if the token ID does not exist. May return an empty string.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> uint256 ID of the token to query</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenImageSvg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC1155GetImageSvg: SVG Image query for nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _tokenImageSvgs</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Internal function to set the token SVG image for a given token.</span></span> <span class="giallo-l"><span class="z-comment"> * Reverts if the token ID does not exist.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> uint256 ID of the token to set its SVG image</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> imagesvg</span><span class="z-comment"> string SVG to assign</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setTokenImageSvg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> imagesvg</span><span>)</span><span class="z-storage z-type"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>,</span><span class="z-string"> &quot;ERC1155GetImageSvg: SVG image set of nonexistent token&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> _tokenImageSvgs</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span> imagesvg</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ----- ERC1155MixedFungibleWithSvgMintable.sol -------------------------</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ERC1155MixedFungibleMintable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ERC1155GetImageSvg.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> Mintable form of ERC1155 with SVG images</span></span> <span class="giallo-l"><span class="z-comment"> Shows how easy it is to mint new items with SVG images</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC1155MixedFungibleWithSvgMintable</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC1155</span><span>, </span><span class="z-entity z-name">ERC1155MixedFungibleMintable</span><span>, </span><span class="z-entity z-name">ERC1155GetImageSvg</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to mint non-fungible tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address that will receive the minted tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _type</span><span class="z-comment"> The token type to mint.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenImageSvg</span><span class="z-comment"> The token SVG image of the minted token.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintNonFungibleWithImageSvg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _type</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenImageSvg</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> creatorOnly</span><span>(</span><span class="z-entity z-name">_type</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> mintNonFungible</span><span>(</span><span>_type</span><span>,</span><span> _to</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> setTokenImageSvg</span><span>(</span><span>_type</span><span>,</span><span> tokenImageSvg</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to mint fungible tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address that will receive the minted tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> The token type to mint.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _quantities</span><span class="z-comment"> The number of tokens for a type to mint.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenImageSvg</span><span class="z-comment"> The token SVG image of the minted token.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mintFungibleWithImageSvg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _quantities</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> tokenImageSvg</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> creatorOnly</span><span>(</span><span class="z-entity z-name">_id</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> mintFungible</span><span>(</span><span>_id</span><span>,</span><span> _to</span><span>,</span><span> _quantities</span><span>,</span><span> tokenImageSvg</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> setTokenImageSvg</span><span>(</span><span>_id</span><span>,</span><span> tokenImageSvg</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>We propose to add three sol files in the existing ERC</span><span class="z-keyword">-</span><span class="z-constant">20</span><span> implementation</span><span>.</span></span> <span class="giallo-l"><span>Here are the details </span><span class="z-keyword">for</span><span> the proposed sol files</span><span>.</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ----- IERC20GetImageSvg.sol -------------------------</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC20/IERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-20 Fungible Token Standard, retrieving SVG image for a token</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/token/ERC20/ERC20.sol</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> IERC20GetImageSvg</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenImageSvg</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> ----- ERC20GetImageSvg.sol -------------------------</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;@openzeppelin/contracts/token/ERC20/ERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./IERC20GetImageSvg.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC20GetImageSvg</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20</span><span>, </span><span class="z-entity z-name">IERC20GetImageSvg</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> private</span><span> _tokenImageSvg</span><span>;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment">将图片实现写在构造器中</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> svgCode</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span>_tokenImageSvg </span><span class="z-keyword">=</span><span> svgCode</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns an SVG Image.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenImageSvg</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _tokenImageSvg</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span></code></pre><h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-03-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Joseph Stockermanshttps://github.com/jstoxrocky https://wg-eips.ritovision.com/2566/ <h2 id="simple-summary">Simple Summary</h2> <p>New Ethereum RPC method <code>eth_sendTransactionToContractFunction</code> that parallels <code>eth_sendTransaction</code> but allows for human-readable contract function execution data to be displayed to users.</p> <h2 id="abstract">Abstract</h2> <p>When a dapp prompts a user to execute a smart contract function via a ProviderWallet, confirmation screens displayed in the ProviderWallet layer cannot display the human readable details of the function to be called and the arguments to be passed. This is because the Ethereum RPC method used for contract function execution (<code>eth_sendTransaction</code>) accepts information about what function to call in a non-human readable (and non-recoverable) format. As such, when a ProviderWallet receives this non-human readable information from a dapp, they are unable to display a human readable version since they never received one and cannot recover one from the data.</p> <p>This creates a poor and potentially dangerous user experience. For example, a malicious dapp could swap out the <code>address</code> argument in a token contract's <code>transfer(address,uint256)</code> function and reroute the tokens intended for someone else to themselves. This sleight-of-hand would be quiet and unlikely to be picked up by a casual user glancing over the non-human readable data. By adding a new Ethereum RPC method (<code>eth_sendTransactionToContractFunction</code>) that accepts the function ABI, ProviderWallets can recreate and display the human readable details of contract function execution to users.</p> <h2 id="motivation">Motivation</h2> <h3 id="providerwallet-definition">ProviderWallet Definition</h3> <p>ProviderWallets like Metamask and Geth are hybrid software that combine an Ethereum API provider with an Ethereum wallet. This allows them to sign transactions on behalf of their users and also broadcast those signed transactions to the Ethereum network. ProviderWallets are used for both convenience and for the protection they give users through human readable confirmation prompts.</p> <h3 id="existing-solutions">Existing Solutions</h3> <p>Much discussion has been made in the past few years on the topic of human readable Ethereum transaction data. Aragon's <a rel="external" href="https://github.com/aragon/radspec">Radspec</a> addresses this issue by requiring contract developers to amend their contract functions with human readable comments. ProviderWallets can then use Aragon's Radspec software to parse these comments from the contract code and display them to the end user - substituting in argument values where necessary. Unfortunately, this approach cannot work with contracts that do not have Radspec comments (and may require integration with IPFS).</p> <p><a rel="external" href="https://github.com/ethereum/EIPs/issues/1138">EIP 1138</a> also addresses this issue directly but contains serious security issues - allowing untrusted dapps to generate the human readable message displayed to users. In a similar train of thought, <a rel="external" href="https://github.com/ethereum/go-ethereum/pull/2940">Geth's #2940 PR</a> and <a rel="external" href="https://github.com/ethereum/EIPs/blob/master/EIPS/./00191.md">EIPs 191</a>, <a rel="external" href="https://github.com/ethereum/EIPs/blob/master/EIPS/./00712.md">712</a> all highlight the Ethereum community's desire for ProviderWallets to better inform users about what data they are actually acting upon.</p> <p>Finally, the ProviderWallet Metamask already includes some built-in magic for interactions with ERC20 contracts that allows confirmation prompts to display the intended <em>token</em> recipient and <em>token</em> value. Although this is accomplished in an ad hoc fashion for ERC20-like contracts only, the motivation is the same: users deserve better information about the execution of contract functions they are relying on ProviderWallets to perform.</p> <h3 id="background">Background</h3> <p>At one point or another, a dapp will ask a user to interact with a contract. The interaction between dapps and contracts is a large part of the Ethereum ecosystem and is most commonly brokered by a ProviderWallet. When a dapp asks a user to interact with a contract, it will do so by sending the <code>eth_sendTransaction</code> method name to the Ethereum API exposed by a ProviderWallet along with the relevant transaction data. The <code>data</code> field of the transaction data contains the information necessary for the Ethereum virtual machine to identify and execute the contract's function. This field has a specific formatting that is both non-human readable and non-recoverable to its human readable state.</p> <p>The accepted format for <code>eth_sendTransaction</code>'s <code>data</code> field is the hexadecimal encoding of the first four bytes of the keccak256 digest of the function signature. This abbreviated hash is then concatenated with the ABI encoded arguments to the function. Since the keccak256 digest of the function signature cannot be converted back into the function signature, the <code>data</code> field is not only non-human readable, its non-recoverable as well. On top of this, additional insight into the concatenated argument values is further obfuscated as information about their data types are held in the function signature preimage.</p> <h2 id="specification">Specification</h2> <p>This EIP proposes increasing the set of Ethereum RPC methods to include a new method - <code>eth_sendTransactionToContractFunction</code>. This method parallels <code>eth_sendTransaction</code> with the only difference being the inclusion of the contract function's <code>abi</code> field.</p> <p>Parameters</p> <ol> <li><code>Object</code> - The transaction object</li> </ol> <ul> <li><code>from</code>: <code>DATA</code>, 20 Bytes - The address the transaction is sent from.</li> <li><code>to</code>: <code>DATA</code>, 20 Bytes - (optional when creating new contract) The address the transaction is directed to.</li> <li><code>gas</code>: <code>QUANTITY</code> - (optional, default: 90000) Integer of the gas provided for the transaction execution. It will return unused gas.</li> <li><code>gasPrice</code>: <code>QUANTITY</code> - (optional, default: To-Be-Determined) Integer of the gasPrice used for each paid gas</li> <li><code>value</code>: <code>QUANTITY</code> - (optional) Integer of the value sent with this transaction</li> <li><code>data</code>: <code>DATA</code> - The hash of the invoked method signature and encoded parameters</li> <li><code>abi</code>: <code>DATA</code> - The function ABI</li> <li><code>nonce</code>: <code>QUANTITY</code> - (optional) Integer of a nonce. This allows to overwrite your own pending transactions that use the same nonce.</li> </ul> <p>Example Parameters</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> params: [{</span></span> <span class="giallo-l"><span> &quot;from&quot;: &quot;0x69e6F1b01f34A702Ce63bA6EF83c64fAEC37a227&quot;,</span></span> <span class="giallo-l"><span> &quot;to&quot;: &quot;0xe44127f6fA8A00ee0228730a630fc1F3162C4d52&quot;,</span></span> <span class="giallo-l"><span> &quot;gas&quot;: &quot;0x76c0&quot;, // 30400</span></span> <span class="giallo-l"><span> &quot;gasPrice&quot;: &quot;0x9184e72a000&quot;, // 10000000000000</span></span> <span class="giallo-l"><span> &quot;value&quot;: &quot;0x9184e72a&quot;, // 2441406250</span></span> <span class="giallo-l"><span> &quot;abi&quot;: &quot;{</span></span> <span class="giallo-l"><span> &quot;inputs&quot;: [{</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;_address&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;address&quot;</span></span> <span class="giallo-l"><span> }, {</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;_value&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;uint256&quot;</span></span> <span class="giallo-l"><span> }],</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;transferTokens&quot;,</span></span> <span class="giallo-l"><span> &quot;outputs&quot;: [{</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;success&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;bool&quot;</span></span> <span class="giallo-l"><span> }],</span></span> <span class="giallo-l"><span> &quot;stateMutability&quot;: &quot;nonpayable&quot;,</span></span> <span class="giallo-l"><span> &quot;type&quot;: &quot;function&quot;</span></span> <span class="giallo-l"><span> }&quot;,</span></span> <span class="giallo-l"><span> &quot;data&quot;: &quot;0xbec3fa170000000000000000000000006Aa89e52c9a826496A8f311c1a9db62fd477E256000000000000000000000000000000000000000000000000000000174876E800&quot; </span></span> <span class="giallo-l"><span> }]</span></span></code></pre> <p>Returns DATA, 32 Bytes - the transaction hash, or the zero hash if the transaction is not yet available.</p> <p>Example // Request curl -X POST --data '{"jsonrpc":"2.0","method":"eth_sendTransactionToContractFunction","params":[{see above}],"id":1}'</p> <p>// Result { "id":1, "jsonrpc": "2.0", "result": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" }</p> <h2 id="rationale">Rationale</h2> <p>This EIP's proposed <code>eth_sendTransactionToContractFunction</code> method is intended to parallel <code>eth_sendTransaction</code> as much as possible since both methods result in the same behaviour when executing a contract function. The newly introduced <code>abi</code> field is an element of the contract's ABI that corresponds to the intended function. The <code>data</code> field is the same <code>data</code> field from <code>eth_sendTransaction</code>. The <code>abi</code> field can be combined with values parsed from the <code>data</code> field to recreate human readable contract function execution information.</p> <h2 id="implementation">Implementation</h2> <p>The <code>data</code> field in <code>eth_sendTransactionToContractFunction</code> is the same as that required for <code>eth_sendTransaction</code> allowing the transaction to be completed via the existing mechanisms used for <code>eth_sendTransaction</code>. The input argument values can be parsed from the <code>data</code> field and since we know their types from the <code>abi</code> field, the provider wallet can use this info to encode and display the values in an appropriate human readable format. Furthermore, the hashed and truncated function signature in the <code>data</code> field can be reconstructed using the information provided in the <code>abi</code> field providing an additional check to ensure that the supplied ABI matches the <code>data</code> field.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>With backwards compatibility in mind, this EIP proposes augmenting the set of Ethereum RPC methods with an additional method instead of mutating the existing method. Precedent for adding a new RPC method comes from <a rel="external" href="https://github.com/ethereum/EIPs/blob/master/EIPS/./00712.md">EIP 712</a> in which adding the method <code>eth_signTypedData</code> is proposed for confirmation prompt security. As an alternate approach, the <code>eth_sendTransaction</code> method could be changed to accept an additional <code>abi</code> argument, but this would break all existing code attempting to execute a contract function.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Displaying the contract address, function name, and argument values can provide additional security to users, but it is not a guarantee that a function will execute as the user expects. A poorly implemented contract can still name its function <code>transfer</code> and accept <code>address</code> and <code>uint256</code> arguments - but there is nothing short of contract examination that will let a user know that this contract is indeed a valid ERC20 contract. This EIP does not intend to solve the larger problem around trust in a contract's code, but instead intends to give users better tools to understand exactly what is contained within the data they are broadcasting to the Ethereum network.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-03-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 Dan Finlaydan@danfinlay.com https://wg-eips.ritovision.com/2593/ <h2 id="simple-summary">Simple Summary</h2> <p>The current "first price auction" fee model in Ethereum is inefficient and needlessly costly to users. This EIP proposes a way to replace this with a mechanism that allows dynamically priced transaction fees and efficient transaction price discovery.</p> <h2 id="abstract">Abstract</h2> <p>Based on <a rel="external" href="https://agoric.com/papers/incentive-engineering-for-computational-resource-management/full-text/">The Agoric Papers</a>.</p> <p>Each transaction would have the option of providing parameters that specify an "escalating" bid, creating a time-based auction for validators to include that transaction.</p> <p>This creates highly efficient price discovery, where the price will always immediately fall to the highest bid price, which is not necessarily that user's highest price they would pay.</p> <p><img src="https://ethresear.ch/uploads/default/original/2X/0/042795efa4c2680d644bc66386cd2984a70293f8.gif" alt="escalator algorithm price chart" /></p> <h2 id="motivation">Motivation</h2> <p>Ethereum currently prices transaction fees using a simple first-price auction, which leads to well documented inefficiencies (some of which are documented in <a rel="external" href="https://github.com/ethereum/EIPs/blob/master/EIPS/./01559.md">EIP-1559</a>) when users are trying to estimate what price will get a transaction included in a block, especially during times of price volatility and full blocks.</p> <p>EIP 1559 is currently being championed as an improvement for the Ethereum protocol, and while I agree that the gas market is very inefficient, since a change like this will affect all client and wallet implementations, the Ethereum community should make sure to make a selection based on solid reasoning and justifications, which I believe 1559 is currently lacking.</p> <p>To facilitate a more productive and concrete discussion about the gas fee market, I felt it was important to present an alternative that is clearly superior to the status quo, so that any claimed properties of EIP-1559 can be compared to a plausible alternative improvement.</p> <p>I suggest the three gas payment algorithms be compared under all combinations of these conditions:</p> <ul> <li>Blocks that are regularly half full, Blocks that are regularly less than half full, and blocks that repeatedly full in a surprising ("black swan") series.</li> <li>Users that are willing to wait for a price that may be below the market rate, vs users who value inclusion urgently and are willing to pay above market rate.</li> </ul> <p>We should then ask:</p> <ul> <li>Is the user willing to pay the most in a given scenario also likely to have their transaction processed in a time period they find acceptable?</li> <li>Are users who want a good price likely to get included in a reasonable period of time? (Ideally within one block)</li> </ul> <p>I believe that under this analysis we will find that the escalator algorithm outperforms EIP-1559 in both normal and volatile conditions, for both high-stakes transactions and more casual users looking for a good price.</p> <p>While I think a deeper simulation/analysis should be completed, I will share my expected results under these conditions.</p> <p>Furthermore, by introducing tx fee payment related to the current time, we create an incentive for miners to more honestly report the current time.</p> <h3 id="user-strategies-under-various-conditions-and-algorithms">User Strategies Under Various Conditions and Algorithms</h3> <p>First I will suggest a likely optimal strategy for different players under the conditions of the different algorithms being considered.</p> <table><thead><tr><th>Gas Strategy</th><th>Current Single-Price</th><th>EIP 1559</th><th>Escalator</th></tr></thead><tbody> <tr><td>Blocks regularly half full, user wants urgent inclusion.</td><td>User bids within the range of prices that have been recently accepted, likely over-pays slightly.</td><td>User bids one price tier over the current rate, and is likely included.</td><td>User bids a range from the low end of recently included to the high end, and is likely included at the lowest rate possible.</td></tr> <tr><td>Blocks regularly half full, user willing to wait for a good price.</td><td>User bids below or near the low end of the recently accepted prices, may need to wait for a while. If waiting too long, user may need to re-submit with a higher price.</td><td>User bids under or at the current price tier, and may wait for the price to fall. If waiting too long, user may need to re-submit with a higher price.</td><td>User bids as low as they'd like, but set an upper bound on how long they're willing to wait before increasing price.</td></tr> <tr><td>Blocks regularly full, user wants urgent inclusion.</td><td>User bids over the price of all recently accepted transactions, almost definitely over-paying significantly.</td><td>User bids over the current price tier, and needs to increase their <code>tip</code> parameter to be competitive on the next block, recreating the single-price auction price problem.</td><td>User bids over a price that has been accepted consistently, with an escalating price in case that price is not high enough.</td></tr> <tr><td>Blocks regularly full, user willing to wait for a good price.</td><td>User bids below the low end of the recently accepted prices, may need to wait for a while. If waiting too long, user may need to re-submit with a higher price.</td><td>User bids under or at the current price tier, and may wait for the price to fall. If waiting too long, user may need to re-submit with a higher price.</td><td>User bids as low as they'd like, but set an upper bound on how long they're willing to wait before increasing price.</td></tr> <tr><td>Blocks regularly under-full, user wants urgent inclusion.</td><td>User bids within or over the range of prices that have been recently accepted, likely over-pays slightly, and is likely included in the next block.</td><td>User bids at or over the current price tier, and is likely included in the next block.</td><td>User submits bid starting within recently accepted prices, is likely accepted in the next block.</td></tr> <tr><td>Blocks regularly under-full, user willing to wait for a good price.</td><td>User bids below the low end of the recently accepted prices, may need to wait for a while. If waiting too long, user may need to re-submit with a higher price.</td><td>User bids at or under the current price tier, and is likely included in the next block. If bidding under and waiting too long, user may need to re-submit with a higher price.</td><td>User bids as low as they'd like, but set an upper bound on how long they're willing to wait before increasing price, is likely included in the next few blocks at the lowest possible price.</td></tr> </tbody></table> <h3 id="user-results-under-various-conditions-and-algorithms">User Results Under Various Conditions and Algorithms</h3> <p>Now I will consider the ultimate results of the strategies listed above. Are users happy under these conditions? Did we save users money? Were users who wanted urgent inclusion able to secure it?</p> <table><thead><tr><th>Gas Strategy</th><th>Current Single-Price</th><th>EIP 1559</th><th>Escalator</th></tr></thead><tbody> <tr><td>Blocks regularly half full, user wants urgent inclusion.</td><td>User pays an expected amount, and gets transaction mined reliably.</td><td>User pays an expected amount, and gets transaction mined reliably.</td><td>User pays an expected amount, and gets transaction mined reliably.</td></tr> <tr><td>Blocks regularly half full, user willing to wait for a good price.</td><td>User can wait for a better price, but may need to resubmit re-signed transactions.</td><td>User can wait for a better price, but may need to resubmit re-signed transactions.</td><td>User can discover the lowest price within their time preference with a single signature.</td></tr> <tr><td>Blocks regularly full, user wants urgent inclusion.</td><td>User over-pays, but reliably gets transaction included.</td><td>Due to <code>tip</code> parameter "breaking tie" within a block, user over-pays for reliable inclusion.</td><td>User is able to balance the amount of overpayment they risk with the urgency they require.</td></tr> <tr><td>Blocks regularly full, user willing to wait for a good price.</td><td>User chooses their price, and waits for it, or manually re-submits.</td><td>User chooses their price, and waits for it, or manually re-submits.</td><td>User chooses their lowest price, but also their highest price and maximum wait time, so no resubmission is needed.</td></tr> <tr><td>Blocks regularly under-full, user wants urgent inclusion.</td><td>User over-pays, but reliably gets transaction included.</td><td>User bids at or over current price tier, gets transaction mined reliably.</td><td>User pays an expected amount, and gets transaction mined reliably.</td></tr> <tr><td>Blocks regularly under-full, user willing to wait for a good price.</td><td>User bids below the low end of the recently accepted prices, may need to wait for a while. If waiting too long, user may need to re-submit with a higher price.</td><td>User chooses their price, and waits for it, or manually re-submits.</td><td>User chooses their lowest price, but also their highest price and maximum wait time, so no resubmission is needed.</td></tr> </tbody></table> <p>In all cases, the escalator algorithm as I have described is able to perform optimally.</p> <p>The current gas auction model works well under half-full and less conditions, but for users with urgent needs, has the downside of overpayment. For users seeking a low price, the current model has the downside of requiring re-submission, but has the benefit of always giving users a path towards reliable block inclusion.</p> <p>EIP-1559 also performs well under normal conditions, but under conditions where blocks are regularly full, the price discovery mechanism breaks, and miners will fall back to the <code>TIP</code> parameter to choose the transactions to include, meaning that under network congestion, EIP-1559 forces users to <em>either</em> choose efficient prices or certainty of next-block inclusion.</p> <p>EIP-1559 also has all the re-submission issues of the current model in situations where a user would like to pay under the current market rate, but has certain time constraints limiting their patience. The Escalator algorithm is the only strategy listed here that allows users to discover the lowest possible price given the network conditions and their time constraints.</p> <h2 id="specification">Specification</h2> <p><strong>Client-Wide Parameters</strong></p> <ul> <li><code>INITIAL_FORK_BLKNUM</code>: TBD</li> </ul> <p><strong>Transaction Parameters</strong> The transaction <code>gasPrice</code> parameter is now optional, and if excluded can be replaced by these parameters instead:</p> <ul> <li><code>START_PRICE</code>: The lowest price that the user would like to pay for the transaction.</li> <li><code>START_TIME</code>: The first time that this transaction is valid at.</li> <li><code>MAX_PRICE</code>: The maximum price the sender would be willing to pay to have this transaction processed.</li> <li><code>MAX_TIME</code>: The time at which point the user's <code>MAX_PRICE</code> is achieved. The transaction remains valid after this time at that price.</li> </ul> <p><strong>Proposal</strong></p> <p>For all blocks where <code>block.number &gt;= INITIAL_FORK_BLKNUM</code>:</p> <p>When processing a transaction with the new pricing parameters, miners now receive a fee based off of the following linear function, where <code>BLOCK</code> is the current block number:</p> <ul> <li>IF <code>BLOCK &gt; MAX_TIME</code> then <code>TX_FEE = MAX_PRICE</code>.</li> <li><code>TX_FEE = START_PRICE + ((MAX_PRICE - START_PRICE) / (MAX_TIME - START_TIME) * (BLOCK - START_TIME))</code></li> </ul> <p>As a JavaScript function:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> txFee</span><span> (</span><span class="z-variable">startTime</span><span>,</span><span class="z-variable"> startPrice</span><span>,</span><span class="z-variable"> maxTime</span><span>,</span><span class="z-variable"> maxPrice</span><span>,</span><span class="z-variable"> currentTime</span><span>)</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">currentTime</span><span class="z-keyword"> &gt;=</span><span class="z-variable z-other"> maxTime</span><span>)</span><span class="z-keyword"> return</span><span class="z-variable z-other"> maxPrice</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> priceRange</span><span class="z-keyword"> =</span><span class="z-variable z-other"> maxPrice</span><span class="z-keyword"> -</span><span class="z-variable z-other"> startPrice</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> blockRange</span><span class="z-keyword"> =</span><span class="z-variable z-other"> maxTime</span><span class="z-keyword"> -</span><span class="z-variable z-other"> startTime</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> slope</span><span class="z-keyword"> =</span><span class="z-variable z-other"> priceRange</span><span class="z-keyword"> /</span><span class="z-variable z-other"> blockRange</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> startPrice</span><span class="z-keyword"> +</span><span> (</span><span class="z-variable z-other">slope</span><span class="z-keyword"> *</span><span> (</span><span class="z-variable z-other">currentTime</span><span class="z-keyword"> -</span><span class="z-variable z-other"> startTime</span><span>)</span><span>)</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Since a current <code>gasPrice</code> transaction is effectively a flat-escalated transaction bid, it is entirely compatible with this model, and so there is no concrete requirement to deprecate current transaction processing logic, allowing cold wallets and hardware wallets to continue working for the foreseeable future.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>The security considerations for this EIP are:</p> <ul> <li>None currently known.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-03-04T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/3322/ <h2 id="simple-summary">Simple Summary</h2> <p>Allows contract accounts to store gas that can be transferred to the refund counter.</p> <h2 id="abstract">Abstract</h2> <p>Contracts can persist gas for later transfer to the refund counter. Three opcodes are introduced to read, add to, and use this gas counter.</p> <h2 id="motivation">Motivation</h2> <p>The refund mechanism is currently being used by gas tokens to arbitrage gas price. This brings gas supply elasticity and price stability by moving gas from blocks with less demand to blocks with more demand. Unfortunately this rewards unnecessary state growth. By introducing a superior gas storage mechanism, the gas market will require less storage and computation.</p> <h2 id="specification">Specification</h2> <p>Contract accounts gain an unsigned gas refund counter, initially zero.</p> <p>Three new opcodes are introduced to manage this state.</p> <ul> <li><code>SELFGAS</code> (<code>0x49</code>): Pushes the current account's gas refund counter onto the stack. Shares gas pricing with <code>SELFBALANCE</code>.</li> <li><code>USEGAS</code> (<code>0x4a</code>): Pops <code>amount</code> from the stack. The minimum of <code>amount</code> and the current account's gas refund counter is transferred to the execution context's refund counter. Costs <code>5000</code> gas.</li> <li><code>STOREGAS</code> (<code>0x4b</code>): Pops <code>amount</code> from the stack. Costs <code>5000 + amount</code> gas. Increases the current account's gas refund counter by <code>amount</code>.</li> </ul> <h2 id="rationale">Rationale</h2> <p>By reusing the execution context's refund counter we can reuse its 50% DoS protection, which limits its block elasticity contribution to 2x.</p> <p>The gas costs are based on similar opcodes <code>SELFBALANCE</code> and <code>SSTORE</code>.</p> <p>Most accounts will store no gas, so the per-account storage overhead should be minimal or even zero in the normal case.</p> <p>The opcode numbers chosen are in the same <code>0x4X</code> range as <code>SELFBALANCE</code> and <code>GASLIMIT</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Because the gas is added to the refund counter, no compatibility issues are anticipated.</p> <h2 id="test-cases">Test Cases</h2> <table><thead><tr><th>Code</th><th>Used Gas</th><th>Refund</th><th>Original</th><th>Final</th></tr></thead><tbody> <tr><td>0x60004900</td><td>5003</td><td>0</td><td>0</td><td>0</td></tr> <tr><td>0x60034900</td><td>5003</td><td>2</td><td>2</td><td>0</td></tr> <tr><td>0x60034900</td><td>5003</td><td>3</td><td>3</td><td>0</td></tr> <tr><td>0x60034900</td><td>5003</td><td>3</td><td>4</td><td>1</td></tr> <tr><td>0x60034960034900</td><td>10006</td><td>4</td><td>4</td><td>0</td></tr> <tr><td>0x60034960034900</td><td>10006</td><td>6</td><td>6</td><td>0</td></tr> <tr><td>0x484900</td><td>5010</td><td>100000</td><td>100000</td><td>0</td></tr> <tr><td>0x61ffff4a00</td><td>70538</td><td>0</td><td>0</td><td>65535</td></tr> </tbody></table> <h2 id="security-considerations">Security Considerations</h2> <p>DoS is already limited by the 50% refund limit.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-02-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Forshtatforshtat1@gmail.com https://wg-eips.ritovision.com/2542/ <h2 id="simple-summary">Simple Summary</h2> <p>A mechanism to allow smart contracts to access information on gas limits for the current transaction and execution frame.</p> <h2 id="abstract">Abstract</h2> <p>Currently, there is an existing opcode <code>0x45 GASLIMIT</code> that provides access to the block gas limit. While this information may be useful in some cases, it is probably not a value that smart contract developers may be concerned about. The opcode <code>0x5a GAS</code> provides the remaining gas, not the initial one. Also, it is worth noting how existing <code>0x32 ORIGIN</code>, <code>0x33 CALLER</code>, <code>0x34 CALLVALUE</code> and <code>0x3a GASPRICE</code> opcodes set a pattern of having access to both the transaction and current execution frame state. TBD: as 0x30 opcode range is exhausted, the proposed opcodes can be added to 0x50 range, or a new range can be added.</p> <h2 id="motivation">Motivation</h2> <p>As concepts of relaying, meta-transactions, gas fees, and account abstraction gain popularity, it becomes critical for some contracts to be able to track gas expenditure with absolute precision. Without access to this data on an EVM level, such contracts resort to approximation, mimicking EVM logic on-chain, and some use-cases even become infeasible.</p> <h2 id="specification">Specification</h2> <p>If block.number &gt;= TBD, add three new opcodes:</p> <p>TXGASLIMIT: 0x5c</p> <p>Pushes the gas limit of the entire transaction onto the stack. This is a value of the 'startgas' parameter signed by the externally owned account.<br /> Gas costs: 2 (same as <code>GASLIMIT</code>)</p> <p>CALLGASLIMIT: 0x5d</p> <p>Pushes the gas limit of the current execution frame onto the stack. This is the 'callGas' value that was obtained after the application of the EIP-150 “all but one 64th” rule.<br /> Gas costs: 2 (same as <code>GASLIMIT</code>)</p> <p>Also, consider renaming <code>0x45 GASLIMIT</code> to <code>BLOCKGASLIMIT</code> to avoid confusion.</p> <h2 id="rationale">Rationale</h2> <p>Consider a solidity smart contract that wants to know how much gas the entire transaction or a part of it had consumed. It is not entirely possible with the current EVM. With proposed changes, using a pseudo-Solidity syntax, this information would be easily available:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function keepTrackOfGas(string memory message, uint256 number) public {</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> uint gasUsed = msg.gasLimit - gasleft();</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This is an extremely common use case, and multiple implementations suffer from not taking the non-accessible expenses into consideration. The state-of-the-art solution for the <code>gasUsed</code> problem is to access 'gasleft()' as the first line of your smart contract.<br /> Note how variable transaction input size means the gas used by the transaction depends on the number of zero and non-zero bytes of input, as well <code>GTXDATANONZERO</code>. Another issue is that Solidity handles <code>public</code> methods by loading the entire input from <code>calldata</code> to <code>memory</code>, spending an unpredictable amount of gas.</p> <p>Another application is for a method to have a requirement for a gas limit given to it. This situation arises quite commonly in the context of meta-transactions, where the msg.sender's account holder may not be too interested in the inner transaction's success. Exaggerated pseudocode:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function verifyGasLimit(uint256 desiredGasLimit, bytes memory signature, address signer, bytes memory someOtherData) public {</span></span> <span class="giallo-l"><span> require(ecrecover(abi.encodePacked(desiredGasLimit, someOtherData), signature) == signer, &quot;Signature does not match&quot;);</span></span> <span class="giallo-l"><span> require(tx.gasLimit == desiredGasLimit, &quot;Transaction limit does not match the signed value. The signer did not authorize that.&quot;);</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>In this situation it is not possible to rely on 'gasleft()' value, because it is dynamic, depends on opcode and calldata pricing, and cannot be signed.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal introduces two new opcodes and renames an existing one, but stays fully backwards compatible apart from that.</p> <h2 id="forwards-compatibility">Forwards Compatibility</h2> <p>A major consideration for this proposal is its alignment with one or many possible future modifications to the EVM:</p> <ol> <li> <p>EIP-2489 Deprecate the GAS opcode (a.k.a. 39-UNGAS proposal)<br /> There is a sentiment that the ability of smart contracts to perform "gas introspection" leads to the contracts being dependent on current opcode pricing.<br /> While criticizing said misconception is beyond the scope of this EIP, in case there is a need to make a breaking change to the behavior of the existing <code>0x5a GAS</code> opcode, the same considerations will apply to the proposed opcodes. This means this EIP does not add any new restraints on EMV evolution.</p> </li> <li> <p>Stateless Ethereum<br /> The UNGAS proposal is said to be related to the ongoing project of Stateless Ethereum. It’s not strictly necessary for stateless Ethereum, but it is an idea for how to make future breaking changes to gas schedules easier.<br /> As long as the concept of 'gas limit' is part of the EVM, the author sees no reason proposed opcodes would conflict with Stateless Ethereum. Gas schedules are not exposed by this proposal.</p> </li> <li> <p>Comparison with other controversial opcodes<br /> There are opcodes that are not proposed for deprecation but face criticism. Examples include <code>0x32 ORIGIN</code> being misused by smart contract developers, or <code>0x46 CHAINID</code> making some smart-contracts 'unforkable'.<br /> This EIP neither encourages nor enables any bad security practices, and does not introduce any concepts that are new for EVM either.</p> </li> </ol> <h2 id="security-considerations">Security considerations</h2> <p>Existing smart contracts are not affected by this change.<br /> Smart contracts that will use proposed opcodes must not use them for the core of any security features, but only as a source of information about their execution environment.</p> <h2 id="implementation">Implementation</h2> <p>The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-02-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonhttps://github.com/arachnid 0agehttps://github.com/0age https://wg-eips.ritovision.com/2544/

Adds support for "wildcard" resolution of subdomains in ENS.

<h2 id="abstract">Abstract</h2> <p>The Ethereum Name Service Specification (EIP-137) establishes a two-step name resolution process. First, an ENS client performs the namehash algorithm on the name to determine the associated "node", and supplies that node to the ENS Registry contract to determine the resolver. Then, if a resolver has been set on the Registry, the client supplies that same node to the resolver contract, which will return the associated address or other record.</p> <p>As currently specified, this process terminates if a resolver is not set on the ENS Registry for a given node. This EIP changes the name resolution process by adding an additional step if a resolver is not set for a domain. This step strips out the leftmost label from the name, derives the node of the new fragment, and supplies that node to the ENS Registry. If a resolver is located for that node, the client supplies the original, complete node to that resolver contract to derive the relevant records. This step is repeated until a node with a resolver is found.</p> <p>Further, this specification defines a new way for resolvers to resolve names, using a unified <code>resolve()</code> method that permits more flexible handling of name resolution.</p> <h2 id="motivation">Motivation</h2> <p>Many applications such as wallet providers, exchanges, and dapps have expressed a desire to issue ENS names for their users via custom subdomains on a shared parent domain. However, the cost of doing so is currently prohibitive for large user bases, as a distinct record must be set on the ENS Registry for each subdomain.</p> <p>Furthermore, users cannot immediately utilize these subdomains upon account creation, as the transaction to assign a resolver for the node of the subdomain must first be submitted and mined on-chain. This adds unnecessary friction when onboarding new users, who coincidentally would often benefit greatly from the usability improvements afforded by an ENS name.</p> <p>Enabling wildcard support allows for the design of more advanced resolvers that deterministically generate addresses and other records for unassigned subdomains. The generated addresses could map to counterfactual contract deployment addresses (i.e. <code>CREATE2</code> addresses), to designated "fallback" addresses, or other schemes. Additionally, individual resolvers would still be assignable to any given subdomain, which would supersede the wildcard resolution using the parent resolver.</p> <p>Another critical motivation with EIP-2544 is to enable wildcard resolution in a backwards-compatible fashion. It does not require modifying the current ENS Registry contract or any existing resolvers, and continues to support existing ENS records — legacy ENS clients would simply fail to resolve wildcard records.</p> <h2 id="specification">Specification</h2> <p>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> <p>Let:</p> <ul> <li><code>namehash</code> be the algorithm defined in EIP 137.</li> <li><code>dnsencode</code> be the process for encoding DNS names specified in section 3.1 of RFC1035, with the exception that there is no limit on the total length of the encoded name. The empty string is encoded identically to the name '.', as a single 0-octet.</li> <li><code>parent</code> be a function that removes the first label from a name (eg, <code>parent('foo.eth') = 'eth'</code>). <code>parent('tld')</code> is defined as the empty string ''.</li> <li><code>ens</code> is the ENS registry contract for the current network.</li> </ul> <p>EIP-2544-compliant ENS resolvers MAY implement the following function interface:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>interface ExtendedResolver {</span></span> <span class="giallo-l"><span> function resolve(bytes calldata name, bytes calldata data) external view returns(bytes);</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>If a resolver implements this function, it MUST return true when <code>supportsInterface()</code> is called on it with the interface's ID, 0xTBD.</p> <p>ENS clients will call <code>resolve</code> with the DNS-encoded name to resolve and the encoded calldata for a resolver function (as specified in EIP-137 and elsewhere); the function MUST either return valid return data for that function, or revert if it is not supported.</p> <p>EIP-2544-compliant ENS clients MUST perform the following procedure when determining the resolver for a given name:</p> <ol> <li>Set <code>currentname = name</code></li> <li>Set <code>resolver = ens.resolver(namehash(currentname))</code></li> <li>If <code>resolver</code> is not the zero address, halt and return <code>resolver</code>.</li> <li>If <code>name</code> is the empty name ('' or '.'), halt and return null.</li> <li>Otherwise, set <code>currentname = parent(currentname)</code> and go to 2.</li> </ol> <p>If the procedure above returns null, name resolution MUST terminate unsuccessfully. Otherwise, EIP-2544-compliant ENS clients MUST perform the following procedure when resolving a record:</p> <ol> <li>Set <code>calldata</code> to the ABI-encoded call data for the resolution function required - for example, the ABI encoding of <code>addr(namehash(name))</code> when resolving the <code>addr</code> record.</li> <li>Set <code>supports2544 = resolver.supportsInterface(0xTBD)</code>.</li> <li>If <code>supports2544</code> is true, set <code>result = resolver.resolve(dnsencode(name), calldata)</code></li> <li>Otherwise, set <code>result</code> to the result of calling <code>resolver</code> with <code>calldata</code>.</li> <li>Return <code>result</code> after decoding it using the return data ABI of the corresponding resolution function (eg, for <code>addr()</code>, ABI-decode the result of <code>resolver.resolve()</code> as an <code>address</code>).</li> </ol> <p>Note that in all cases the resolution function (<code>addr()</code> etc) and the <code>resolve</code> function are supplied the original <code>name</code>, <em>not</em> the <code>currentname</code> found in the first stage of resolution.</p> <h3 id="pseudocode">Pseudocode</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getResolver(name) {</span></span> <span class="giallo-l"><span> for(let currentname = name; currentname !== &#39;&#39;; currentname = parent(currentname)) {</span></span> <span class="giallo-l"><span> const node = namehash(currentname);</span></span> <span class="giallo-l"><span> const resolver = ens.resolver(node);</span></span> <span class="giallo-l"><span> if(resolver != &#39;0x0000000000000000000000000000000000000000&#39;) {</span></span> <span class="giallo-l"><span> return resolver;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> return null;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function resolve(name, func, ...args) {</span></span> <span class="giallo-l"><span> const resolver = getResolver(name);</span></span> <span class="giallo-l"><span> if(resolver === null) {</span></span> <span class="giallo-l"><span> return null;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> const supports2544 = resolver.supportsInterface(&#39;0xTBD&#39;);</span></span> <span class="giallo-l"><span> let result;</span></span> <span class="giallo-l"><span> if(supports2544) {</span></span> <span class="giallo-l"><span> const calldata = resolver[func].encodeFunctionCall(namehash(name), ...args);</span></span> <span class="giallo-l"><span> result = resolver.resolve(dnsencode(name), calldata);</span></span> <span class="giallo-l"><span> return resolver[func].decodeReturnData(result);</span></span> <span class="giallo-l"><span> } else {</span></span> <span class="giallo-l"><span> return resolver[func](...args);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The proposed implementation supports wildcard resolution in a manner that minimizes the impact to existing systems. It also reuses existing algorithms and procedures to the greatest possible extent, thereby easing the burden placed on authors and maintainers of various ENS clients.</p> <p>It also recognizes an existing consensus concerning the desirability of wildcard resolution for ENS, enabling more widespread adoption of the original specification by solving for a key scalability obstacle.</p> <p>While introducing an optional <code>resolve</code> function for resolvers, taking the unhashed name and calldata for a resolution function increases implementation complexity, it provides a means for resolvers to obtain plaintext labels and act accordingly, which enables many wildcard-related use-cases that would otherwise not be possible - for example, a wildcard resolver could resolve <code>id.nifty.eth</code> to the owner of the NFT with id <code>id</code> in some collection. With only namehashes to work with, this is not possible. Resolvers with simpler requirements can continue to simply implement resolution functions directly and omit support for the <code>resolve</code> function entirely.</p> <p>The DNS wire format is used for encoding names as it permits quick and gas-efficient hashing of names, as well as other common operations such as fetching or removing individual labels; in contrast, dot-separated names require iterating over every character in the name to find the delimiter.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Existing ENS clients that are compliant with EIP-137 will fail to resolve wildcard records and refuse to interact with them, while those compliant with EIP-2544 will continue to correctly resolve, or reject, existing ENS records. Resolvers wishing to implement the new <code>resolve</code> function for non-wildcard use-cases (eg, where the resolver is set directly on the name being resolved) should consider what to return to legacy clients that call the individual resolution functions for maximum compatibility.</p> <h2 id="security-considerations">Security Considerations</h2> <p>While compliant ENS clients will continue to refuse to resolve records without a resolver, there is still the risk that an improperly-configured client will refer to an incorrect resolver, or will not reject interactions with the null address when a resolver cannot be located.</p> <p>Additionally, resolvers supporting completely arbitrary wildcard subdomain resolution will increase the likelihood of funds being sent to unintended recipients as a result of typos. Applications that implement such resolvers should consider making additional name validation available to clients depending on the context, or implementing features that support recoverability of funds.</p> <p>There is also the possibility that some applications might require that no resolver be set for certain subdomains. For this to be problematic, the parent domain would need to successfully resolve the given subdomain node — to the knowledge of the authors, no application currently supports this feature or expects that subdomains should not resolve to a record.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-02-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Vlasovhttps://github.com/shamatar hujw77https://github.com/hujw77 https://wg-eips.ritovision.com/2539/

Precompiles for BLS12-377 curve operations

<h2 id="abstract">Abstract</h2> <p>This precompile adds operation on BLS12-377 curve (from Zexe paper) as a precompile in a set necessary to <em>efficiently</em> perform operations such as BLS signature verification and perform SNARKs verifications. Unique properties of BLS12-377 also later allow to have SNARKs that check BLS12-377 pairing in an efficient way and allow e.g. constant-size BLS signature aggregation.</p> <p>If <code>block.number &gt;= X</code> we introduce <em>nine</em> separate precompiles to perform the following operations:</p> <ul> <li>BLS12_377_G1ADD - to perform point addition on a curve defined over prime field</li> <li>BLS12_377_G1MUL - to perform point multiplication on a curve defined over prime field</li> <li>BLS12_377_G1MULTIEXP - to perform multiexponentiation on a curve defined over prime field</li> <li>BLS12_377_G2ADD - to perform point addition on a curve twist defined over quadratic extension of the base field</li> <li>BLS12_377_G2MUL - to perform point multiplication on a curve twist defined over quadratic extension of the base field</li> <li>BLS12_377_G2MULTIEXP - to perform multiexponentiation on a curve twist defined over quadratic extension of the base field</li> <li>BLS12_377_PAIRING - to perform a pairing operations between a set of <em>pairs</em> of (G1, G2) points</li> <li>BLS12_377_MAP_FP_TO_G1 - maps base field element into the G1 point</li> <li>BLS12_377_MAP_FP2_TO_G2 - maps extension field element into the G2 point</li> </ul> <p>Multiexponentiation operation is included to efficiently aggregate public keys or individual signer's signatures during BLS signature verification.</p> <h3 id="proposed-addresses-table">Proposed addresses table</h3> <table><thead><tr><th>Precompile</th><th>Address</th></tr></thead><tbody> <tr><td>BLS12_377_G1ADD</td><td>0x15</td></tr> <tr><td>BLS12_377_G1MUL</td><td>0x16</td></tr> <tr><td>BLS12_377_G1MULTIEXP</td><td>0x17</td></tr> <tr><td>BLS12_377_G2ADD</td><td>0x18</td></tr> <tr><td>BLS12_377_G2MUL</td><td>0x19</td></tr> <tr><td>BLS12_377_G2MULTIEXP</td><td>0x1a</td></tr> <tr><td>BLS12_377_PAIRING</td><td>0x1b</td></tr> <tr><td>BLS12_377_MAP_FP_TO_G1</td><td>0x1c</td></tr> <tr><td>BLS12_377_MAP_FP2_TO_G2</td><td>0x1d</td></tr> </tbody></table> <h2 id="motivation">Motivation</h2> <p>Motivation of this precompile is to add a cryptographic primitive that allows to get 120+ bits of security for operations over pairing friendly curve compared to the existing BN254 precompile that only provides 80 bits of security. In addition it allows efficient one-time recursive proof aggregations, e.g. proofs about existence of BLS12-377 based signature.</p> <h2 id="specification">Specification</h2> <p>Curve parameters:</p> <p>BLS12-377 curve is fully defined by the following set of parameters (coefficient <code>A=0</code> for all BLS12 curves):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Base field modulus = 0x01ae3a4617c510eac63b05c06ca1493b1a22d9f300f5138f1ef3622fba094800170b5d44300000008508c00000000001</span></span> <span class="giallo-l"><span>B coefficient = 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>Main subgroup order = 0x12ab655e9a2ca55660b44d1e5c37b00159aa76fed00000010a11800000000001</span></span> <span class="giallo-l"><span>Extension tower:</span></span> <span class="giallo-l"><span>Fp2 construction:</span></span> <span class="giallo-l"><span>Fp quadratic non-residue = 0x01ae3a4617c510eac63b05c06ca1493b1a22d9f300f5138f1ef3622fba094800170b5d44300000008508bffffffffffc</span></span> <span class="giallo-l"><span>Fp6/Fp12 construction:</span></span> <span class="giallo-l"><span>Fp2 cubic non-residue c0 = 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>Fp2 cubic non-residue c1 = 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001</span></span> <span class="giallo-l"><span>Twist parameters:</span></span> <span class="giallo-l"><span>Twist type: D</span></span> <span class="giallo-l"><span>B coefficient for twist c0 = 0x000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000</span></span> <span class="giallo-l"><span>B coefficient for twist c1 = 0x010222f6db0fd6f343bd03737460c589dc7b4f91cd5fd889129207b63c6bf8000dd39e5c1ccccccd1c9ed9999999999a</span></span> <span class="giallo-l"><span>Generators:</span></span> <span class="giallo-l"><span>G1:</span></span> <span class="giallo-l"><span>X = 0x008848defe740a67c8fc6225bf87ff5485951e2caa9d41bb188282c8bd37cb5cd5481512ffcd394eeab9b16eb21be9ef</span></span> <span class="giallo-l"><span>Y = 0x01914a69c5102eff1f674f5d30afeec4bd7fb348ca3e52d96d182ad44fb82305c2fe3d3634a9591afd82de55559c8ea6</span></span> <span class="giallo-l"><span>G2:</span></span> <span class="giallo-l"><span>X c0 = 0x018480be71c785fec89630a2a3841d01c565f071203e50317ea501f557db6b9b71889f52bb53540274e3e48f7c005196</span></span> <span class="giallo-l"><span>X c1 = 0x00ea6040e700403170dc5a51b1b140d5532777ee6651cecbe7223ece0799c9de5cf89984bff76fe6b26bfefa6ea16afe</span></span> <span class="giallo-l"><span>Y c0 = 0x00690d665d446f7bd960736bcbb2efb4de03ed7274b49a58e458c282f832d204f2cf88886d8c7c2ef094094409fd4ddf</span></span> <span class="giallo-l"><span>Y c1 = 0x00f8169fd28355189e549da3151a70aa61ef11ac3d591bf12463b01acee304c24279b83f5e52270bd9a1cdd185eb8f93</span></span> <span class="giallo-l"><span>Pairing parameters:</span></span> <span class="giallo-l"><span>|x| (miller loop scalar) = 0x8508c00000000001</span></span> <span class="giallo-l"><span>x is negative = false</span></span></code></pre><h3 id="fine-points-and-encoding-of-base-elements">Fine points and encoding of base elements</h3> <h4 id="field-elements-encoding">Field elements encoding:</h4> <p>To encode points involved in the operation one has to encode elements of the base field and the extension field.</p> <p>Base field element (Fp) is encoded as <code>64</code> bytes by performing BigEndian encoding of the corresponding (unsigned) integer (top <code>16</code> bytes are always zeroes). <code>64</code> bytes are chosen to have <code>32</code> byte aligned ABI (representable as e.g. <code>bytes32[2]</code> or <code>uint256[2]</code>). Corresponding integer <strong>must</strong> be less than field modulus.</p> <p>For elements of the quadratic extension field (Fp2) encoding is byte concatenation of individual encoding of the coefficients totaling in <code>128</code> bytes for a total encoding. For an Fp2 element in a form <code>el = c0 + c1 * v</code> where <code>v</code> is formal quadratic non-residue and <code>c0</code> and <code>c1</code> are Fp elements the corresponding byte encoding will be <code>encode(c0) || encode(c1)</code> where <code>||</code> means byte concatenation (or one can use <code>bytes32[4]</code> or <code>uint256[4]</code> in terms of Solidity types).</p> <p>If encodings do not follow this spec anywhere during parsing in the precompile the precompile <em>must</em> return an error.</p> <h4 id="encoding-of-points-in-g1-g2">Encoding of points in G1/G2:</h4> <p>Points in either G1 (in base field) or in G2 (in extension field) are encoded as byte concatenation of encodings of the <code>x</code> and <code>y</code> affine coordinates. Total encoding length for G1 point is thus <code>128</code> bytes and for G2 point is <code>256</code> bytes.</p> <h4 id="point-of-infinity-encoding">Point of infinity encoding:</h4> <p>Also referred as "zero point". For BLS12 curves point with coordinates <code>(0, 0)</code> (formal zeroes in Fp or Fp2) is <em>not</em> on the curve, so encoding of such point <code>(0, 0)</code> is used as a convention to encode point of infinity.</p> <h4 id="encoding-of-scalars-for-multiplication-operation">Encoding of scalars for multiplication operation:</h4> <p>Scalar for multiplication operation is encoded as <code>32</code> bytes by performing BigEndian encoding of the corresponding (unsigned) integer. Corresponding integer is <strong>not</strong> required to be less than or equal than main subgroup size.</p> <h3 id="abi-for-operations">ABI for operations</h3> <h4 id="abi-for-g1-addition">ABI for G1 addition</h4> <p>G1 addition call expects <code>256</code> bytes as an input that is interpreted as byte concatenation of two G1 points (<code>128</code> bytes each). Output is an encoding of addition operation result - single G1 point (<code>128</code> bytes).</p> <p>Error cases:</p> <ul> <li>Either of points being not on the curve must result in error</li> <li>Field elements encoding rules apply (obviously)</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-g1-multiplication">ABI for G1 multiplication</h4> <p>G1 multiplication call expects <code>160</code> bytes as an input that is interpreted as byte concatenation of encoding of G1 point (<code>128</code> bytes) and encoding of a scalar value (<code>32</code> bytes). Output is an encoding of multiplication operation result - single G1 point (<code>128</code> bytes).</p> <p>Error cases:</p> <ul> <li>Point being not on the curve must result in error</li> <li>Field elements encoding rules apply (obviously)</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-g1-multiexponentiation">ABI for G1 multiexponentiation</h4> <p>G1 multiexponentiation call expects <code>160*k</code> bytes as an input that is interpreted as byte concatenation of <code>k</code> slices each of them being a byte concatenation of encoding of G1 point (<code>128</code> bytes) and encoding of a scalar value (<code>32</code> bytes). Output is an encoding of multiexponentiation operation result - single G1 point (<code>128</code> bytes).</p> <p>Error cases:</p> <ul> <li>Any of G1 points being not on the curve must result in error</li> <li>Field elements encoding rules apply (obviously)</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-g2-addition">ABI for G2 addition</h4> <p>G2 addition call expects <code>512</code> bytes as an input that is interpreted as byte concatenation of two G2 points (<code>256</code> bytes each). Output is an encoding of addition operation result - single G2 point (<code>256</code> bytes).</p> <p>Error cases:</p> <ul> <li>Either of points being not on the curve must result in error</li> <li>Field elements encoding rules apply (obviously)</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-g2-multiplication">ABI for G2 multiplication</h4> <p>G2 multiplication call expects <code>288</code> bytes as an input that is interpreted as byte concatenation of encoding of G2 point (<code>256</code> bytes) and encoding of a scalar value (<code>32</code> bytes). Output is an encoding of multiplication operation result - single G2 point (<code>256</code> bytes).</p> <p>Error cases:</p> <ul> <li>Point being not on the curve must result in error</li> <li>Field elements encoding rules apply (obviously)</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-g2-multiexponentiation">ABI for G2 multiexponentiation</h4> <p>G2 multiexponentiation call expects <code>288*k</code> bytes as an input that is interpreted as byte concatenation of <code>k</code> slices each of them being a byte concatenation of encoding of G2 point (<code>256</code> bytes) and encoding of a scalar value (<code>32</code> bytes). Output is an encoding of multiexponentiation operation result - single G2 point (<code>256</code> bytes).</p> <p>Error cases:</p> <ul> <li>Any of G2 points being not on the curve must result in error</li> <li>Field elements encoding rules apply (obviously)</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-pairing">ABI for pairing</h4> <p>Pairing call expects <code>384*k</code> bytes as an inputs that is interpreted as byte concatenation of <code>k</code> slices. Each slice has the following structure:</p> <ul> <li><code>128</code> bytes of G1 point encoding</li> <li><code>256</code> bytes of G2 point encoding</li> </ul> <p>Output is a <code>32</code> bytes where first <code>31</code> bytes are equal to <code>0x00</code> and the last byte is <code>0x01</code> if pairing result is equal to multiplicative identity in a pairing target field and <code>0x00</code> otherwise.</p> <p>Error cases:</p> <ul> <li>Invalid encoding of any boolean variable must result in error</li> <li>Any of G1 or G2 points being not on the curve must result in error</li> <li>Any of G1 or G2 points are not in the correct subgroup</li> <li>Field elements encoding rules apply (obviously)</li> <li>Input has invalid length</li> </ul> <h4 id="abi-for-mapping-fp-element-to-g1-point">ABI for mapping Fp element to G1 point</h4> <p>Field-to-curve call expects <code>64</code> bytes as input that is interpreted as an element of the base field. Output of this call is <code>128</code> bytes and is G1 point following respective encoding rules.</p> <p>Error cases:</p> <ul> <li>Input has invalid length</li> <li>Input is not a valid field element</li> </ul> <h4 id="abi-for-mapping-fp2-element-to-g2-point">ABI for mapping Fp2 element to G2 point</h4> <p>Field-to-curve call expects <code>128</code> bytes as input that is interpreted as an element of the quadratic extension field. Output of this call is <code>256</code> bytes and is G2 point following respective encoding rules.</p> <p>Error cases:</p> <ul> <li>Input has invalid length</li> <li>Input is not a valid field element</li> </ul> <h3 id="prevention-of-ddos-on-error-handling">Prevention of DDoS on error handling</h3> <p>This precompile performs extensive computations and in case of any errors during execution it MUST consume all gas from the gas schedule for the corresponding operation.</p> <h3 id="gas-schedule">Gas schedule</h3> <p>Assuming a constant <code>30 MGas/second</code> following prices are suggested.</p> <h4 id="g1-addition">G1 addition</h4> <p><code>600</code> gas</p> <h4 id="g1-multiplication">G1 multiplication</h4> <p><code>12000</code> gas</p> <h4 id="g2-addition">G2 addition</h4> <p><code>4500</code> gas</p> <h4 id="g2-multiplication">G2 multiplication</h4> <p><code>55000</code> gas</p> <h4 id="g1-g2-multiexponentiation">G1/G2 Multiexponentiation</h4> <p>Multiexponentiations are expected to be performed by the Peppinger algorithm (we can also say that it <strong>must</strong> be performed by Peppinger algorithm to have a speedup that results in a discount over naive implementation by multiplying each pair separately and adding the results). For this case there was a table prepared for discount in case of <code>k &lt;= 128</code> points in the multiexponentiation with a discount cap <code>max_discount</code> for <code>k &gt; 128</code>.</p> <p>To avoid non-integer arithmetic call cost is calculated as <code>k * multiplication_cost * discount / multiplier</code> where <code>multiplier = 1000</code>, <code>k</code> is a number of (scalar, point) pairs for the call, <code>multiplication_cost</code> is a corresponding single multiplication call cost for G1/G2.</p> <p>Discounts table as a vector of pairs <code>[k, discount]</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[[1, 1200], [2, 888], [3, 764], [4, 641], [5, 594], [6, 547], [7, 500], [8, 453], [9, 438], [10, 423], [11, 408], [12, 394], [13, 379], [14, 364], [15, 349], [16, 334], [17, 330], [18, 326], [19, 322], [20, 318], [21, 314], [22, 310], [23, 306], [24, 302], [25, 298], [26, 294], [27, 289], [28, 285], [29, 281], [30, 277], [31, 273], [32, 269], [33, 268], [34, 266], [35, 265], [36, 263], [37, 262], [38, 260], [39, 259], [40, 257], [41, 256], [42, 254], [43, 253], [44, 251], [45, 250], [46, 248], [47, 247], [48, 245], [49, 244], [50, 242], [51, 241], [52, 239], [53, 238], [54, 236], [55, 235], [56, 233], [57, 232], [58, 231], [59, 229], [60, 228], [61, 226], [62, 225], [63, 223], [64, 222], [65, 221], [66, 220], [67, 219], [68, 219], [69, 218], [70, 217], [71, 216], [72, 216], [73, 215], [74, 214], [75, 213], [76, 213], [77, 212], [78, 211], [79, 211], [80, 210], [81, 209], [82, 208], [83, 208], [84, 207], [85, 206], [86, 205], [87, 205], [88, 204], [89, 203], [90, 202], [91, 202], [92, 201], [93, 200], [94, 199], [95, 199], [96, 198], [97, 197], [98, 196], [99, 196], [100, 195], [101, 194], [102, 193], [103, 193], [104, 192], [105, 191], [106, 191], [107, 190], [108, 189], [109, 188], [110, 188], [111, 187], [112, 186], [113, 185], [114, 185], [115, 184], [116, 183], [117, 182], [118, 182], [119, 181], [120, 180], [121, 179], [122, 179], [123, 178], [124, 177], [125, 176], [126, 176], [127, 175], [128, 174]]</span></span></code></pre> <p><code>max_discount = 174</code></p> <h4 id="pairing-operation">Pairing operation</h4> <p>Cost of the pairing operation is <code>55000*k + 65000</code> where <code>k</code> is a number of pairs.</p> <h4 id="fp-to-g1-mapping-operation">Fp-to-G1 mapping operation</h4> <p>Fp -&gt; G1 mapping is <code>5500</code> gas.</p> <h4 id="fp2-to-g2-mapping-operation">Fp2-to-G2 mapping operation</h4> <p>Fp2 -&gt; G2 mapping is <code>75000</code> gas</p> <h2 id="rationale">Rationale</h2> <p>Motivation section covers a total motivation to have operations over BLS12-377 curve available. We also extend a rationale for move specific fine points.</p> <h3 id="multiexponentiation-as-a-separate-call">Multiexponentiation as a separate call</h3> <p>Explicit separate multiexponentiation operation that allows one to save execution time (so gas) by both the algorithm used (namely Peppinger algorithm) and (usually forgotten) by the fact that <code>CALL</code> operation in Ethereum is expensive (at the time of writing), so one would have to pay non-negigible overhead if e.g. for multiexponentiation of <code>100</code> points would have to call the multipication precompile <code>100</code> times and addition for <code>99</code> times (roughly <code>138600</code> would be saved).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backward compatibility questions.</p> <h3 id="important-notes">Important notes</h3> <h4 id="subgroup-checks">Subgroup checks</h4> <p>Subgroup check <strong>is mandatory</strong> during the pairing call. Implementations <em>should</em> use fast subgroup checks: at the time of writing multiplication gas cost is based on <code>double-and-add</code> multiplication method that has a clear "worst case" (all bits are equal to one). For pairing operation it's expected that implementation uses faster subgroup check, e.g. by using wNAF multiplication method for elliptic curves that is ~ <code>40%</code> cheaper with windows size equal to 4. (Tested empirically. Savings are due to lower hamming weight of the group order and even lower hamming weight for wNAF. Concretely, subgroup check for both G1 and G2 points in a pair are around <code>35000</code> combined).</p> <h2 id="test-cases">Test Cases</h2> <p>Due to the large test parameters space we first provide properties that various operations must satisfy. We use additive notation for point operations, capital letters (<code>P</code>, <code>Q</code>) for points, small letters (<code>a</code>, <code>b</code>) for scalars. Generator for G1 is labeled as <code>G</code>, generator for G2 is labeled as <code>H</code>, otherwise we assume random point on a curve in a correct subgroup. <code>0</code> means either scalar zero or point of infinity. <code>1</code> means either scalar one or multiplicative identity. <code>group_order</code> is a main subgroup order. <code>e(P, Q)</code> means pairing operation where <code>P</code> is in G1, <code>Q</code> is in G2.</p> <p>Requeired properties for basic ops (add/multiply):</p> <ul> <li>Commutativity: <code>P + Q = Q + P</code></li> <li>Additive negation: <code>P + (-P) = 0</code></li> <li>Doubling <code>P + P = 2*P</code></li> <li>Subgroup check: <code>group_order * P = 0</code></li> <li>Trivial multiplication check: <code>1 * P = P</code></li> <li>Multiplication by zero: <code>0 * P = 0</code></li> <li>Multiplication by the unnormalized scalar <code>(scalar + group_order) * P = scalar * P</code></li> </ul> <p>Required properties for pairing operation:</p> <ul> <li>Degeneracy <code>e(P, 0*Q) = e(0*P, Q) = 1</code></li> <li>Bilinearity <code>e(a*P, b*Q) = e(a*b*P, Q) = e(P, a*b*Q)</code> (internal test, not visible through ABI)</li> </ul> <p>Test vector for all operations are expanded in this <code>csv</code> files in matter-labs' 1962 proposol.</p> <h2 id="reference-implementation">Reference Implementation</h2> <p>There is a various choice of existing implementations of the curve operations. It may require extra work to add an ABI:</p> <ul> <li>Code bases with fixed parameters</li> <li>Rust: matter-labs</li> <li>C++: matter-labs</li> <li>Original implementation linked in Zexe paper in Rust: github.com/scipr-lab/zexe</li> <li>Standalone in Go: github.com/kilic/bls12-377</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>Strictly following the spec will eliminate security implications or consensus implications in a contrast to the previous BN254 precompile.</p> <p>Important topic is a "constant time" property for performed operations. We explicitly state that this precompile <strong>IS NOT REQUIRED</strong> to perform all the operations using constant time algorithms.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-02-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 William Morrisshttps://github.com/wjmelements https://wg-eips.ritovision.com/3300/ <h2 id="simple-summary">Simple Summary</h2> <p>Phases out the <code>SSTORE</code> and <code>SELFDESTRUCT</code> gas refunds.</p> <h2 id="abstract">Abstract</h2> <p>This EIP would define a block when the <code>SSTORE</code> and <code>SELFDESTRUCT</code> refunds would begin to diminish. The refund would step linearly downward, eroding the implicit value of such refunds at an accelerating pace.</p> <h2 id="motivation">Motivation</h2> <p>Refunds increase block elasticity, so the block gas target can exceed the number established by miners by up to 2x. This can cause hesitancy for miners to increase the block gas target.</p> <p>Refunds, tokenized or not, are valuable to their holders, especially during congestion. If refunds must be removed, a gradual change in their value would be less-disruptive to the gas market than sudden abolition. Refund consumption would proceed, especially during periods of congestion, and the refunds would be cleaned up from the state. Refund creation, driven by demand, would naturally diminish as the efficiency of the refunds fall. As the refund value approaches the activation cost, the implicit value of the refunds will approach zero, but in periods of congestion they will be cleaned up.</p> <p>This change is less work for the protocol developers than compensation and cleanup, while likely still achieving cleanup.</p> <h2 id="specification">Specification</h2> <p>Parameters:</p> <ul> <li><code>FORK_BLOCK_NUM</code>: EIP-3300 activation block</li> <li><code>REFUND_DECAY_STEP</code>: 1 gas</li> <li><code>REFUND_DECAY_FREQUENCY</code>: 100 blocks</li> </ul> <p>Computed:</p> <ul> <li><code>REFUND_DECAY</code>: <code>REFUND_DECAY_STEP * ceil((block.number + 1 - FORK_BLOCK_NUM) / REFUND_DECAY_FREQUENCY)</code></li> </ul> <p>On the block this EIP activates, and again every <code>REFUND_DECAY_FREQUENCY</code> blocks, all gas refunds, including <code>SELFDESTRUCT</code> and <code>SSTORE</code> would diminish by <code>REFUND_DECAY_STEP</code>, until 0. The current difference is called the <code>REFUND_DECAY</code>, which shall be subtracted from each gas refund.</p> <p>For gas-cost regimes with refund removals that cancel prior refunds, the invariant that the refund counter cannot go negative will be preserved by diminishing the magnitude of those removals by <code>REFUND_DECAY</code>, until 0.</p> <h3 id="eip-2929">EIP-2929</h3> <p>The refunds as of EIP-2929 are as follows:</p> <ul> <li>24000 for SELFDESTRUCT</li> <li><code>SSTORE_RESET_GAS - SLOAD_GAS</code> (5000 - 100)</li> <li><code>SSTORE_SET_GAS - SLOAD_GAS</code> (20000 - 100)</li> <li><code>SSTORE_SET_GAS - SLOAD_GAS</code> (20000 - 100)</li> <li><code>SSTORE_CLEARS_SCHEDULE</code> (15000)</li> </ul> <p>Each of these refunds would be decreased by the current <code>REFUND_DECAY</code>.</p> <p>There is also a case where <code>SSTORE_CLEARS_SCHEDULE</code> is removed from the refund counter. That removal will also diminish by <code>REFUND_DECAY_STEP</code> until 0, maintaining the non-negative refund counter invariant.</p> <h2 id="rationale">Rationale</h2> <p>Persisted refunds would become worthless before they fall below their activation cost. Once the refunds are worthless, they can be removed by another hard fork without waiting for 0. The rate of diminishing specified would currently require (24000-5000) * 100 = 1,900,000 blocks for <code>SELFDESTRUCT</code> and (15000-5000) * 100 = 1,000,000 blocks for <code>SSTORE</code>. This timeframe is currently about a year, which should be enough flexibility for the remaining refunds to be consumed.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal breaks gas refunds, which contribute to block elasticity. The effect of this will be increased gas price volatility: higher highs and lower lows.</p> <p>Because the refund counter is separate from the gas counter, the block-to-block gas changes will not break <code>eth_estimateGas</code>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-02-21T00:00:00+00:00 2026-02-11T14:49:27+00:00 Martin Holst Swendehttps://github.com/holiman https://wg-eips.ritovision.com/2583/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP introduces a gas penalty for opcodes which access the account for trie non-existent accounts.</p> <h2 id="abstract">Abstract</h2> <p>This EIP adds a gas penalty for accesses to the account trie, where the address being looked up does not exist. Non-existing accounts can be used in DoS attacks, since they bypass cache mechanisms, thus creating a large discrepancy between 'normal' mode of execution and 'worst-case' execution of an opcode.</p> <h2 id="motivation">Motivation</h2> <p>As the ethereum trie becomes more and more saturated, the number of disk lookups that a node is required to do in order to access a piece of state increases too. This means that checking e.g. <code>EXTCODEHASH</code> of an account at block <code>5</code> was <em>inherently</em> a cheaper operation that it is at, say <code>8.5M</code>.</p> <p>From an implementation perspective, a node can (and does) use various caching mechanisms to cope with the problem, but there's an inherent problem with caches: when they yield a 'hit', they're great, but when they 'miss', they're useless.</p> <p>This is attackable. By forcing a node to lookup non-existent keys, an attacker can maximize the number of disk lookups. Sidenote: even if the 'non-existence' is cached, it's trivial to use a new non-existent key the next time, and never hit the same non-existent key again. Thus, caching 'non-existence' might be dangerous, since it will evict 'good' entries.</p> <p>So far, the attempts to handle this problem has been in raising the gas cost, e.g. <a href="https://wg-eips.ritovision.com/150/">EIP-150</a>, <a href="https://wg-eips.ritovision.com/1884/">EIP-1884</a>.</p> <p>However, when determining gas-costs, a secondary problem that arises due to the large discrepancy between 'happy-path' and 'notorious path' -- how do we determine the pricing?</p> <ul> <li>The 'happy-path', assuming all items are cached? <ul> <li>Doing so would that would underprice all trie-accesses, and could be DoS-attacked.</li> </ul> </li> <li>The 'normal' usage, based on benchmarks of actual usage? <ul> <li>This is basically what we do now, but that means that intentionally notorious executions are underpriced -- which constitutes a DoS vulnerability.</li> </ul> </li> <li>The 'paranoid' case: price everything as if caching did not exist? <ul> <li>This would severely harm basically every contract due to the gas-cost increase. Also, if the gas limits were raised in order to allow the same amount of computation as before, the notorious case could again be used for DoS attacks.</li> </ul> </li> </ul> <p>From an engineering point of view, a node implementor is left with few options:</p> <ul> <li>Implement bloom filters for existence. This is difficult, not least because of the problems of reorgs, and the fact that it's difficult to undo bloom filter modifications.</li> <li>Implement flattened account databases. This is also difficult, both because of reorgs and also because it needs to be an <em>additional</em> data structure aside from the <code>trie</code> -- we need the <code>trie</code> for consensus. So it's an extra data structure of around <code>15G</code> that needs to be kept in check. This is currently being pursued by the Geth-team.</li> </ul> <p>This EIP proposes a mechanism to alleviate the situation.</p> <h2 id="specification">Specification</h2> <p>We define the constant <code>penalty</code> as <code>TBD</code> (suggested <code>2000</code> gas).</p> <p>For opcodes which access the account trie, whenever the operation is invoked targeting an <code>address</code> which does not exist in the trie, then <code>penalty</code> gas is deducted from the available <code>gas</code>.</p> <h3 id="detailed-specification">Detailed specification</h3> <p>These are the opcodes which triggers lookup into the main account trie:</p> <table><thead><tr><th>Opcode</th><th>Affected</th><th>Comment</th></tr></thead><tbody> <tr><td>BALANCE</td><td>Yes</td><td><code>balance(nonexistent_addr)</code> would incur <code>penalty</code></td></tr> <tr><td>EXTCODEHASH</td><td>Yes</td><td><code>extcodehash(nonexistent_addr)</code> would incur <code>penalty</code></td></tr> <tr><td>EXTCODECOPY</td><td>Yes</td><td><code>extcodecopy(nonexistent_addr)</code> would incur <code>penalty</code></td></tr> <tr><td>EXTCODESIZE</td><td>Yes</td><td><code>extcodesize(nonexistent_addr)</code> would incur <code>penalty</code></td></tr> <tr><td>CALL</td><td>Yes</td><td>See details below about call variants</td></tr> <tr><td>CALLCODE</td><td>Yes</td><td>See details below about call variants</td></tr> <tr><td>DELEGATECALL</td><td>Yes</td><td>See details below about call variants</td></tr> <tr><td>STATICCALL</td><td>Yes</td><td>See details below about call variants</td></tr> <tr><td>SELFDESTRUCT</td><td>No</td><td>See details below.</td></tr> <tr><td>CREATE</td><td>No</td><td>Create destination not explicitly settable, and assumed to be nonexistent already.</td></tr> <tr><td>CREATE2</td><td>No</td><td>Create destination not explicitly settable, and assumed to be nonexistent already.</td></tr> </tbody></table> <h3 id="notes-on-call-derivatives">Notes on Call-derivatives</h3> <p>A <code>CALL</code> triggers a lookup of the <code>CALL</code> destination address. The base cost for <code>CALL</code> is at <code>700</code> gas. A few other characteristics determine the actual gas cost of a call:</p> <ol> <li>If the <code>CALL</code> (or <code>CALLCODE</code>) transfers value, an additional <code>9K</code> is added as cost. 1.1 If the <code>CALL</code> destination did not previously exist, an additional <code>25K</code> gas is added to the cost.</li> </ol> <p>This EIP adds a second rule in the following way:</p> <ol start="2"> <li>If the call does <em>not</em> transfer value and the callee does <em>not</em> exist, then <code>penalty</code> gas is added to the cost.</li> </ol> <p>In the table below,</p> <ul> <li><code>value</code> means non-zero value transfer,</li> <li><code>!value</code> means zero value transfer,</li> <li><code>dest</code> means destination already exists, or is a <code>precompile</code></li> <li><code>!dest</code> means destination does not exist and is not a <code>precompile</code></li> </ul> <table><thead><tr><th>Op</th><th>value,dest</th><th>value, !dest</th><th>!value, dest</th><th>!value, !dest</th></tr></thead><tbody> <tr><td>CALL</td><td>no change</td><td>no change</td><td>no change</td><td><code>penalty</code></td></tr> <tr><td>CALLCODE</td><td>no change</td><td>no change</td><td>no change</td><td><code>penalty</code></td></tr> <tr><td>DELEGATECALL</td><td>N/A</td><td>N/A</td><td>no change</td><td><code>penalty</code></td></tr> <tr><td>STATICCALL</td><td>N/A</td><td>N/A</td><td>no change</td><td><code>penalty</code></td></tr> </tbody></table> <p>Whether the rules of this EIP is to be applied for regular ether-sends in <code>transactions</code> is TBD. See the 'Backwards Compatibility'-section for some more discussion on that topic.</p> <h3 id="note-on-selfdestruct">Note on <code>SELFDESTRUCT</code></h3> <p>The <code>SELFDESTRUCT</code> opcode also triggers an account trie lookup of the <code>beneficiary</code>. However, due to the following reasons, it has been omitted from having a <code>penalty</code> since it already costs <code>5K</code> gas.</p> <h3 id="clarifications">Clarifications:</h3> <ul> <li>The <code>base</code> costs of any opcodes are not modified by the EIP.</li> <li>The opcode <code>SELFBALANCE</code> is not modified by this EIP, regardless of whether the <code>self</code> address exists or not.</li> </ul> <h2 id="rationale">Rationale</h2> <p>With this scheme, we could continue to price these operations based on the 'normal' usage, but gain protection from attacks that try to maximize disk lookups/cache misses. This EIP does not modify anything regarding storage trie accesses, which might be relevant for a future EIP. However, there are a few crucial differences.</p> <ol> <li>Storage tries are typically small, and there's a high cost to populate a storage trie with sufficient density for it to be in the same league as the account trie.</li> <li>If an attacker wants to use an existing large storage trie, e.g. some popular token, he would typically have to make a <code>CALL</code> to cause a lookup in that token -- something like <code>token.balanceOf(&lt;nonexistent-address&gt;)</code>. That adds quite a lot of extra gas-impediments, as each <code>CALL</code> is another <code>700</code> gas, plus gas for arguments to the <code>CALL</code>.</li> </ol> <h3 id="determining-the-penalty">Determining the <code>penalty</code></h3> <p>A transaction with <code>10M</code> gas can today cause ~<code>14K</code> trie lookups.</p> <ul> <li>A <code>penalty</code> of <code>1000</code>would lower the number to ~<code>5800</code> lookups, <code>41%</code> of the original.</li> <li>A <code>penalty</code> of <code>2000</code>would lower the number to ~<code>3700</code> lookups, <code>26%</code> of the original.</li> <li>A <code>penalty</code> of <code>3000</code>would lower the number to ~<code>2700</code> lookups, <code>20%</code> of the original.</li> <li>A <code>penalty</code> of <code>4000</code>would lower the number to ~<code>2100</code> lookups, <code>15%</code> of the original.</li> </ul> <p>There exists a roofing function for the <code>penalty</code>. Since the <code>penalty</code> is deducted from <code>gas</code>, that means that a malicious contract can always invoke a malicious relay to perform the trie lookup. Let's refer to this as the 'shielded relay' attack.</p> <p>In such a scenario, the <code>malicious</code> would spend <code>~750</code> gas each call to <code>relay</code>, and would need to provide the <code>relay</code> with at least <code>700</code> gas to do a trie access.</p> <p>Thus, the effective <code>cost</code> would be on the order of <code>1500</code>. It can thus be argued that <code>penalty</code> above <code>~800</code> would not achieve better protection against trie-miss attacks.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard-fork.</p> <h3 id="ether-transfers">Ether transfers</h3> <p>A regular <code>transaction</code> from one EOA to another, with value, is not affected.</p> <p>A <code>transaction</code> with <code>0</code> value, to a destination which does not exist, would be. This scenario is highly unlikely to matter, since such a <code>transaction</code> is useless -- even during success, all it would accomplish would be to spend some <code>gas</code>. With this EIP, it would potentially spend some more gas.</p> <h3 id="layer-2">Layer 2</h3> <p>Regarding layer-2 backward compatibility, this EIP is a lot less disruptive than EIPs which modify the <code>base</code> cost of an opcode. For state accesses, there are seldom legitimate scenarios where</p> <ol> <li>A contract checks <code>BALANCE</code>/<code>EXTCODEHASH</code>/<code>EXTCODECOPY</code>/<code>EXTCODESIZE</code> of another contract <code>b</code>, <em>and</em>,</li> <li>If such <code>b</code> does not exist, continues the execution</li> </ol> <h4 id="solidity-remote-calls">Solidity remote calls</h4> <p>Example: When a remote call is made in Solidity:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> recipient.invokeMethod(1)</span></span></code></pre> <ul> <li>Solidity does a pre-flight <code>EXTCODESIZE</code> on <code>recipient</code>.</li> <li>If the pre-flight check returns <code>0</code>, then <code>revert(0,0)</code> is executed, to stop the execution.</li> <li>If the pre-flight check returns non-zero, then the execution continues and the <code>CALL</code> is made.</li> </ul> <p>With this EIP in place, the 'happy-path' would work as previously, and the 'notorious'-path where <code>recipient</code> does not exist would cost an extra <code>penalty</code> gas, but the actual execution-flow would be unchanged.</p> <h4 id="erc223">ERC223</h4> <p><a rel="external" href="https://github.com/ethereum/EIPs/issues/223">ERC223 Token Standard</a> is, at the time of writing, marked as 'Draft', but is deployed and in use on mainnet today.</p> <p>The ERC specifies that when a token <code>transfer(_to,...)</code> method is invoked, then:</p> <blockquote> <p>This function must transfer tokens and invoke the function <code>tokenFallback (address, uint256, bytes)</code> in <code>_to</code>, if <code>_to</code> is a contract. ... NOTE: The recommended way to check whether the <code>_to</code> is a contract or an address is to assemble the code of <code>_to</code>. If there is no code in <code>_to</code>, then this is an externally owned address, otherwise it's a contract.</p> </blockquote> <p>The reference implementations from <a rel="external" href="https://github.com/Dexaran/ERC223-token-standard/tree/development/token/ERC223">Dexaran</a> and <a rel="external" href="https://github.com/OpenZeppelin/openzeppelin-contracts/blob/1bc923b6a222e79a90f20305a459b0ee779eb918/contracts/token/ERC721/ERC721.sol#L499">OpenZeppelin</a> both implement the <code>isContract</code> check using an <code>EXTCODESIZE</code> invocation.</p> <p>This scenario <em>could</em> be affected, but in practice should not be. Let's consider the possibilities:</p> <ol> <li>The <code>_to</code> is a contract: Then <code>ERC223</code> specifies that the function <code>tokenFallback(...)</code> is invoked. <ul> <li>The gas expenditure for that call is at least<code>700</code> gas.</li> <li>In order for the <code>callee</code> to be able to perform any action, best practice it to ensure that it has at least <code>2300</code> gas along with the call.</li> <li>In summary: this path requires there to be least <code>3000</code> extra gas available (which is not due to any <code>penalty</code>)</li> </ul> </li> <li>The <code>_to</code> exists, but is no contract. The flow exits here, and is not affected by this EIP</li> <li>The <code>_to</code> does not exist: A <code>penalty</code> is deducted.</li> </ol> <p>In summary, it would seem that <code>ERC223</code> should not be affected, as long as the <code>penalty</code> does not go above around <code>3000</code> gas.</p> <h3 id="other">Other</h3> <p>The contract <a rel="external" href="https://etherscan.io/address/0x08d32b0da63e2c3bcf8019c9c5d849d7a9d791e6#code"><code>Dentacoin</code></a> would be affected.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> function transfer(address _to, uint256 _value) returns (bool success) {</span></span> <span class="giallo-l"><span> ... // omitted for brevity</span></span> <span class="giallo-l"><span> if (balances[msg.sender] &gt;= _value &amp;&amp; balances[_to] + _value &gt; balances[_to]) { // Check if sender has enough and for overflows</span></span> <span class="giallo-l"><span> balances[msg.sender] = safeSub(balances[msg.sender], _value); // Subtract DCN from the sender</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if (msg.sender.balance &gt;= minBalanceForAccounts &amp;&amp; _to.balance &gt;= minBalanceForAccounts) { // Check if sender can pay gas and if recipient could</span></span> <span class="giallo-l"><span> balances[_to] = safeAdd(balances[_to], _value); // Add the same amount of DCN to the recipient</span></span> <span class="giallo-l"><span> Transfer(msg.sender, _to, _value); // Notify anyone listening that this transfer took place</span></span> <span class="giallo-l"><span> return true;</span></span> <span class="giallo-l"><span> } else {</span></span> <span class="giallo-l"><span> balances[this] = safeAdd(balances[this], DCNForGas); // Pay DCNForGas to the contract</span></span> <span class="giallo-l"><span> balances[_to] = safeAdd(balances[_to], safeSub(_value, DCNForGas)); // Recipient balance -DCNForGas</span></span> <span class="giallo-l"><span> Transfer(msg.sender, _to, safeSub(_value, DCNForGas)); // Notify anyone listening that this transfer took place</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if(msg.sender.balance &lt; minBalanceForAccounts) {</span></span> <span class="giallo-l"><span> if(!msg.sender.send(gasForDCN)) throw; // Send eth to sender</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> if(_to.balance &lt; minBalanceForAccounts) {</span></span> <span class="giallo-l"><span> if(!_to.send(gasForDCN)) throw; // Send eth to recipient</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> } else { throw; }</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>The contract checks <code>_to.balance &gt;= minBalanceForAccounts</code>, and if the <code>balance</code> is too low, some <code>DCN</code> is converted to <code>ether</code> and sent to the <code>_to</code>. This is a mechanism to ease on-boarding, whereby a new user who has received some <code>DCN</code> can immediately create a transaction.</p> <p>Before this EIP:</p> <ul> <li>When sending <code>DCN</code> to a non-existing address, the additional <code>gas</code> expenditure would be: <ul> <li><code>9000</code> for an ether-transfer</li> <li><code>25000</code> for a new account-creation</li> <li>(<code>2300</code> would be refunded to the caller later)</li> <li>A total runtime <code>gas</code>-cost of <code>34K</code> gas would be required to handle this case.</li> </ul> </li> </ul> <p>After this EIP:</p> <ul> <li>In addition to the <code>34K</code> an additional <code>penalty</code> would be added. <ul> <li>Possibly two, since the reference implementation does the balance-check twice, but it's unclear whether the compiled code would indeed perform the check twice.</li> </ul> </li> <li>A total runtime <code>gas</code>-cost of <code>34K+penalty</code> (or <code>34K + 2 * penalty</code>) would be required to handle this case.</li> </ul> <p>It can be argued that the extra penalty of <code>2-3K</code> gas can be considered marginal in relation to the other <code>34K</code> gas already required to handle this.</p> <h2 id="test-cases">Test Cases</h2> <p>The following cases need to be considered and tested:</p> <ul> <li>That during creation of a brand new contract, within the constructor, the <code>penalty</code> should not be applied for calls concerning the self-address.</li> <li>TBD: How the <code>penalty</code> is applied in the case of a contract which has performed a <code>selfdestruct</code> <ul> <li>a) previously in the same call-context,</li> <li>b) previously in the same transaction,</li> <li>c) previously in the same block, For any variant of <code>EXTCODEHASH(destructed)</code>, <code>CALL(destructed)</code>, <code>CALLCODE(destructed)</code> etc.</li> </ul> </li> <li>The effects on a <code>transaction</code> with <code>0</code> value going to a non-existent account.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>See 'Backwards Compatibility'</p> <h2 id="implementation">Implementation</h2> <p>Not yet available.</p> <h2 id="alternative-variants">Alternative variants</h2> <h3 id="alt-1-insta-refunds">Alt 1: Insta-refunds</h3> <p>Bump all trie accesses with <code>penalty</code>. <code>EXTCODEHASH</code> becomes <code>2700</code> instead of <code>700</code>.</p> <ul> <li>If a trie access hit an existing item, immediately refund penalty (<code>2K</code> )</li> </ul> <p>Upside:</p> <ul> <li>This eliminates the 'shielded relay' attack</li> </ul> <p>Downside:</p> <ul> <li>This increases the up-front cost of many ops (CALL/EXTCODEHASH/EXTCODESIZE/STATICCALL/EXTCODESIZE etc) <ul> <li>Which may break many contracts.</li> </ul> </li> </ul> <h3 id="alt-2-parent-bail">Alt 2: Parent bail</h3> <p>Use <code>penalty</code> as described, but if a child context goes OOG on the <code>penalty</code>, then the remainder is subtracted from the parent context (recursively).</p> <p>Upside:</p> <ul> <li>This eliminates the 'shielded relay' attack</li> </ul> <p>Downside:</p> <ul> <li>This breaks the current invariant that a child context is limited by whatever <code>gas</code> was allocated for it. <ul> <li>However, the invariant is not <em>totally</em> thrown out, the new invariant becomes that it is limited to <code>gas + penalty</code>.</li> </ul> </li> <li>This can be seen as 'messy' -- since only <em>some</em> types of OOG (penalties) becomes passed up the call chain, but not others, e.g. OOG due to trying to allocate too much memory. There is a distinction, however: <ul> <li>Gas-costs which arise due to not-yet-consumed resources do not get passed to parent. For example: a huge allocation is not actually performed if there is insufficient gas.</li> <li>Whereas gas-costs which arise due to already-consumed resources <em>do</em> get passed to parent; in this case the penalty is paid post-facto for a trie iteration.</li> </ul> </li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-02-19T00:00:00+00:00 2026-02-11T14:48:25+00:00 Hadrien Crouboishttps://github.com/amxx https://wg-eips.ritovision.com/2525/ <h2 id="1-abstract">1. Abstract</h2> <p>This presents a method to improve a universal method of login to the ethereum blockchain, leveraging the metadata storage provided by the ENS. We consider a user to be logged in when we have an <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a> provider that can sign transaction and messages on his behalf. This method is inspired by <a rel="external" href="https://www.youtube.com/watch?v=1LVwWknE-NQ">Alex Van de Sande's work</a> and <a rel="external" href="https://web3connect.com">Web3Connect</a>. In the future, the approach described here-after should be extended to work with any blockchain.</p> <h2 id="2-motivation">2. Motivation</h2> <p>Multiple wallet solutions can be used to interact with the Ethereum blockchain. Some (metamask, gnosis, ...) are compatible as they inject a standardized wallet object in the browser without requiring any effort from the Dapp developers, but they require an effort on the user side (user has to install the plugin). Other solutions (Portis, Authereum, Torus, Universal Login, ...) propose a more seamless flow to non-crypto-aware users but require an integration effort from the Dapp developers. Hardware wallet (ledger, trezor, keepkey, ...) also require integration effort from the Dapp developers.</p> <p>When Dapps integrate login with multiple solutions, they rely on the user choosing the correct wallet-provider. This could prove increasingly difficult as the number of wallet-provider increases, particularly for novice users. Additionally, if decentralized applications pick and choose only a handful of wallets to support, the current incumbent wallets will have a distinct advantage and new wallets will struggle to find adoption. This will create a less competitive environment and stifle innovation. Rather than relying on the user choosing which wallet-provider to connect with (as does Web3Connect), ENSLogin proposes to use user-owned ENS domain as entry points. Metadata attached to these ENS domains is used to detect which wallet-provider if used by the corresponding account.</p> <p>That way, ENSLogin would allow any user to connect to any Dapp with any wallet, using a simple domain as a login.</p> <h2 id="3-description">3. Description</h2> <h3 id="3-1-overview">3.1. Overview</h3> <p>The ENSLogin works as follow:</p> <ul> <li>Request an ENS domain from the user</li> <li>Resolve the ENS domain to retrieve (see <a href="https://wg-eips.ritovision.com/137/">EIP-137</a>) <ul> <li>An address (see <a href="https://wg-eips.ritovision.com/137/">EIP-137</a>)</li> <li>A text entry (see <a href="https://wg-eips.ritovision.com/634/">EIP-634</a>)</li> </ul> </li> <li>Interpret the text entry and download the file it points to</li> <li>Evaluate the content of the downloaded file</li> <li>Return the corresponding object to the Dapp</li> </ul> <p>At this point, the app should process like with any web3 provider. Calling the <code>enable()</code> functions should ask the users for wallet specific credentials is needed.</p> <p>This workflow is to be implemented by an SDK that Dapp could easily import. The SDK would contain the resolution mechanism and support for both centralized and decentralized storage solution. Wallet-provider specific code should NOT be part of SDK. Wallet-provider specific code should only be present in the external file used to generate the web3 provider.</p> <h3 id="3-2-details">3.2. Details</h3> <ul> <li> <p><strong>Text entry resolution:</strong> A pointer to the code needed to instantiate the wallet-provider is recorded using the ENS support for text entries (see <a href="https://wg-eips.ritovision.com/634/">EIP-634</a>). The corresponding key is <code>enslogin</code> (<strong>subject to change</strong>). If no value is associated with the key <code>enslogin</code> at the targeted domain, we fallback to metadata store on the parent's node with the key <code>enslogin-default</code> (<strong>subject to change</strong>). <strong>Example:</strong> for the ens domain <code>username.domain.eth</code>, the resolution would look for (in order):</p> <ul> <li><code>resolver.at(ens.owner(nodehash("username.domain.eth"))).text(nodehash("username.domain.eth"), 'enslogin')</code></li> <li><code>resolver.at(ens.owner(nodehash("domain.eth"))).text(nodehash("domain.eth"), 'enslogin-default')</code></li> </ul> </li> <li> <p><strong>Provider link:</strong> Code for instantiating the wallet-provider must be pointed to in a standardized manner. <strong>This is yet not specified.</strong> The current approach uses a human-readable format <code>scheme://path</code> such as:</p> <ul> <li> <p><code>ipfs://Qm12345678901234567890123456789012345678901234</code></p> </li> <li> <p><code>https://server.com/enslogin-module-someprovider</code> And adds a suffix depending on the targeted blockchain type (see <a rel="external" href="https://github.com/satoshilabs/slips/blob/master/./00044.md">SLIP 44</a>) and language. Canonical case is a webapp using ethereum so the target would be:</p> </li> <li> <p><code>ipfs://Qm12345678901234567890123456789012345678901234/60/js</code></p> </li> <li> <p><code>https://server.com/enslogin-module-someprovider/60/js</code> Note that this suffix mechanism is compatible with http/https as well as IPFS. It is a constraint on the storage layer as some may not be able to do this kind of resolution.</p> </li> </ul> </li> <li> <p><strong>Provider instantiation:</strong></p> <ul> <li>[JAVASCRIPT/ETHEREUM] The file containing the wallet-provider's code should inject a function <code>global.provider: (config) =&gt; Promise&lt;web3provider&gt;</code> that returns a promise to a standardized provider object. For EVM blockchains, the object should follow <a href="https://wg-eips.ritovision.com/1193/">EIP-1193</a>.</li> <li>Other blockchain types/langages should be detailed in the future.</li> </ul> </li> <li> <p><strong>Configuration object:</strong> In addition to the username (ENS domain), the Dapp should have the ability to pass a configuration object that could be used by the wallet-provider instantiating function. This configuration should include:</p> <ul> <li>A body (common to all provider) that specify details about the targeted chain (network name / node, address of the ens entrypoint ...). If any of these are missing, a fallback can be used (mainnet as a default network, bootstrapping an in-browser IPFS node, ...).</li> <li>Wallet provider-specific fields (<strong>optional</strong>, starting with one underscore <code>_</code>) can be added to pass additional, wallet-provider specific, parameters / debugging flags.</li> <li>SDK specific fields (<strong>optional</strong>, starting with two underscores <code>__</code>) can be used to pass additional arguments. Minimal configuration:</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> provider: {</span></span> <span class="giallo-l"><span> network: &#39;goerli&#39;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Example of advanced configuration object:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> provider: {</span></span> <span class="giallo-l"><span> network: &#39;goerli&#39;,</span></span> <span class="giallo-l"><span> ens: &#39;0x112234455c3a32fd11230c42e7bccd4a84e02010&#39;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> ipfs: {</span></span> <span class="giallo-l"><span> host: &#39;ipfs.infura.io&#39;,</span></span> <span class="giallo-l"><span> port: 5001,</span></span> <span class="giallo-l"><span> protocol: &#39;https&#39;</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> _authereum: {...},</span></span> <span class="giallo-l"><span> _portis: {...},</span></span> <span class="giallo-l"><span> _unilogin: {...},</span></span> <span class="giallo-l"><span> _torus: {...},</span></span> <span class="giallo-l"><span> __callbacks: {</span></span> <span class="giallo-l"><span> resolved: (username, addr, descr) =&gt; {</span></span> <span class="giallo-l"><span> console.log(`[CALLBACKS] resolved: ${username} ${addr} ${descr}`);</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> loading: (protocol, path) =&gt; {</span></span> <span class="giallo-l"><span> console.log(`[CALLBACKS] loading: ${protocol} ${path}`);</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> loaded: (protocol, path) =&gt; {</span></span> <span class="giallo-l"><span> console.log(`[CALLBACKS] loaded: ${protocol} ${path}`);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre></li> </ul> <p><strong>TODO</strong> <em>(maybe move that part to section 6.1)</em>: Add <a rel="external" href="https://github.com/satoshilabs/slips/blob/master/./00044.md">SLIP 44</a> compliant blockchain description to the config for better multichain support. This will require a additional field <code>ENS network</code> to know which ethereum network to use for resolution when the targeted blockchain/network is not ethereum (could also be used for cross chain resolution on ethereum, for example xDAI login with metadata stored on mainnet)</p> <h3 id="3-3-decentralization">3.3. Decentralization</h3> <p>Unlike solution like Web3Connect, ENSLogin proposes a modular approach that is decentralized by nature. The code needed for a Dapp to use ENSLogin (hereafter referred to as the SDK) only contains lookup mechanism for the ethereum blockchain and the data storages solutions. The solution is limited by the protocols (https / ipfs / ...) that the SDK can interact with. Beyond that, any wallet-provider that follows the expected structure and that is available through one of the supported protocol is automatically compatible with all the Dapps proposing ENSLogin support. There is no need to go through a centralized approval process. Furthermore, deployed SDK do not need to be upgraded to benefit from the latest wallet updates. The only permissioned part of the protocol is in the ENS control of the users over the metadata that describes their wallet-provider implementation. Users could also rely on the fallback mechanism to have the wallet-provider update it for them.</p> <h3 id="3-4-incentives">3.4. Incentives</h3> <p>We believe ENSLogin's biggest strength is the fact that it aligns the incentives of Dapp developers and wallet-providers to follow this standard.</p> <ul> <li>A wallet-provider that implements the required file and make them available will ensure the compatibility of its wallet with all Dapps using ENSLogin. This will remove the burden of asking all Dapps to integrate their solutions, which Dapps are unlikely to do until the wallet as strong userbase. Consequently, ENSLogin will improve the competition between wallet-providers and encourage innovation in that space</li> <li>A Dapp that uses ENSLogin protocol, either by including the ENSLogin's SDK or by implementing compatible behaviour, will make itself available to all the users of all the compatible wallet. At some point, being compatible with ENSLogin will be the easiest to reach a large user-base.</li> <li>ENSLogin should be mostly transparent for the users. Most wallet provider will set up the necessary entries without requiring any effort from the user. Advanced users can take control over the wallet resolution process, which will be simple once the right tooling is available.</li> </ul> <h3 id="3-5-drawbacks">3.5. Drawbacks</h3> <p>While ENSLogin allows dapps to support any wallet for logging in, dapps still must choose which wallets they suggest to users for registration. This can be done through a component like Web3Connect or BlockNative's</p> <h2 id="4-prototype">4. Prototype</h2> <p><strong>TODO</strong></p> <h2 id="5-support-by-the-community">5. Support by the community</h2> <h3 id="5-1-adoption">5.1. Adoption</h3> <table><thead><tr><th>Name</th><th>Live</th><th>Module</th><th>Assigns ENS names</th><th>support by default</th></tr></thead><tbody> <tr><td>Argent</td><td>yes</td><td>no</td><td>yes</td><td>no</td></tr> <tr><td>Authereum</td><td>yes</td><td>yes</td><td>yes</td><td>no</td></tr> <tr><td>Fortmatic</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr> <tr><td>Gnosis Safe</td><td>yes</td><td>yes*</td><td>no</td><td>no</td></tr> <tr><td>Ledger</td><td>yes</td><td>beta</td><td>no</td><td>no</td></tr> <tr><td>KeepKey</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr> <tr><td>Metamask</td><td>yes</td><td>yes</td><td>no</td><td>no</td></tr> <tr><td>Opera</td><td>yes</td><td>yes*</td><td>no</td><td>no</td></tr> <tr><td>Portis</td><td>yes</td><td>yes</td><td>no</td><td>no</td></tr> <tr><td>SquareLink</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr> <tr><td>Shipl</td><td>no</td><td>no</td><td>no</td><td>no</td></tr> <tr><td>Torus</td><td>yes</td><td>yes</td><td>no</td><td>no</td></tr> <tr><td>Trezor</td><td>yes</td><td>no</td><td>no</td><td>no</td></tr> <tr><td>UniLogin</td><td>beta</td><td>beta</td><td>yes</td><td>no</td></tr> </tbody></table> <p>*use the metamask module</p> <h2 id="6-possible-evolutions">6. Possible evolutions</h2> <h3 id="6-1-multichain-support">6.1. Multichain support</h3> <p><strong>TODO</strong></p> <h2 id="7-faq">7. FAQ</h2> <h3 id="7-1-can-anyone-connect-with-my-login-where-are-my-private-keys-stored">7.1. Can anyone connect with my login? Where are my private keys stored?</h3> <p>ENSLogin only has access to what is recorded on the ENS, namely your address and the provider you use. Private key management is a is handled by the provider and is outside ENSLogin's scope. Some might store the key on disk. Other might rely on custodial keys stored on a remote (hopefully secure) server. Others might use a dedicated hardware component to handle signature and never directly have access to the private key.</p> <h3 id="7-2-how-do-i-get-an-ens-login">7.2. How do I get an ENS Login?</h3> <p><strong>TODO</strong> (this might need a separate ERC)</p> 2020-02-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Filip Štamcarhttps://github.com/filips123 https://wg-eips.ritovision.com/2520/ <h2 id="simple-summary">Simple Summary</h2> <p>ENS support for multiple <code>contenthash</code> records on a single ENS name.</p> <h2 id="motivation">Motivation</h2> <p>Many applications are resolving ENS names to content hosted on distributed systems. To do this, they use <code>contenthash</code> record from ENS domain to know how to resolve names and which distributed system should be used.</p> <p>However, the domain can store only one <code>contenthash</code> record which means that the site owner needs to decide which hosting system to use. Because there are many ENS-compatible hosting systems available (IPFS, Swarm, recently Onion and ZeroNet), and there will probably be even more in the future, lack of support for multiple records could become problematic. Instead, domains should be able to store multiple <code>contenthash</code> records to allow applications to resolve to multiple hosting systems.</p> <h2 id="specification">Specification</h2> <p>Setting and getting functions <strong>MUST</strong> have the same public interface as specified in EIP 1577. Additionally, they <strong>MUST</strong> also have new public interfaces introduced by this EIP:</p> <ul> <li> <p>For setting a <code>contenthash</code> record, the <code>setContenthash</code> <strong>MUST</strong> provide additional <code>proto</code> parameter and use it to save the <code>contenthash</code>. When <code>proto</code> is not provided, it <strong>MUST</strong> save the record as default record.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setContenthash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proto</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> hash</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> authorised</span><span>(</span><span class="z-entity z-name">node</span><span>)</span><span>;</span></span></code></pre></li> <li> <p>For getting a <code>contenthash</code> record, the <code>contenthash</code> <strong>MUST</strong> provide additional <code>proto</code> parameter and use it to get the <code>contenthash</code> for requested type. When <code>proto</code> is not provided, it <strong>MUST</strong> return the default record.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> contenthash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proto</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre></li> <li> <p>Resolver that supports multiple <code>contenthash</code> records <strong>MUST</strong> return <code>true</code> for <code>supportsInterface</code> with interface ID <code>0x6de03e07</code>.</p> </li> </ul> <p>Applications that are using ENS <code>contenthash</code> records <strong>SHOULD</strong> handle them in the following way:</p> <ul> <li> <p>If the application only supports one hosting system (like directly handling ENS from IPFS/Swarm gateways), it <strong>SHOULD</strong> request <code>contenthash</code> with a specific type. The contract <strong>MUST</strong> then return it and application <strong>SHOULD</strong> correctly handle it.</p> </li> <li> <p>If the application supports multiple hosting systems (like MetaMask), it <strong>SHOULD</strong> request <code>contenthash</code> without a specific type (like in EIP 1577). The contract <strong>MUST</strong> then return the default <code>contenthash</code> record.</p> </li> </ul> <h2 id="rationale">Rationale</h2> <p>The proposed implementation was chosen because it is simple to implement and supports all important requested features. However, it doesn't support multiple records for the same type and priority order, as they don't give much advantage and are harder to implement properly.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The EIP is backwards-compatible with EIP 1577, the only differences are additional overloaded methods. Old applications will still be able to function correctly, as they will receive the default <code>contenthash</code> record.</p> <h2 id="implementation">Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ContentHashResolver</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> private</span><span> MULTI_CONTENT_HASH_INTERFACE_ID </span><span class="z-keyword">=</span><span class="z-constant"> 0x6de03e07</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword">=&gt;</span><span class="z-storage z-type">mapping</span><span>(</span><span class="z-support">bytes</span><span class="z-keyword">=&gt;</span><span class="z-support">bytes</span><span>)</span><span>)</span><span> hashes</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setContenthash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proto</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> hash</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> hashes</span><span>[</span><span>node</span><span>]</span><span>[</span><span>proto</span><span>]</span><span class="z-keyword"> =</span><span> hash</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> ContenthashChanged</span><span>(</span><span>node</span><span>,</span><span> hash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> contenthash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proto</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> hashes</span><span>[</span><span>node</span><span>]</span><span>[</span><span>proto</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> interfaceID </span><span class="z-keyword">==</span><span> MULTI_CONTENT_HASH_INTERFACE_ID</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-02-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Hancockhttps://github.com/madeoftin https://wg-eips.ritovision.com/2515/ <h2 id="simple-summary">Simple Summary</h2> <p>The difficulty Freeze is an alternative to the Difficulty Bomb that is implemented within the protocols difficulty adjustment algorithm. The Difficulty Freeze begins at a certain block height, determined in advance, freezes the difficulty and increases by 1% after that block forever. This does not stop the chain, but it incentivizes devs to upgrade at a regular cadence and requires any chain split to address the difficulty freeze.</p> <h2 id="abstract">Abstract</h2> <p>The difficulty Freeze is a mechanism that is easy to predict and model, and the pressures of missing it are more readily felt by the core developers and client maintainers. The client maintainers are also positioned as the group that is most able to respond to an incoming Difficulty Freeze. This combined with the predictability is more likely to lead to the timely diffusual of the bomb.</p> <h2 id="motivation">Motivation</h2> <p>The current difficulty bombs' effect on the Block Time Targeting mechanism is rather complex to model, and it has both appeared when it was not expected (Muir Glacier) and negatively affected miners when they are not the target (in the case of delaying forks due to technical difficulties). Miners are affected by a reduction in block rewards due to the increase in block time. Users are affected as a function of the usability of the chain is affected by increased block times. Both of these groups are unable on their own to address the difficulty bomb. In the case of the Difficulty Freeze, the consequences of missing it are more directly felt by the client maintainers and it is more predictiable and so knowing when to make the change is readily apparent.</p> <h2 id="specification">Specification</h2> <p>Add variable <code>DIFFICULTY_FREEZE_HEIGHT</code></p> <p>The logic of the Difficulty Freeze is defined as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>if (BLOCK_HEIGHT &lt;= DIFFICULTY_FREEZE_HEIGHT):</span></span> <span class="giallo-l"><span> block_diff = parent_diff + parent_diff // 2048 * max(</span></span> <span class="giallo-l"><span> 1 - (block_timestamp - parent_timestamp) // 10, -99)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>else:</span></span> <span class="giallo-l"><span> block_diff = parent_diff + parent_diff * 0.01</span></span></code></pre> <p><strong>Optional Implementation</strong></p> <p>Add the variable <code>DIFFICULTY_FREEZE_DIFFERENCE</code> and use the <code>LAST_FORK_HEIGHT</code> to calculate when the Difficulty Freeze would occur.</p> <p>For example we can set the <code>DFD = 1,800,000 blocks</code> or approximately 9 months. The Difficulty Calculation would then be.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>if (BLOCK_HEIGHT &lt;= LAST_FORK_HEIGHT + DIFFICULTY_FREEZE_DIFFERENCE) :</span></span> <span class="giallo-l"><span> block_diff = parent_diff + parent_diff // 2048 * max(</span></span> <span class="giallo-l"><span> 1 - (block_timestamp - parent_timestamp) // 10, -99)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>else:</span></span> <span class="giallo-l"><span> block_diff = parent_diff + parent_diff * 0.01</span></span></code></pre> <p>This approach would have the added benefit that updating the Difficulty Freeze is easier as it happens automatically at the time of every upgrade. The trade-off is that the logic for checking is more complex and would require further analysis and test cases to ensure no consensus bugs arise.</p> <h2 id="rationale">Rationale</h2> <p>Block height is very easy to predict and evaluate within the system. This removes the effect of the Difficulty Bomb on block time, simplifying the block time targeting mechanism. The addition of an increase in the difficulty was added after feedback that the game theory of the mechanism did not reliably result in .</p> <p>https://twitter.com/quentinc137/status/1227110578235330562</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No backward incompatibilities</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>The effect of missing the Difficulty Freeze has a different impact than missing the Difficulty Bomb. At the point of a Difficulty freeze, the protocol is no longer able to adapt to changes in hash power on the network. This can lead to one of three scenarios.</p> <ul> <li>The Hash rate Increases: Block Times would increase on the network for short time until the increase in difficulty is too high for the network to add any more miners.</li> <li>The Hash rate decreases: Block times would increase.</li> <li>The Hash rate stays the same: A consistent increase in blocktimes.</li> </ul> <p>Clients are motivated to have their client sync fully to the network and so are very motivated to keep this situation from occurring. Simultaneously delaying the Difficulty Freeze is most easily implemented by client teams. Therefore the group that is most negatively affected is also the group that can most efficiently address it.</p> <h2 id="economic-considerations">Economic Considerations</h2> <p>Under the current Difficult, Bomb issuance of ETH is reduced as the Ice Age takes affect. Under the Difficulty Freeze, it is more likely that issuance would increase for a short time; however, clients are motivated to prevent this and keep clients syncing effectively. This means it is much less likely to occur. The increase to the difficulty over time will eventually reduce blocktimes and also issuance.</p> <p>It is also easy to predict when this change would happen, and stakeholders who are affected (Eth Holders) can keep client developers accountable by observing when the Difficulty Freeze is approaching and yell at them on twitter.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-01-29T00:00:00+00:00 2026-02-11T14:48:25+00:00 Barry WhiteHathttps://github.com/barryWhiteHat Marta Belléshttps://github.com/bellesmarta Jordi Baylinahttps://github.com/jbaylina https://wg-eips.ritovision.com/2494/ <h2 id="simple-summary">Simple Summary</h2> <p>This proposal defines Baby Jubjub, an elliptic curve designed to work inside zk-SNARK circuits in Ethereum.</p> <h2 id="abstract">Abstract</h2> <p>Two of the main issues behind why blockchain technology is not broadly used by individuals and industry are scalability and privacy guarantees. With a set of cryptographic tools called zero-knowledge proofs (ZKP) it is possible to address both of these problems. More specifically, the most suitable protocols for blockchain are called zk-SNARKs (zero-knowledge Succinct Non-interactive ARguments of Knowledge), as they are non-interactive, have succinct proof size and sublinear verification time. These types of protocols allow proving generic computational statements that can be modelled with arithmetic circuits defined over a finite field (also called zk-SNARK circuits).</p> <p>To verify a zk-SNARK proof, it is necessary to use an elliptic curve. In Ethereum, the curve is alt_bn128 (also referred as BN254), which has primer order <code>r</code>. With this curve, it is possible to generate and validate proofs of any <code>F_r</code>-arithmetic circuit. This EIP describes <em>Baby Jubjub</em>, an elliptic curve defined over the finite field <code>F_r</code> which can be used inside any zk-SNARK circuit, allowing for the implementation of cryptographic primitives that make use of elliptic curves, such as the Pedersen Hash or the Edwards Digital Signature Algorithm (EdDSA).</p> <h2 id="motivation">Motivation</h2> <p>A <a rel="external" href="https://en.wikipedia.org/wiki/Zero-knowledge_proof">zero knowledge proof</a> (ZKP) is a protocol that enables one party, the prover, to convince another, the verifier, that a statement is true without revealing any information beyond the veracity of the statement. <a rel="external" href="https://people.csail.mit.edu/silvio/Selected%20Scientific%20Papers/Zero%20Knowledge/Noninteractive_Zero-Knowkedge.pdf">Non-Interactive ZKPs</a> (NIZK) are a particular type of zero-knowledge proofs in which the prover can generate the proof without interaction with the verifier. NIZK protocols are very suitable for Ethereum applications, because they allow a smart contract to act as a verifier. This way, anyone can generate a proof and send it as part of a transaction to the smart contract, which can perform some action depending on whether the proof is valid or not. In this context, the most preferable NIZK are <a rel="external" href="https://eprint.iacr.org/2013/279.pdf">zk-SNARK</a> (Zero-knowledge Succinct Non Interactive ARgument of Knowledge), a set of non-interactive zero-knowledge protocols that have succinct proof size and sublinear verification time. The importance of these protocols is double: on the one hand, they help improve privacy guarantees, and on the other, they are a possible solution to scalability issues (e.g. see <a rel="external" href="https://github.com/barryWhiteHat/roll_up">zk-Rollup</a> project).</p> <p>Like most ZKPs, zk-SNARKs permit proving computational statements. For example, one can prove things like: the knowledge of a private key associated with a certain public key, the correct computation of a transaction, or the knowledge of the preimage of a particular hash. Importantly, one can do these things without leaking any information about the statements in question. In other words, without leaking any information about the private key, the transaction details, or the value of the preimage. More specifically, zk-SNARKs permit proving any computational statement that can be modelled with an <code>F_r</code>-arithmetic circuit, a circuit consisting of set of wires that carry values from the field <code>F_r</code> and connect them to addition and multiplication gates <code>mod r</code>. This type of circuits are often called zk-SNARK circuits.</p> <p>The implementation of most zk-SNARK protocols (e.g. <a rel="external" href="https://eprint.iacr.org/2013/279.pdf">[Pinnochio]</a> and <a rel="external" href="https://eprint.iacr.org/2016/260.pdf">[Groth16]</a>) make use of an elliptic curve for validating a proof. In Ethereum, the curve used is alt_bn128 (also referred as BN254), which has prime order <code>r</code>. While it is possible to generate and validate proofs of <code>F_r</code>-arithmetic circuits with BN254, it is not possible to use BN254 to implement elliptic-curve cryptography within these circuits. To implement functions that require the use of elliptic curves inside a zk-SNARK circuit -- such as the <a rel="external" href="https://github.com/zcash/zips/blob/master/protocol/protocol.pdf">Pedersen Hash</a> or the <a rel="external" href="https://tools.ietf.org/html/rfc8032">Edwards Digital Signature Algorithm</a> (EdDSA) -- a new curve with coordinates in <code>F_r</code> is needed. To this end, we propose in this EIP <em>Baby Jubjub</em>, an elliptic curve defined over <code>F_r</code> that can be used inside any <code>F_r</code>-arithmetic circuit. In the next sections we describe in detail the characteristics of the curve, how it was generated, and which security considerations were taken.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> inputs zk-SNARK (alt_bn128) output</span></span> <span class="giallo-l"><span> +--------------------------------------------+</span></span> <span class="giallo-l"><span> | +--------------------+ |</span></span> <span class="giallo-l"><span> ---&gt;| | EdDSA (Baby Jubjub)| |</span></span> <span class="giallo-l"><span> | +--------------------+ | </span></span> <span class="giallo-l"><span> ---&gt;| |---&gt;</span></span> <span class="giallo-l"><span> | +-----------------------------+ |</span></span> <span class="giallo-l"><span> ---&gt;| | Pedersen Hash (Baby Jubjub) | |</span></span> <span class="giallo-l"><span> | +-----------------------------+ |</span></span> <span class="giallo-l"><span> +--------------------------------------------+</span></span></code></pre><h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <p>Let <code>F_r</code> be the prime finite field with <code>r</code> elements, where</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>r = 21888242871839275222246405745257275088548364400416034343698204186575808495617</span></span></code></pre> <p>Let <code>E</code> be the twisted Edwards elliptic curve defined over <code>F_r</code> described by equation</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ax^2 + y^2 = 1 + dx^2y^2</span></span></code></pre> <p>with parameters</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>a = 168700</span></span> <span class="giallo-l"><span>d = 168696</span></span></code></pre> <p>We call <strong>Baby Jubjub</strong> the curve <code>E(F_r)</code>, that is, the subgroup of <code>F_r</code>-rational points of <code>E</code>.</p> <h3 id="order">Order</h3> <p>Baby Jubjub has order</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>n = 21888242871839275222246405745257275088614511777268538073601725287587578984328</span></span></code></pre> <p>which factors in</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>n = h x l</span></span></code></pre> <p>where</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>h = 8</span></span> <span class="giallo-l"><span>l = 2736030358979909402780800718157159386076813972158567259200215660948447373041</span></span></code></pre> <p>The parameter <code>h</code> is called <em>cofactor</em> and <code>l</code> is a prime number of 251 bits.</p> <h3 id="generator-point">Generator Point</h3> <p>The point <code>G = (x,y)</code> with coordinates</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>x = 995203441582195749578291179787384436505546430278305826713579947235728471134</span></span> <span class="giallo-l"><span>y = 5472060717959818805561601436314318772137091100104008585924551046643952123905</span></span></code></pre> <p>generates all <code>n</code> points of the curve.</p> <h3 id="base-point">Base Point</h3> <p>The point <code>B = (x,y)</code> with coordinates</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>x = 5299619240641551281634865583518297030282874472190772894086521144482721001553</span></span> <span class="giallo-l"><span>y = 16950150798460657717958625567821834550301663161624707787222815936182638968203</span></span></code></pre> <p>generates the subgroup of points <code>P</code> of Baby Jubjub satisfying <code>l * P = O</code>. That is, it generates the set of points of order <code>l</code> and origin <code>O</code>.</p> <h3 id="arithmetic">Arithmetic</h3> <p>Let <code>P1 = (x1, y1)</code> and <code>P2 = (x2, y2)</code> be two arbitrary points of Baby Jubjub. Then <code>P1 + P2 = (x3, y3)</code> is calculated in the following way:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>x3 = (x1*y2 + y1*x2)/(1 + d*x1*x2*y1*y2)</span></span> <span class="giallo-l"><span>y3 = (y1*y2 - a*x1*x2)/(1 - d*x1*x2*y1*y2)</span></span></code></pre> <p>Note that both addition and doubling of points can be computed using a single formula.</p> <h2 id="rationale">Rationale</h2> <p>The search for Baby Jubjub was motivated by the need for an elliptic curve that allows the implementation of elliptic-curve cryptography in <code>F_r</code>-arithmetic circuits. The curve choice was based on three main factors: type of curve, generation process and security criteria. This section describes how these factors were addressed.</p> <p><strong>Form of the Curve</strong></p> <p>Baby Jubjub is a <strong>twisted Edwards</strong> curve birationally equivalent to a <strong>Montgomery</strong> curve. The choice of this form of curve was based on the following facts:</p> <ol> <li>The Edwards-curve Digital Signature Scheme is based on twisted Edwards curves.</li> <li>Twisted Edwards curves have a single complete formula for addition of points, which makes the implementation of the group law inside circuits very efficient <a rel="external" href="https://eprint.iacr.org/2008/013.pdf">[Crypto08/013, Section 6]</a>.</li> <li>As a twisted Edwards curve is generally birationally equivalent to a Montgomery curve <a rel="external" href="https://eprint.iacr.org/2008/013.pdf">[Crypto08/13,Theorem 3.2]</a>, the curve can be easily converted from one form to another. As addition and doubling of points in a Montgomery curve can be performed very efficiently, computations outside the circuit can be done faster using this form and sped up inside circuits by combining it with twisted Edwards form (see <a rel="external" href="http://hyperelliptic.org/EFD/g1p/index.html">here</a>) for more details).</li> </ol> <p><strong>Generation of the Curve</strong></p> <p>Baby Jubjub was conceived as a solution to the circuit implementation of cryptographic schemes that require elliptic curves. As with any cryptographic protocol, it is important to reduce the possibility of a backdoor being present. As a result, we designed the generation process to be <strong>transparent</strong> and <strong>deterministic</strong> -- in order to make it clear that no external considerations were taken into account, and to ensure that the process can be reproduced and followed by anyone who wishes to do so.</p> <p>The algorithm chosen for generating Baby Jubjub is based in the criteria defined in <a rel="external" href="https://tools.ietf.org/html/rfc7748">[RFC7748, Appendix A.1]</a> and can be found in <a rel="external" href="https://github.com/barryWhiteHat/baby_jubjub">this github repository</a>. Essentially, the algorithm takes a prime number <code>p = 1 mod 4</code> and returns the lowest <code>A&gt;0</code> such that <code>A-2</code> is a multiple of 4 and such that the set of solutions in <code>F_p</code> of <code>y^2 = x^3 + Ax^2 + x</code> defines a Montgomery curve with cofactor 8.</p> <p>Baby Jubjub was generated by running the algorithm with the prime</p> <p><code>r = 21888242871839275222246405745257275088548364400416034343698204186575808495617</code>,</p> <p>which is the order of alt_bn128, the curve used to verify zk-SNARK proofs in Ethereum. The output of the algorithm was <code>A=168698</code>. Afterwards, the corresponding Montgomery curve was transformed into twisted Edwards form. Using SAGE libraries for curves, the order <code>n</code> of the curve and its factorization <code>n = 8*l</code> was calculated.</p> <ul> <li><strong>Choice of generator</strong> : the generator point <code>G</code> is the point of order <code>n</code> with smallest positive <code>x</code>-coordinate in <code>F_r</code>.</li> <li><strong>Choice of base point</strong>: the base point <code>B</code> is chosen to be <code>B = 8*G</code>, which has order <code>l</code>.</li> </ul> <p><strong>Security Criteria</strong></p> <p>It is crucial that Baby Jubjub be safe against well-known attacks. To that end, we decided that the curve should pass <a rel="external" href="https://safecurves.cr.yp.to/">SafeCurves</a> security tests, as they are known for gathering the best known attacks against elliptic curves. Supporting evidence that Baby Jubjub satisfies the SafeCurves criteria can be found <a rel="external" href="https://github.com/barryWhiteHat/baby_jubjub">here</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Baby Jubjub is a twisted Edwards elliptic curve birational to different curves. So far, the curve has mainly been used in its original form, in Montomgery form, and in another (different representation) twisted Edwards form -- which we call the reduced twisted Edwards form.</p> <p>Below are the three representations and the birational maps that make it possible to map points from one form of the curve to another. In all cases, the generator and base points are written in the form <strong><code>(x,y)</code>.</strong></p> <h3 id="forms-of-the-curve">Forms of the Curve</h3> <p>All generators and base points are written in the form (x,y).</p> <p><strong>Twisted Edwards Form</strong> (standard)</p> <ul> <li> <p>Equation: <code>ax^2 + y^2 = 1 + dx^2y^2</code></p> </li> <li> <p>Parameters: <code>a = 168700, d = 168696</code></p> </li> <li> <p>Generator point:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(995203441582195749578291179787384436505546430278305826713579947235728471134, 5472060717959818805561601436314318772137091100104008585924551046643952123905)</span></span></code></pre></li> <li> <p>Base point:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(5299619240641551281634865583518297030282874472190772894086521144482721001553, 16950150798460657717958625567821834550301663161624707787222815936182638968203)</span></span></code></pre></li> </ul> <p><strong>Montgomery Form</strong></p> <ul> <li> <p>Equation: <code>By^2 = x^3 + A x^2 + x</code></p> </li> <li> <p>Parameters: <code>A = 168698, B = 1</code></p> </li> <li> <p>Generator point:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(7, 4258727773875940690362607550498304598101071202821725296872974770776423442226)</span></span></code></pre></li> <li> <p>Base point:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(7117928050407583618111176421555214756675765419608405867398403713213306743542, 14577268218881899420966779687690205425227431577728659819975198491127179315626)</span></span></code></pre></li> </ul> <p><strong>Reduced Twisted Edwards Form</strong></p> <ul> <li> <p>Equation: <code>a' x^2 + y^2 = 1 + d' x^2y^2</code></p> </li> <li> <p>Parameters:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>a&#39; = -1 </span></span> <span class="giallo-l"><span>d&#39; = 12181644023421730124874158521699555681764249180949974110617291017600649128846</span></span></code></pre></li> <li> <p>Generator point:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(4986949742063700372957640167352107234059678269330781000560194578601267663727, 5472060717959818805561601436314318772137091100104008585924551046643952123905)</span></span></code></pre></li> <li> <p>Base point:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(9671717474070082183213120605117400219616337014328744928644933853176787189663, 16950150798460657717958625567821834550301663161624707787222815936182638968203)</span></span></code></pre></li> </ul> <h3 id="conversion-of-points">Conversion of Points</h3> <p>Following formulas allow to convert points from one form of the curve to another. We will denote the coordinates</p> <ul> <li><code>(u, v)</code> for points in the Montomgery form,</li> <li><code>(x, y)</code> for points in the Twisted Edwards form and</li> <li><code>(x', y')</code> for points in reduced Twisted Edwards form.</li> </ul> <p>Note that in the last conversion -- from Twisted Edwards to Reduced Twisted Edwards and back -- we also use the scaling factor <code>f</code>, where:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>f = 6360561867910373094066688120553762416144456282423235903351243436111059670888</span></span></code></pre> <p>In the expressions one can also use directly <code>-f</code>, where:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>-f = 15527681003928902128179717624703512672403908117992798440346960750464748824729</span></span></code></pre> <p><strong>Montgomery --&gt; Twisted Edwards</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(u, v) --&gt; (x, y)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>x = u/v</span></span> <span class="giallo-l"><span>y = (u-1)/(u+1)</span></span></code></pre> <p><strong>Twisted Edwards --&gt; Montgomery</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(x, y) --&gt; (u, v)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>u = (1+y)/(1-y) </span></span> <span class="giallo-l"><span>v = (1+y)/((1-y)x)</span></span></code></pre> <p><strong>Montgomery --&gt; Reduced Twisted Edwards</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(u, v) --&gt; (x&#39;, y&#39;)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>x&#39; = u*(-f)/v </span></span> <span class="giallo-l"><span>y&#39; = (u-1)/(u+1) </span></span></code></pre> <p><strong>Reduced Twisted Edwards --&gt; Montgomery</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(x&#39;, y&#39;) --&gt; (u, v)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>u = (1+y&#39;)/(1-y&#39;)</span></span> <span class="giallo-l"><span>v = (-f)*(1+y&#39;)/((1-y&#39;)*x&#39;)</span></span></code></pre> <p><strong>Twisted Edwards --&gt; Reduced Twisted Edwards</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(x, y) --&gt; (x&#39;, y&#39;)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>x&#39; = x*(-f)</span></span> <span class="giallo-l"><span>y&#39; = y</span></span></code></pre> <p><strong>Reduced Twisted Edwards --&gt; Twisted Edwards</strong></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(x&#39;, y&#39;) --&gt; (x, y)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>x = x&#39;/(-f)</span></span> <span class="giallo-l"><span>y = y&#39;</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This section specifies the safety checks done on Baby Jubjub. The choices of security parameters are based on <a rel="external" href="https://safecurves.cr.yp.to">SafeCurves criteria</a>, and supporting evidence that Baby Jubjub satisfies the following requisites can be found <a rel="external" href="https://github.com/barryWhiteHat/baby_jubjub">here</a>.</p> <p><strong>Curve Parameters</strong></p> <p>Check that all parameters in the specification of the curve describe a well-defined elliptic curve over a prime finite field.</p> <ul> <li>The number <code>r</code> is prime.</li> <li>Parameters <code>a</code> and <code>d</code> define an equation that corresponds to an elliptic curve.</li> <li>The product of <code>h</code> and <code>l</code> results into the order of the curve and the <code>G</code> point is a generator.</li> <li>The number <code>l</code> is prime and the <code>B</code> point has order <code>l</code>.</li> </ul> <p><strong>Elliptic Curve Discrete Logarithm Problem</strong></p> <p>Check that the discrete logarithm problem remains difficult in the given curve. We checked Baby Jubjub is resistant to the following known attacks.</p> <ul> <li><em>Rho method</em> <a rel="external" href="https://www.cambridge.org/core/books/elliptic-curves-in-cryptography/16A2B60636EFA7EBCC3D5A5D01F28546">[Blake-Seroussi-Smart, Section V.1]</a>: we require the cost for the rho method, which takes on average around <code>0.886*sqrt(l)</code> additions, to be above <code>2^100</code>.</li> <li><em>Additive and multiplicative transfers</em> <a rel="external" href="https://www.cambridge.org/core/books/elliptic-curves-in-cryptography/16A2B60636EFA7EBCC3D5A5D01F28546">[Blake-Seroussi-Smart, Section V.2]</a>: we require the embedding degree to be at least <code>(l − 1)/100</code>.</li> <li><em>High discriminant</em> <a rel="external" href="https://www.cambridge.org/core/books/elliptic-curves-in-cryptography/16A2B60636EFA7EBCC3D5A5D01F28546">[Blake-Seroussi-Smart, Section IX.3]</a>: we require the complex-multiplication field discriminant <code>D</code> to be larger than <code>2^100</code>.</li> </ul> <p><strong>Elliptic Curve Cryptography</strong></p> <ul> <li><em>Ladders</em> <a rel="external" href="https://wstein.org/edu/Fall2001/124/misc/montgomery.pdf">[Montgomery]</a>: check the curve supports the Montgomery ladder.</li> <li><em>Twists</em> <a rel="external" href="https://safecurves.cr.yp.to/twist.html">[SafeCurves, twist]</a>: check it is secure against the small-subgroup attack, invalid-curve attacks and twisted-attacks.</li> <li><em>Completeness</em> <a rel="external" href="https://safecurves.cr.yp.to/complete.html">[SafeCurves, complete]</a>: check if the curve has complete single-scalar and multiple-scalar formulas.</li> <li><em>Indistinguishability</em> <a rel="external" href="https://eprint.iacr.org/2013/325">[IACR2013/325]</a>: check availability of maps that turn elliptic-curve points indistinguishable from uniform random strings.</li> </ul> <h2 id="test-cases">Test Cases</h2> <p><strong>Test 1 (Addition)</strong></p> <p>Consider the points <code>P1 = (x1, y1)</code> and <code>P2 = (x2, y2)</code> with the following coordinates:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>x1 = 17777552123799933955779906779655732241715742912184938656739573121738514868268</span></span> <span class="giallo-l"><span>y1 = 2626589144620713026669568689430873010625803728049924121243784502389097019475</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>x2 = 16540640123574156134436876038791482806971768689494387082833631921987005038935</span></span> <span class="giallo-l"><span>y2 = 20819045374670962167435360035096875258406992893633759881276124905556507972311</span></span></code></pre> <p>Then their sum <code> P1+P2 = (x3, y3)</code> is equal to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>x3 = 7916061937171219682591368294088513039687205273691143098332585753343424131937</span></span> <span class="giallo-l"><span>y3 = 14035240266687799601661095864649209771790948434046947201833777492504781204499</span></span></code></pre> <p><strong>Test 2 (Doubling)</strong></p> <p>Consider the points <code>P1 = (x1, y1)</code> and <code>P2 = (x2, y2)</code> with the following coordinates:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>x1 = 17777552123799933955779906779655732241715742912184938656739573121738514868268,</span></span> <span class="giallo-l"><span>y1 = 2626589144620713026669568689430873010625803728049924121243784502389097019475</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>x2 = 17777552123799933955779906779655732241715742912184938656739573121738514868268</span></span> <span class="giallo-l"><span>y2 = 2626589144620713026669568689430873010625803728049924121243784502389097019475</span></span></code></pre> <p>Then their sum <code> P1+P2 = (x3, y3)</code> is equal to:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>x3 = 6890855772600357754907169075114257697580319025794532037257385534741338397365</span></span> <span class="giallo-l"><span>y3 = 4338620300185947561074059802482547481416142213883829469920100239455078257889</span></span></code></pre> <p><strong>Test 3 (Doubling the identity)</strong></p> <p>Consider the points <code>P1 = (x1, y1)</code> and <code>P2 = (x2, y2)</code> with the following coordinates:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>x1 = 0</span></span> <span class="giallo-l"><span>y1 = 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>x2 = 0</span></span> <span class="giallo-l"><span>y2 = 1</span></span></code></pre> <p>Then their sum <code> P1+P2 = (x3, y3)</code> results in the same point:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>x3 = 0</span></span> <span class="giallo-l"><span>y3 = 1</span></span></code></pre> <p><strong>Test 4 (Curve membership)</strong></p> <p>Point <code>(0,1)</code> is a point on Baby Jubjub.</p> <p>Point <code>(1,0)</code> is not a point on Baby Jubjub.</p> <p><strong>Test 5 (Base point choice)</strong></p> <p>Check that the base point <code> B = (Bx, By)</code> with coordinates</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Bx = 5299619240641551281634865583518297030282874472190772894086521144482721001553</span></span> <span class="giallo-l"><span>By = 16950150798460657717958625567821834550301663161624707787222815936182638968203</span></span></code></pre> <p>is 8 times the generator point <code>G = (Gx, Gy)</code>, where</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Gx = 995203441582195749578291179787384436505546430278305826713579947235728471134</span></span> <span class="giallo-l"><span>Gy = 5472060717959818805561601436314318772137091100104008585924551046643952123905</span></span></code></pre> <p>That is, check that <code>B = 8 x G</code>.</p> <p><strong>Test 6 (Base point order)</strong></p> <p>Check that the base point <code> B = (Bx, By)</code> with coordinates</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Bx = 5299619240641551281634865583518297030282874472190772894086521144482721001553</span></span> <span class="giallo-l"><span>By = 16950150798460657717958625567821834550301663161624707787222815936182638968203</span></span></code></pre> <p>multiplied by <code>l</code>, where</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>l = 2736030358979909402780800718157159386076813972158567259200215660948447373041</span></span></code></pre> <p>results in the origin point <code>O = (0, 1)</code>. This test checks that the base point <code>B</code> has order <code>l</code>.</p> <h2 id="implementation">Implementation</h2> <p>Arithmetic of Baby Jubjub and some cryptographic primitives using the curve have already been implemented in different languages. Here are a few such implementations:</p> <ul> <li>Python: https://github.com/barryWhiteHat/baby_jubjub_ecc</li> <li>JavaScript: https://github.com/iden3/circomlib/blob/master/src/babyjub.js</li> <li>Circuit (circom): https://github.com/iden3/circomlib/blob/master/circuits/babyjub.circom</li> <li>Rust: https://github.com/arnaucube/babyjubjub-rs</li> <li>Solidity: https://github.com/yondonfu/sol-baby-jubjub</li> <li>Go: https://github.com/iden3/go-iden3-crypto/tree/master/babyjub</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-01-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ricardo Guilherme Schmidthttps://github.com/3esmit https://wg-eips.ritovision.com/2474/ <h2 id="simple-summary">Simple Summary</h2> <p>Allow contracts to be called directly by <code>block.coinbase</code> (block validator), without a transaction.</p> <h2 id="abstract">Abstract</h2> <p><em>In proof-of-work blockchains, validators are known as miners.</em></p> <p>The validator might want to execute functions directly, without having to sign a transaction. Some examples might be presenting a proof in a contract for a change which also benefits the validator.</p> <p>A notable example would be when a validator want to act as an <a href="https://wg-eips.ritovision.com/1077/">EIP-1077</a> Gas Relayer, incentivized to pick up fees from meta transactions. Without this change, they can do so by signing from any address a <code>gasPrice = 0</code> transaction with the gas relayed call. However this brings an overhead of a signed transaction by validator that does nothing, as <code>msg.sender</code> is never used, and there is no gas cost to EVM charge.</p> <p>This proposal makes possible to remove this unused ecrecover.</p> <h2 id="motivation">Motivation</h2> <p>In order to reduce the overhead of calls that don't use <code>msg.sender</code> and are being called by validator with <code>tx.gasPrice = 0</code>.</p> <h2 id="specification">Specification</h2> <p>The calls to be executed by <code>block.coinbase</code> would be included first at block, and would consume normally the gas of block, however they won't pay/cost gas, instead the call logic would pay the validator in other form.</p> <p>Would be valid to execute any calls without a transaction by the block coinbase, except when the validator call tries to read <code>msg.sender</code>, which would throw an invalid jump.</p> <p>Calls included by the validator would have <code>tx.origin = block.coinbase</code> and <code>gas.price = 0</code> for the rest of call stack, the rest follows as normal calls.</p> <h2 id="rationale">Rationale</h2> <p>TBD</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>tx.origin = block.coinbase</code> could cause some issues on bad designed contracts, such as using <code>tx.origin</code> to validate a signature, an analysis on how contracts use tx.origin might be useful to decide if this is a good choice.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>TBD</p> <h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-01-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ricardo Guilherme Schmidthttps://github.com/3esmit https://wg-eips.ritovision.com/2470/ <h2 id="simple-summary">Simple Summary</h2> <p>Some DApps needs one, and only one, instance of an contract, which have the same address on any chain.</p> <p>A permissionless factory for deploy of keyless deterministic contracts addresses based on its bytecode.</p> <h2 id="abstract">Abstract</h2> <p>Some contracts are designed to be Singletons which have the same address no matter what chain they are, which means that should exist one instance for all, such as <a href="https://wg-eips.ritovision.com/1820/">EIP-1820</a> and <a rel="external" href="https://gitlab.com/status-im/docs/EIPs/blob/secret-multisig-recovery/EIPS/./02429.md">EIP-2429</a>. These contracts are usually deployed using a method known as <a rel="external" href="https://github.com/Arachnid/">Nick</a>'s method, so anyone can deploy those contracts on any chain and they have a deterministic address. This standard proposes the creation of a CREATE2 factory using this method, so other projects requiring this feature can use this factory in any chain with the same setup, even in development chains.</p> <h2 id="motivation">Motivation</h2> <p>Code reuse, using the factory becomes easier to deploy singletons.</p> <h2 id="specification">Specification</h2> <h3 id="erc-2470-singleton-factory">[ERC-2470] Singleton Factory</h3> <blockquote> <p>This is an exact copy of the code of the [ERC2470 factory smart contract].</p> </blockquote> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> 0.6.2</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> Singleton Factory (EIP-2470)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Exposes CREATE2 (EIP-1014) to deploy bytecode on deterministic addresses based on initialization code and salt.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@author</span><span class="z-comment"> Ricardo Guilherme Schmidt (Status Research &amp; Development GmbH)</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> SingletonFactory</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Deploys `_initCode` using `_salt` for defining the deterministic address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _initCode</span><span class="z-comment"> Initialization code.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _salt</span><span class="z-comment"> Arbitrary value to modify resulting address.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> createdContract</span><span class="z-comment"> Created contract address.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> deploy</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _initCode</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _salt</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> payable</span><span class="z-variable"> createdContract</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assembly</span><span> {</span></span> <span class="giallo-l"><span> createdContract </span><span class="z-keyword">:=</span><span class="z-entity z-name"> create2</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-entity z-name"> add</span><span>(</span><span>_initCode</span><span>,</span><span class="z-constant"> 0x20</span><span>)</span><span>,</span><span class="z-entity z-name"> mload</span><span>(</span><span>_initCode</span><span>)</span><span>,</span><span> _salt</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> IV is a value </span><span class="z-keyword">changed</span><span class="z-comment"> to generate the vanity address.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> IV: 6583047</span></span></code></pre><h3 id="deployment-transaction">Deployment Transaction</h3> <p>Below is the raw transaction which MUST be used to deploy the smart contract on any chain.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xf9016c8085174876e8008303c4d88080b90154608060405234801561001057600080fd5b50610134806100206000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c80634af63f0214602d575b600080fd5b60cf60048036036040811015604157600080fd5b810190602081018135640100000000811115605b57600080fd5b820183602082011115606c57600080fd5b80359060200191846001830284011164010000000083111715608d57600080fd5b91908080601f016020809104026020016040519081016040528093929190818152602001838380828437600092019190915250929550509135925060eb915050565b604080516001600160a01b039092168252519081900360200190f35b6000818351602085016000f5939250505056fea26469706673582212206b44f8a82cb6b156bfcc3dc6aadd6df4eefd204bc928a4397fd15dacf6d5320564736f6c634300060200331b83247000822470</span></span></code></pre> <p>The strings of <code>2470</code>'s at the end of the transaction are the <code>r</code> and <code>s</code> of the signature. From this deterministic pattern (generated by a human), anyone can deduce that no one knows the private key for the deployment account.</p> <h3 id="deployment-method">Deployment Method</h3> <p>This contract is going to be deployed using the keyless deployment method---also known as <a rel="external" href="https://github.com/Arachnid/">Nick</a>'s method---which relies on a single-use address. (See <a rel="external" href="https://medium.com/@weka/how-to-send-ether-to-11-440-people-187e332566b7">Nick's article</a> for more details). This method works as follows:</p> <ol> <li>Generate a transaction which deploys the contract from a new random account.</li> </ol> <ul> <li>This transaction MUST NOT use <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> in order to work on any chain.</li> <li>This transaction MUST have a relatively high gas price to be deployed on any chain. In this case, it is going to be 100 Gwei.</li> </ul> <ol start="2"> <li> <p>Forge a transaction with the following parameters:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> nonce</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> gasPrice</span><span>:</span><span class="z-constant"> 100000000000</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> value</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> data</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x608060405234801561001057600080fd5b50610134806100206000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c80634af63f0214602d575b600080fd5b60cf60048036036040811015604157600080fd5b810190602081018135640100000000811115605b57600080fd5b820183602082011115606c57600080fd5b80359060200191846001830284011164010000000083111715608d57600080fd5b91908080601f016020809104026020016040519081016040528093929190818152602001838380828437600092019190915250929550509135925060eb915050565b604080516001600160a01b039092168252519081900360200190f35b6000818351602085016000f5939250505056fea26469706673582212206b44f8a82cb6b156bfcc3dc6aadd6df4eefd204bc928a4397fd15dacf6d5320564736f6c63430006020033</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> gasLimit</span><span>:</span><span class="z-constant"> 247000</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> v</span><span>:</span><span class="z-constant"> 27</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> r</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x247000</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> s</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x2470</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <blockquote> <p>The <code>r</code> and <code>s</code> values, made of starting <code>2470</code>, are obviously a human determined value, instead of a real signature.</p> </blockquote> </li> <li> <p>We recover the sender of this transaction, i.e., the single-use deployment account.</p> <blockquote> <p>Thus we obtain an account that can broadcast that transaction, but we also have the warranty that nobody knows the private key of that account.</p> </blockquote> </li> <li> <p>Send exactly 0.0247 ether to this single-use deployment account.</p> </li> <li> <p>Broadcast the deployment transaction.</p> <blockquote> <p>Note: 247000 is the double of gas needed to deploy the smart contract, this ensures that future changes in OPCODE pricing are unlikely to cause this deploy transaction to fail out of gas. A left over will sit in the address of about 0.01 ETH will be forever locked in the single use address.</p> </blockquote> </li> </ol> <p>The resulting transaction hash is <code>0x803351deb6d745e91545a6a3e1c0ea3e9a6a02a1a4193b70edfcd2f40f71a01c</code>.</p> <p>This operation can be done on any chain, guaranteeing that the contract address is always the same and nobody can use that address with a different contract.</p> <h3 id="single-use-factory-deployment-account">Single-use Factory Deployment Account</h3> <p><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAYAAADDPmHLAAAB0UlEQVR4nO3asW1CQRBAQdpyCa6CIpxTjgujDGTJNEC2QqvjTbDx33c3P7vL79f1fzLf98dobn8/o5nuP53p/tPzm+5/AQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA4CMBnH6B0/23L2AbEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAJ8JYPsCtw+w3g9AvB+AeD8A8X4A4v0AxPsBiPcDEO8HIN4PQLwfgHg/APF+AOL9AMT7AYj3AxDvP/5ByOkApt/PvwgCAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADgJYDtA9w+gO0fYHsAAGB/CQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAOAdALYfNExnun+9H4B4PwDxfgDi/QDE+wGI9wMQ7wcg3g9AvB+AeD8A8X4A4v0AxPsBiPcDEO8HIN4/fhCy/aDidADb5wcAAGcHAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAO8CsH2ApwPY/j4Ah+8PAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPB6nlegoDNgrfyiAAAAAElFTkSuQmCC" alt="" /></p> <p><code>0xBb6e024b9cFFACB947A71991E386681B1Cd1477D</code></p> <p>This account is generated by reverse engineering it from its signature for the transaction. This way no one knows the private key, but it is known that it is the valid signer of the deployment transaction.</p> <blockquote> <p>To deploy the registry, 0.0247 ether MUST be sent to this account <em>first</em>.</p> </blockquote> <h3 id="factory-contract-address">Factory Contract Address</h3> <p><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIAAAACACAYAAADDPmHLAAABn0lEQVR4nO3coRECMRRF0S2GutCUQzd4WqAMLB4qQGWYP+EecXXeZo/OcTrf35Ndbq+l7F/rmB6w+wXuvh+A+H4A4vsBiO8HIL4fgPh+AOL7AYjvByC+H4D4fgDi+wGI7wcgvh+A+H4A4vuXAUxfwPX5GG33+wMAgL0/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPgGYHrA9A+cbhoQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA/wlgesD0+bvvXz0fgM33AwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAB8ATB9gZoNgHgAxAMgHgDxAIgHQDwA4gEQD4B4AMQDIB4A8QCIB0A8AOId0w8caK3V/wfA5gEQD4B4AMQDIB4A8QCIB0A8AOIBEA+AeADEAyAeAPEAiAdAPADiARAPgHgAxAMgHgDxAIgHQDwA4gEQD4B4AMQDIB4A8QCItwxg+oECDT8QMT1AAAgAASAABIAAEAACQAAIAAEgAASAANAv+gDxVDRR1CVqRAAAAABJRU5ErkJggg==" alt="" /></p> <p><code>0xce0042B868300000d44A59004Da54A005ffdcf9f</code></p> <p>The contract has the address above for every chain on which it is deployed.</p> <h3 id="abi-for-singletonfactory">ABI for SingletonFactory:</h3> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">constant</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">internalType</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bytes</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">_initCode</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bytes</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">internalType</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bytes32</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">_salt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bytes32</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">deploy</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">outputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">internalType</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address payable</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">createdContract</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">payable</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">stateMutability</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nonpayable</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">function</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>SingletonFactory does not allow sending value on create2, this was done to prevent different results on the created object. SingletonFactory allows user defined salt to facilitate the creation of vanity addresses for other projects. If vanity address is not necessary, salt <code>bytes(0)</code> should be used. Contracts that are constructed by the SingletonFactory MUST not use <code>msg.sender</code> in their constructor, all variables must came through initialization data. This is intentional, as if allowing a callback after creation to aid initialization state would lead to contracts with same address (but different chains) to have the same address but different initial state. The resulting address can be calculated in chain by any contract using this formula: <code>address(keccak256(bytes1(0xff), 0xce0042B868300000d44A59004Da54A005ffdcf9f, _salt, keccak256(_code)) &lt;&lt; 96)</code> or in javascript using https://github.com/ethereumjs/ethereumjs-util/blob/master/docs/README.md#const-generateaddress2.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Does not apply as there are no past versions of Singleton Factory being used.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>https://github.com/3esmit/ERC2470</p> <h2 id="security-considerations">Security Considerations</h2> <p>Some contracts can possibly not support being deployed on any chain, or require a different address per chain, that can be safely done by using comparison in <a href="https://wg-eips.ritovision.com/1344/">EIP-1344</a> in constructor. Account contracts are singletons in the point of view of each user, when wallets want to signal what chain id is intended, <a href="https://wg-eips.ritovision.com/1191/">EIP-1191</a> should be used. Contracts deployed on factory must not use <code>msg.sender</code> in constructor, instead use constructor parameters, otherwise the factory would end up being the controller/only owner of those.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2020-01-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kristijan Sedlakhttps://github.com/xpepermint William Entrikengithub.com@phor.net Witek Radomskiwitek@enjin.io https://wg-eips.ritovision.com/2477/ <h2 id="simple-summary">Simple Summary</h2> <p>This specification defines a mechanism by which clients may verify that a fetched token metadata document has been delivered without unexpected manipulation.</p> <p>This is the Web3 counterpart of the W3C Subresource Integrity (SRI) specification.</p> <h2 id="abstract">Abstract</h2> <p>An interface <code>ERC2477</code> with two functions <code>tokenURIIntegrity</code> and <code>tokenURISchemaIntegrity</code> are specified for smart contracts and a narrative is provided to explain how this improves the integrity of the token metadata documents.</p> <h2 id="motivation">Motivation</h2> <p>Tokens are being used in many applications to represent, trace and provide access to assets off-chain. These assets include in-game digital items in mobile apps, luxury watches and products in our global supply chain, among many other creative uses.</p> <p>Several token standards allow attaching metadata to specific tokens using a URI (RFC 3986) and these are supported by the applications mentioned above. These metadata standards are:</p> <ul> <li>ERC-721 metadata extension (<code>ERC721Metadata</code>)</li> <li>ERC-1155 metadata extension (<code>ERC1155Metadata_URI</code>)</li> <li>ERC-1046 (DRAFT) ERC-20 Metadata Extension</li> </ul> <p>Although all these standards allow storing the metadata entirely on-chain (using the "data" URI, RFC 2397), or using a content-addressable system (e.g. IPFS's Content IDentifiers [sic]), nearly every implementation we have found is using Uniform Resource Locators (the exception is The Sandbox which uses IPFS URIs). These URLs provide no guarantees of content correctness or immutability. This standard adds such guarantees.</p> <h2 id="design">Design</h2> <p><strong>Approach A:</strong> A token contract may reference metadata by using its URL. This provides no integrity protection because the referenced metadata and/or schema could change at any time if the hosted content is mutable. This is the world before EIP-2477:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌───────────────────────┐ ┌────────┐ ┌────────┐</span></span> <span class="giallo-l"><span>│ TokenID │──────▶│Metadata│─────▶│ Schema │</span></span> <span class="giallo-l"><span>└───────────────────────┘ └────────┘ └────────┘</span></span></code></pre> <p>Note: according to the JSON Schema project, a metadata document referencing a schema using a URI in the <code>$schema</code> key is a known approach, but it is not standardized.</p> <p><strong>Approach B:</strong> EIP-2477 provides mechanisms to establish integrity for these references. In one approach, there is integrity for the metadata document. Here, the on-chain data includes a hash of the metadata document. The metadata may or may not reference a schema. In this approach, changing the metadata document will require updating on-chain <code>tokenURIIntegrity</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌───────────────────────┐ ┌────────┐ ┌ ─ ─ ─ ─ </span></span> <span class="giallo-l"><span>│ TokenID │──────▶│Metadata│─ ─ ─▶ Schema │</span></span> <span class="giallo-l"><span>└───────────────────────┘ └────────┘ └ ─ ─ ─ ─ </span></span> <span class="giallo-l"><span>┌───────────────────────┐ ▲ </span></span> <span class="giallo-l"><span>│ tokenURIIntegrity │════════════╝ </span></span> <span class="giallo-l"><span>└───────────────────────┘ </span></span></code></pre> <p><strong>Approach C:</strong> In a stronger approach, the schema is referenced by the metadata using an extension to JSON Schema, providing integrity. In this approach, changing the metadata document or the schema will require updating on-chain <code>tokenURIIntegrity</code> and the metadata document, additionally changing the schema requires updating the on-chain <code>tokenURISchemaIntegrity</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌───────────────────────┐ ┌────────┐ ┌────────┐</span></span> <span class="giallo-l"><span>│ TokenID │──────▶│Metadata│═════▶│ Schema │</span></span> <span class="giallo-l"><span>└───────────────────────┘ └────────┘ └────────┘</span></span> <span class="giallo-l"><span>┌───────────────────────┐ ▲ </span></span> <span class="giallo-l"><span>│ tokenURIIntegrity │════════════╝ </span></span> <span class="giallo-l"><span>└───────────────────────┘ </span></span></code></pre> <p><strong>Approach D:</strong> Equally strong, the metadata can make a normal reference (no integrity protection) to the schema and on-chain data also includes a hash of the schema document. In this approach, changing the metadata document will require updating on-chain <code>tokenURIIntegrity</code> and updating the schema document will require updating the <code>tokenURISchemaIntegrity</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌───────────────────────┐ ┌────────┐ ┌────────┐</span></span> <span class="giallo-l"><span>│ TokenID │──────▶│Metadata│─────▶│ Schema │</span></span> <span class="giallo-l"><span>└───────────────────────┘ └────────┘ └────────┘</span></span> <span class="giallo-l"><span>┌───────────────────────┐ ▲ ▲ </span></span> <span class="giallo-l"><span>│ tokenURIIntegrity │════════════╝ ║ </span></span> <span class="giallo-l"><span>└───────────────────────┘ ║ </span></span> <span class="giallo-l"><span>┌───────────────────────┐ ║ </span></span> <span class="giallo-l"><span>│tokenURISchemaIntegrity│════════════════════════════╝ </span></span> <span class="giallo-l"><span>└───────────────────────┘</span></span></code></pre> <p><strong>Approach E:</strong> Lastly, the schema can be referenced with integrity from the metadata and also using on-chain data. In this approach, changing the metadata document or the schema will require updating on-chain <code>tokenURIIntegrity</code> and the metadata document, additionally changing the schema requires updating the on-chain <code>tokenURISchemaIntegrity</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>┌───────────────────────┐ ┌────────┐ ┌────────┐</span></span> <span class="giallo-l"><span>│ TokenID │──────▶│Metadata│═════▶│ Schema │</span></span> <span class="giallo-l"><span>└───────────────────────┘ └────────┘ └────────┘</span></span> <span class="giallo-l"><span>┌───────────────────────┐ ▲ ▲ </span></span> <span class="giallo-l"><span>│ tokenURIIntegrity │════════════╝ ║ </span></span> <span class="giallo-l"><span>└───────────────────────┘ ║ </span></span> <span class="giallo-l"><span>┌───────────────────────┐ ║ </span></span> <span class="giallo-l"><span>│tokenURISchemaIntegrity│════════════════════════════╝ </span></span> <span class="giallo-l"><span>└───────────────────────┘ </span></span></code></pre><h2 id="specification">Specification</h2> <p>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> <h3 id="smart-contracts">Smart contracts</h3> <p><strong>Smart contracts implementing the ERC-2477 standard MUST implement the <code>ERC2477</code> interface.</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> SPDX-License-Identifier: CC0-1.0</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.8.7</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-2477 Token Metadata Integrity</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See https://eips.ethereum.org/EIPS/eip-2477</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> The ERC-165 identifier for this interface is 0x832a7e0e</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC2477</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the cryptographic hash of the specified tokenID&#39;s metadata</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier for a specific token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> digest</span><span class="z-comment"> Bytes returned from the hash algorithm, or &quot;&quot; if not available</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> hashAlgorithm</span><span class="z-comment"> The name of the cryptographic hash algorithm, or &quot;&quot; if not available</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenURIIntegrity</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> digest</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> hashAlgorithm</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the cryptographic hash for the specified tokenID&#39;s metadata schema</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> Identifier for a specific token</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> digest</span><span class="z-comment"> Bytes returned from the hash algorithm, or &quot;&quot; if not available</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> hashAlgorithm</span><span class="z-comment"> The name of the cryptographic hash algorithm, or &quot;&quot; if not available</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokenURISchemaIntegrity</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> digest</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> hashAlgorithm</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The returned cryptographic hashes correspond to the token's metadata document and that metadata document's schema, respectively.</p> <p>For example, with ERC-721 <code>tokenURIIntegrity(21)</code> would correspond to <code>tokenURI(21)</code>. With ERC-1155, <code>tokenURIIntegrity(16)</code> would correspond to <code>uri(16)</code>. In both cases, <code>tokenURISchemaIntegrity(32)</code> would correspond to the schema of the document matched by <code>tokenURIIntegrity(32)</code>.</p> <p><strong>Smart contracts implementing the ERC-2477 standard MUST implement the ERC-165 standard, including the interface identifiers above.</strong></p> <p>Smart contracts implementing the ERC-2477 standard MAY use any hashing or content integrity scheme.</p> <p>Smart contracts implementing the ERC-2477 standard MAY use or omit a mechanism to notify when the integrity is updated (e.g. an Ethereum logging operation).</p> <p>Smart contracts implementing the ERC-2477 standard MAY use any mechanism to provide schemas for metadata documents and SHOULD use JSON-LD on the metadata document for this purpose (i.e. <code>"@schema":...</code>).</p> <h3 id="metadata">Metadata</h3> <p>A metadata document MAY conform to this schema to provide referential integrity to its schema document.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">EIP-2477 JSON Object With Refererential Integrity to Schema</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$schema</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uri</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$schemaIntegrity</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">digest</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hashAlgorithm</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">digest</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">hashAlgorithm</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">$schema</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">$schemaIntegrity</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="clients">Clients</h3> <p>A client implementing the ERC-2477 standard MUST support at least the <code>sha256</code> hash algorithm and MAY support other algorithms.</p> <h3 id="caveats">Caveats</h3> <ul> <li>This EIP metadata lists ERC-721 and ERC-1155 as "required" for implementation, due to a technical limitation of EIP metadata. In actuality, this standard is usable with any token implementation that has a <code>tokenURI(uint id)</code> or similar function.</li> </ul> <h2 id="rationale">Rationale</h2> <p><strong>Function and parameter naming</strong></p> <p>The W3C Subresource Integrity (SRI) specification uses the attribute "integrity" to perform integrity verification. This ERC-2477 standard provides a similar mechanism and reuses the integrity name so as to be familiar to people that have seen SRI before.</p> <p><strong>Function return tuple</strong></p> <p>The SRI integrity attribute encodes elements of the tuple $$(cryptographic\ hash\ function, digest, options)$$. This ERC-2477 standard returns a digest and hash function name and omits forward-compatibility options.</p> <p>Currently, the SRI specification does not make use of options. So we cannot know what format they might be when implemented. This is the motivation to exclude this parameter.</p> <p>The digest return value is first, this is an optimization because we expect on-chain implementations will be more likely to use this return value if they will only be using one of the two.</p> <p><strong>Function return types</strong></p> <p>The digest is a byte array and supports various hash lengths. This is consistent with SRI. Whereas SRI uses base64 encoding to target an HTML document, we use a byte array because Ethereum already allows this encoding.</p> <p>The hash function name is a string. Currently there is no universal taxonomy of hash function names. SRI recognizes the names <code>sha256</code>, <code>sha384</code> and <code>sha512</code> with case-insensitive matching. We are aware of two authorities which provide taxonomies and canonical names for hash functions: ETSI Object Identifiers and NIST Computer Security Objects Register. However, SRI's approach is easier to follow and we have adopted this here.</p> <p><strong>Function return type — hash length</strong></p> <p>Clients must support the SHA-256 algorithm and may optionally support others. This is a departure from the SRI specification where SHA-256, SHA-384 and SHA-512 are all required. The rationale for this less-secure requirement is because we expect some clients to be on-chain. Currently SHA-256 is simple and cheap to do on Ethereum whereas SHA-384 and SHA-512 are more expensive and cumbersome.</p> <p>The most popular hash function size below 256 bits in current use is SHA-1 at 160 bits. Multiple collisions (the "Shattered" PDF file, the 320 byte file, the chosen prefix) have been published and a recipe is given to generate infinitely more collisions. SHA-1 is broken. The United States National Institute of Standards and Technology (NIST) has first deprecated SHA-1 for certain use cases in November 2015 and has later further expanded this deprecation.</p> <p>The most popular hash function size above 256 bits in current use is SHA-384 as specified by NIST.</p> <p>The United States National Security Agency requires a hash length of 384 or more bits for the SHA-2 (CNSA Suite Factsheet) algorithm suite for use on TOP SECRET networks. (No unclassified documents are currently available to specify use cases at higher classification networks.)</p> <p>We suspect that SHA-256 and the 0xcert Asset Certification will be popular choices to secure token metadata for the foreseeable future.</p> <p><strong>In-band signaling</strong></p> <p>One possible way to achieve strong content integrity with the existing token standards would be to include, for example, a <code>?integrity=XXXXX</code> at the end of all URLs. This approach is not used by any existing implementations we know about. There are a few reasons we have not chosen this approach. The strongest reason is that the World Wide Web has the same problem and they chose to use the Sub-Resource Integrity approach, which is a separate data field than the URL.</p> <p>Other supplementary reasons are:</p> <ul> <li> <p>For on-chain consumers of data, it is easier to parse a direct hash field than to perform string operations.</p> </li> <li> <p>Maybe there are some URIs which are not amenable to being modified in that way, therefore limiting the generalizability of that approach.</p> </li> </ul> <p>This design justification also applies to <code>tokenURISchemaIntegrity</code>. The current JSON-LD specification allows a JSON document to link to a schema document. But it does not provide integrity. Rather than changing how JSON-LD works, or changing JSON Schemas, we have the <code>tokenURISchemaIntegrity</code> property to just provide the integrity.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Both ERC-721 and ERC-1155 provide compatible token metadata specifications that use URIs and JSON schemas. The ERC-2477 standard is compatible with both, and all specifications are additive. Therefore, there are no backward compatibility regressions.</p> <p>ERC-1523 Standard for Insurance Policies as ERC-721 Non Fungible Tokens (DRAFT) proposes an extension to ERC-721 which also tightens the requirements on metadata. Because it is wholly an extension of ERC-721, ERC-1523 is automatically supported by ERC-2477 (since this standard already supports ERC-721).</p> <p>ERC-1046 (DRAFT) ERC-20 Metadata Extension proposes a comparate extension for ERC-20. Such a concept is outside the scope of this ERC-2477 standard. Should ERC-1046 (DRAFT) be finalized, we will welcome a new ERC which copies ERC-2477 and removes the <code>tokenId</code> parameter.</p> <p>Similarly, ERC-918 (DRAFT) Mineable Token Standard proposes an extension for ERC-20 and also includes metadata. The same comment applies here as ERC-1046.</p> <h2 id="test-cases">Test Cases</h2> <p>Following is a token metadata document which is simultaneously compatible with ERC-721, ERC-1155 and ERC-2477 standards.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$schema</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://URL_TO_SCHEMA_DOCUMENT</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset Name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Lorem ipsum...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">image</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">https://s3.amazonaws.com/your-bucket/images/{id}.png</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This above example shows how JSON-LD is employed to reference the schema document (<code>$schema</code>).</p> <p>Following is a corresponding schema document which is accessible using the URI <code>"https://URL_TO_SCHEMA_DOCUMENT"</code> above.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Identifies the asset to which this NFT represents</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Describes the asset to which this NFT represents</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">image</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">A URI pointing to a resource with mime type image/* representing the asset to which this NFT represents. Consider making any images at a width between 320 and 1080 pixels and aspect ratio between 1.91:1 and 4:5 inclusive.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Assume that the metadata and schema above apply to a token with identifier 1234. (In ERC-721 this would be a specific token, in ERC-1155 this would be a token type.) Then these two function calls MAY have the following output:</p> <ul> <li><code>function tokenURIIntegrity(1234)</code> <ul> <li><code>bytes digest </code>: <code>3fc58b72faff20684f1925fd379907e22e96b660</code></li> <li><code>string hashAlgorithm</code>: <code>sha256</code></li> </ul> </li> <li><code>function tokenURISchemaIntegrity(1234)</code> <ul> <li><code>bytes digest </code>: <code>ddb61583d82e87502d5ee94e3f2237f864eeff72</code></li> <li><code>string hashAlgorithm</code>: <code>sha256</code></li> </ul> </li> </ul> <p>To avoid doubt: the previous paragraph specifies "MAY" have that output because other hash functions are also acceptable.</p> <h2 id="implementation">Implementation</h2> <p>0xcert Framework supports ERC-2477.</p> <h2 id="reference">Reference</h2> <p>Normative standard references</p> <ol> <li>RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. https://www.ietf.org/rfc/rfc2119.txt</li> <li>ERC-165 Standard Interface Detection. ./00165.md</li> <li>ERC-721 Non-Fungible Token Standard. ./00721.md</li> <li>ERC-1155 Multi Token Standard. ./01155.md</li> <li>JSON-LD. https://www.w3.org/TR/json-ld/</li> <li>Secure Hash Standard (SHS). https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf</li> </ol> <p>Other standards</p> <ol> <li>ERC-1046 ERC-20 Metadata Extension (DRAFT). ./01046.md</li> <li>ERC-918 Mineable Token Standard (DRAFT). ./00918.md</li> <li>ERC-1523 Standard for Insurance Policies as ERC-721 Non Fungible Tokens (DRAFT). ./01523.md</li> <li>W3C Subresource Integrity (SRI). https://www.w3.org/TR/SRI/</li> <li>The "data" URL scheme. https://tools.ietf.org/html/rfc2397</li> <li>Uniform Resource Identifier (URI): Generic Syntax. https://tools.ietf.org/html/rfc3986</li> <li>CID [Specification] (DRAFT). https://github.com/multiformats/cid</li> </ol> <p>Discussion</p> <ol> <li>JSON-LD discussion of referential integrity. https://lists.w3.org/Archives/Public/public-json-ld-wg/2020Feb/0003.html</li> <li>JSON Schema use of <code>$schema</code> key for documents. https://github.com/json-schema-org/json-schema-spec/issues/647#issuecomment-417362877</li> </ol> <p>Other</p> <ol> <li>[0xcert Framework supports ERC-2477]. https://github.com/0xcert/framework/pull/717</li> <li>[Shattered] The first collision for full SHA-1. https://shattered.io/static/shattered.pdf</li> <li>[320 byte file] The second SHA Collision. https://privacylog.blogspot.com/2019/12/the-second-sha-collision.html</li> <li>[Chosen prefix] https://sha-mbles.github.io</li> <li>Transitions: Recommendation for Transitioning the Use of Cryptographic Algorithms and Key Lengths. (Rev. 1. Superseded.) https://csrc.nist.gov/publications/detail/sp/800-131a/rev-1/archive/2015-11-06</li> <li>Commercial National Security Algorithm (CNSA) Suite Factsheet. https://apps.nsa.gov/iaarchive/library/ia-guidance/ia-solutions-for-classified/algorithm-guidance/commercial-national-security-algorithm-suite-factsheet.cfm</li> <li>ETSI Assigned ASN.1 Object Identifiers. https://portal.etsi.org/pnns/oidlist</li> <li>Computer Security Objects Register. https://csrc.nist.gov/projects/computer-security-objects-register/algorithm-registration</li> <li>The Sandbox implementation. https://github.com/pixowl/sandbox-smart-contracts/blob/7022ce38f81363b8b75a64e6457f6923d91960d6/src/Asset/ERC1155ERC721.sol</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-12-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/2488/ <h2 id="abstract">Abstract</h2> <p>Deprecate <code>CALLCODE</code> in a <em>somewhat</em> backwards compatible way, by making it always return failure.</p> <h2 id="motivation">Motivation</h2> <p><code>CALLCODE</code> was part of the Frontier release of Ethereum. In the first few weeks/months it became clear that it cannot accomplish its intended design goal. This was rectified with introducing <code>DELEGATECALL</code> (<a href="https://wg-eips.ritovision.com/7/">EIP-7</a>) in the Homestead update (early 2016).</p> <p><code>CALLCODE</code> became never utilized, but it still puts a burden on EVM implementations.</p> <p>Disabling it will not improve the situation for any client whose goal is to sync from genesis, but would help light clients or clients planning to sync from a later point in time.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= FORK_BLOCK</code>, the <code>CALLCODE</code> (<code>0xf2</code>) instruction always returns <code>0</code>, which signals failure.</p> <h2 id="rationale">Rationale</h2> <p>It would be possible just to remove the opcode and exceptionally abort if it is encountered. However, by returning failure, the contract has a chance to act on it and potentially recover.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This is a breaking change and has a potential to break contracts. The author expects no contracts of any value should be affected.</p> <p>TODO: validate this claim.</p> <h2 id="security-considerations">Security Considerations</h2> <p>TBA</p> <h2 id="test-cases">Test Cases</h2> <p>TBA</p> <h2 id="implementation">Implementation</h2> <p>TBA</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-11-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jim McDonaldJim@mcdee.net https://wg-eips.ritovision.com/2386/ <h2 id="simple-summary">Simple Summary</h2> <p>A JSON format for the storage and retrieval of Ethereum 2 hierarchical deterministic (HD) wallet definitions.</p> <h2 id="abstract">Abstract</h2> <p>Ethereum has the concept of keystores: pieces of data that define a key (see <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2335">EIP-2335</a> for details). This adds the concept of walletstores: stores that define wallets and how keys in said wallets are created.</p> <h2 id="motivation">Motivation</h2> <p>Hierarchical deterministic wallets create keys from a <em>seed</em> and a <em>path</em>. The seed needs to be accessible to create new keys, however it should also be protected to the same extent as private keys to stop it from becoming an easy attack vector. The path, or at least the variable part of it, needs to be stored to ensure that keys are not duplicated. Providing a standard method to do this can promote interoperability between wallets and similar software.</p> <p>Given that a wallet has an amount of data and metadata that is useful when accessing existing keys and creating new keys, standardizing this information and how it is stored allows it to be portable between different wallet providers with minimal effort.</p> <h2 id="specification">Specification</h2> <p>The elements of a hierarchical deterministic walletstore are as follows:</p> <h3 id="uuid">UUID</h3> <p>The <code>uuid</code> provided in the walletstore is a randomly-generated type 4 UUID as specified by <a rel="external" href="https://tools.ietf.org/html/rfc4122">RFC 4122</a>. It is intended to be used as a 128-bit proxy for referring to a particular wallet, used to uniquely identify wallets.</p> <p>This element MUST be present. It MUST be a string following the syntactic structure as laid out in <a rel="external" href="https://tools.ietf.org/html/rfc4122#section-3">section 3 of RFC 4122</a>.</p> <h3 id="name">Name</h3> <p>The <code>name</code> provided in the walletstore is a UTF-8 string. It is intended to serve as the user-friendly accessor. The only restriction on the name is that it MUST NOT start with the underscore (<code>_</code>) character.</p> <p>This element MUST be present. It MUST be a string.</p> <h3 id="version">Version</h3> <p>The <code>version</code> provided is the version of the walletstore.</p> <p>This element MUST be present. It MUST be the integer <code>1</code>.</p> <h3 id="type">Type</h3> <p>The <code>type</code> provided is the type of wallet. This informs mechanisms such as key generation.</p> <p>This element MUST be present. It MUST be the string <code>hierarchical deterministic</code>.</p> <h3 id="crypto">Crypto</h3> <p>The <code>crypto</code> provided is the secure storage of a secret for wallets that require this information. For hierarchical deterministic wallets this is the seed from which they calculate individual private keys.</p> <p>This element MUST be present. It MUST be an object that follows the definition described in <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2335">EIP-2335</a>.</p> <h3 id="next-account">Next Account</h3> <p>The <code>nextaccount</code> provided is the index to be supplied to the path <code>m/12381/60/&lt;index&gt;/0</code> when creating a new private key from the seed. The path follows <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2334">EIP-2334</a>.</p> <p>This element MUST be present if the wallet type requires it. It MUST be a non-negative integer.</p> <h3 id="json-schema">JSON schema</h3> <p>The walletstore follows a similar format to that of the keystore described in <a rel="external" href="https://eips.ethereum.org/EIPS/eip-2335">EIP-2335</a>.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/definitions/Walletstore</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">definitions</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Walletstore</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">crypto</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">kdf</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/definitions/Module</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">checksum</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/definitions/Module</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">cipher</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">$ref</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">#/definitions/Module</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nextaccount</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">integer</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">uuid</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">format</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uuid</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">version</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">integer</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">type</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uuid</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">version</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">crypto</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nextaccount</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Walletstore</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">Module</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">function</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">function</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">message</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">params</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>A standard for walletstores, similar to that for keystores, provides a higher level of compatibility between wallets and allows for simpler wallet and key interchange between them.</p> <h2 id="test-cases">Test Cases</h2> <h3 id="test-vector">Test Vector</h3> <p>Password <code>'testpassword'</code> Seed <code>0x147addc7ec981eb2715a22603813271cce540e0b7f577126011eb06249d9227c</code></p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">crypto</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">checksum</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">function</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">sha256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">8bdadea203eeaf8f23c96137af176ded4b098773410634727bd81c4e8f7f1021</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> {</span><span>}</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">cipher</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">function</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">aes-128-ctr</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">7f8211b88dfb8694bac7de3fa32f5f84d0a30f15563358133cda3b287e0f3f4a</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">iv</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">9476702ab99beff3e8012eff49ffb60d</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">kdf</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">function</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">pbkdf2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">c</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 16</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">dklen</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 32</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">prf</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">hmac-sha256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">salt</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">dd35b0c08ebb672fe18832120a55cb8098f428306bf5820f5486b514f61eb712</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Test wallet 2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nextaccount</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">hierarchical deterministic</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">uuid</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">b74559b8-ed56-4841-b25c-dba1b7c9d9d5</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">version</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>A Go implementation of the hierarchical deterministic wallet can be found at <a rel="external" href="https://github.com/wealdtech/go-eth2-wallet-hd">https://github.com/wealdtech/go-eth2-wallet-hd</a>.</p> <h2 id="security-considerations">Security Considerations</h2> <p>The seed stored in the <code>crypto</code> section of the wallet can be used to generate any key along the derived path. As such, the security of all keys generated by HD wallets is reduced to the security of the passphrase and strength of the encryption used to protect the seed, regardless of the security of the passphrase and strength of the encryption used to protect individual keystores.</p> <p>It is possible to work with only the walletstore plus an index for each key, in which case stronger passphrases can be used as decryption only needs to take place once. It is also possible to use generated keystores without the walletstore, in which case a breach of security will expose only the keystore.</p> <p>An example high-security configuration may involve the walletstore existing on an offline computer, from which keystores are generated. The keystores can then be moved individually to an online computer to be used for signing.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-11-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 James Choncholashttps://github.com/james-choncholas https://wg-eips.ritovision.com/2390/ <h2 id="simple-summary">Simple Summary</h2> <p>GeoENS brings geographic split horizon capabilities to ENS. It's GeoDNS for ENS!</p> <h2 id="abstract">Abstract</h2> <p>This EIP specifies an ENS resolver interface for geographically split horizon DNS. Geographic split horizon DNS returns resource records that are specific to an end user's location. This technique is commonly used by CDNs to direct traffic to content caches nearest users. Geographic split horizon resolution is primarily geared towards ENS resolvers storing DNS resource records <a href="https://wg-eips.ritovision.com/1185/">EIP-1185</a>, although the technique could be used on other interfaces like IPFS content hash storage <a href="https://wg-eips.ritovision.com/1062/">EIP-1062</a>.</p> <h2 id="motivation">Motivation</h2> <p>There are many use cases for traditional GeoDNS systems, like Amazon's Route53, in the centralized web. These use cases include proximity-based load balancing and serving content specific to the geographic location of the query. Unfortunately the ENS specification does not provide a mechanism for geo-specific resolution. ENS can respond to queries with IP addresses (as described in <a href="https://wg-eips.ritovision.com/1185/">EIP-1185</a>) however there is no way to respond to geo-specific queries. This EIP proposes a standard to give the ENS system geo-proximal awareness to serve a similar purpose as GeoDNS.</p> <p>GeoENS can do more than DNS-based solutions. In addition to geographic split horizon DNS, GeoENS can be used for the following:</p> <ul> <li>Locating digital resources (like smart contracts) that represent physical objects in the real world.</li> <li>Smart contract managing access to a physical object associated with a specific location.</li> <li>ENS + IPFS web hosting (as described in <a href="https://wg-eips.ritovision.com/1062/">EIP-1062</a>) with content translated to the native language of the query source.</li> <li>Tokenizing objects with a physical location.</li> </ul> <p>Because of the decentralized nature of ENS, geo-specific resolution is different than traditional GeoDNS. GeoDNS works as follows. DNS queries are identified by their source IP address. This IP is looked up in a database like <a rel="external" href="https://www.maxmind.com/en/geoip2-services-and-databases">GeoIP2</a> from MaxMind which maps the IP address to a location. This method of locating the source of a query is error prone and unreliable. If the GeoIP database is out of date, queried locations can be vastly different than their true location. GeoENS does not rely on a database because the user includes a location in their query.</p> <p>It follows that queries can be made by users for any location, not just their location. Traditional DNS will only return the resource assigned to a query's provenance. GeoENS does not correlate a query's provinance with a location, allowing the entire globe to be queried from a single location.</p> <p>An additional shortcoming of traditional DNS is the fact that there is no way to return a list of servers in a certain proximity. This is paramount for uses cases that require discovering the resource with the lowest latency. GeoENS allows a list of resources, like IP addresses, to be gathered within a specific location. Then a client to determine themselves which resource has the lowest latency.</p> <p>Lastly, publicly facing GeoDNS services do not give fine granularity control over geographic regions for GeoDNS queries. Cloud based DNS services like <a rel="external" href="https://aws.amazon.com/route53/">Amazon's Route 53</a> only allow specifying geographic regions at the granularity of a State in the United States. GeoENS on the other hand gives 8 characters of geohash resolution which corresponds to +-20 meter accuracy.</p> <h2 id="specification">Specification</h2> <p>This EIP proposes a new interface to ENS resolvers such that geo-spacial information can be recorded and retrieved from the blockchain. The interface changes are described below for "address resolvers" described in EIP137 however the idea applies to any record described in EIP1185 and EIP1062, namely DNS Resolvers, Text Resolvers, ABI Resolvers, etc.</p> <h3 id="what-is-a-geohash">What is a geohash?</h3> <p>A <a rel="external" href="https://en.m.wikipedia.org/wiki/Geohash#Algorithm_and_example">Geohash</a> is an interleaving of latitude and longitude bits, whose length determines it's precision. Geohashes are typically encoded in base 32 characters.</p> <h3 id="function-setgeoaddr-bytes32-node-string-calldata-geohash-address-addr-external-authorised-node">function setGeoAddr(bytes32 node, string calldata geohash, address addr) external authorised(node)</h3> <p>Sets a resource (contract address, IP, ABI, TEXT, etc.) by node and geohash. Geohashes must be unique per address and are exactly 8 characters long. This leads to an accuracy of +-20 meters. Write default initialized resource value, <code>address(0)</code>, to remove a resource from the resolver.</p> <h3 id="function-geoaddr-bytes32-node-string-calldata-geohash-external-view-returns-address-memory-ret">function geoAddr(bytes32 node, string calldata geohash) external view returns (address[] memory ret)</h3> <p>Query the resolver contract for a specific node and location. All resources (contract addresses, IP addresses, ABIs, TEXT records, etc.) matching the node and prefix geohash provided are returned. This permits querying by exact geohash of 8 characters to return the content at that location, or querying by geographic bounding box described by a geohash of less than 8 character precision.</p> <p>Any type of geohash can be used including <a rel="external" href="https://en.wikipedia.org/wiki/Z-order_curve">Z-order</a> <a rel="external" href="https://en.wikipedia.org/wiki/Hilbert_curve">Hilbert</a> or the more accurate <a rel="external" href="https://s2geometry.io/devguide/s2cell_hierarchy.html">S2 Geometry</a> library from Google. There are also ways to search the geographic data using geohashes without always ending up with a rectangular query region. <a rel="external" href="https://github.com/ashwin711/proximityhash">Searching circular shaped regions</a> is slightly more complex as it requires multiple queries.</p> <h2 id="rationale">Rationale</h2> <p>The proposed implementation uses a sparse <a rel="external" href="https://dl.acm.org/doi/10.1007/BF00288933">Quadtree</a> trie as an index for resource records as it has low storage overhead and good search performance. The leaf nodes of the tree store resource records while non-leaves represent one geohash character. Each node in the tree at depth d corresponds to a geohash of precision d. The tree has depth 8 because the maximum precision of a geohash is 8 characters. The tree has fanout 32 because the radix of a geohash character is 32. The path to get to a leaf node always has depth 8 and the leaf contains the content (like IP address) of the geohash represented by the path to the leaf. The tree is sparse as 71% of the Earth's surface is covered by water. The tree facilitates common traversal algorithms (DFS, BFS) to return lists of resource records within a geographic bounding box.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP does not introduce issues with backwards compatibility.</p> <h2 id="test-cases">Test Cases</h2> <p>See https://github.com/james-choncholas/resolvers/blob/master/test/TestPublicResolver.js</p> <h2 id="implementation">Implementation</h2> <p>This address resolver, written in Solidity, implements the specifications outlined above. The same idea presented here can be applied to other resolver interfaces as specified in EIP137. Note that geohashes are passed and stored using 64 bit unsigned integers. Using integers instead of strings for geohashes is more performant, especially in the <code>geomap</code> mapping. For comparison purposes, see https://github.com/james-choncholas/geoens/tree/master/contracts/StringOwnedGeoENSResolver.sol for the inefficient string implementation.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../ResolverBase.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> GeoENSResolver</span><span class="z-storage"> is</span><span class="z-entity z-name"> ResolverBase</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> constant</span><span> ERC2390 </span><span class="z-keyword">=</span><span class="z-constant"> 0x8fbcc5ce</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> constant</span><span> MAX_ADDR_RETURNS </span><span class="z-keyword">=</span><span class="z-constant"> 64</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> constant</span><span> TREE_VISITATION_QUEUESZ </span><span class="z-keyword">=</span><span class="z-constant"> 64</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> constant</span><span> ASCII_0 </span><span class="z-keyword">=</span><span class="z-constant"> 48</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> constant</span><span> ASCII_9 </span><span class="z-keyword">=</span><span class="z-constant"> 57</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> constant</span><span> ASCII_a </span><span class="z-keyword">=</span><span class="z-constant"> 97</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> constant</span><span> ASCII_b </span><span class="z-keyword">=</span><span class="z-constant"> 98</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> constant</span><span> ASCII_i </span><span class="z-keyword">=</span><span class="z-constant"> 105</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> constant</span><span> ASCII_l </span><span class="z-keyword">=</span><span class="z-constant"> 108</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> constant</span><span> ASCII_o </span><span class="z-keyword">=</span><span class="z-constant"> 111</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-storage z-type"> constant</span><span> ASCII_z </span><span class="z-keyword">=</span><span class="z-constant"> 122</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Node</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> data</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0 if not leaf</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> parent</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span>]</span><span> children</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> always length 32</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> A geohash is 8, base-32 characters.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> A geomap is stored as tree of fan-out 32 (because</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> geohash is base 32) and height 8 (because geohash</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> length is 8 characters)</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword">=&gt;</span><span>Node</span><span>[</span><span>]</span><span>)</span><span class="z-storage z-type"> private</span><span> geomap</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> GeoENSRecordChanged</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> node</span><span>, </span><span class="z-support">bytes8</span><span class="z-variable"> geohash</span><span>, </span><span class="z-support">address</span><span class="z-variable"> addr</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> only 5 bits of ret value are used</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> chartobase32</span><span>(</span><span class="z-variable">byte</span><span class="z-variable"> c</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint8</span><span class="z-variable"> b</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> ascii </span><span class="z-keyword">=</span><span class="z-support"> uint8</span><span>(</span><span>c</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span> (</span><span>ascii </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> ASCII_0 </span><span class="z-keyword">&amp;&amp;</span><span> ascii </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> ASCII_9</span><span>)</span><span class="z-keyword"> ||</span></span> <span class="giallo-l"><span> (</span><span>ascii </span><span class="z-keyword">&gt;</span><span> ASCII_a </span><span class="z-keyword">&amp;&amp;</span><span> ascii </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> ASCII_z</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>ascii </span><span class="z-keyword">!=</span><span> ASCII_a</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>ascii </span><span class="z-keyword">!=</span><span> ASCII_i</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>ascii </span><span class="z-keyword">!=</span><span> ASCII_l</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>ascii </span><span class="z-keyword">!=</span><span> ASCII_o</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>ascii </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> (</span><span>ASCII_0 </span><span class="z-keyword">+</span><span class="z-constant"> 9</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> b </span><span class="z-keyword">=</span><span> ascii </span><span class="z-keyword">-</span><span> ASCII_0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> base32 b = 10</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> ascii &#39;b&#39; = 0x60</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-keyword"> note</span><span class="z-comment"> base32 skips the letter &#39;a&#39;</span></span> <span class="giallo-l"><span> b </span><span class="z-keyword">=</span><span> ascii </span><span class="z-keyword">-</span><span> ASCII_b </span><span class="z-keyword">+</span><span class="z-constant"> 10</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> base32 also skips the following letters</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>ascii </span><span class="z-keyword">&gt;</span><span> ASCII_i</span><span>)</span></span> <span class="giallo-l"><span> b </span><span class="z-keyword">-</span><span class="z-keyword">-</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>ascii </span><span class="z-keyword">&gt;</span><span> ASCII_l</span><span>)</span></span> <span class="giallo-l"><span> b </span><span class="z-keyword">-</span><span class="z-keyword">-</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>ascii </span><span class="z-keyword">&gt;</span><span> ASCII_o</span><span>)</span></span> <span class="giallo-l"><span> b </span><span class="z-keyword">-</span><span class="z-keyword">-</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>b </span><span class="z-keyword">&lt;</span><span class="z-constant"> 32</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> base 32 can&#39;t be larger than 32</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> b</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> geoAddr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes8</span><span class="z-variable"> geohash</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> precision</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> ret</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>node</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> single node georesolver ignores node</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>precision </span><span class="z-keyword">&lt;</span><span class="z-keyword">=</span><span> geohash</span><span>.</span><span>length</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> ret </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> address</span><span>[](</span><span class="z-variable">MAX_ADDR_RETURNS</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>geomap</span><span>[</span><span>node</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> ret</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> ret_i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> walk into the geomap data structure</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> pointer </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> not actual pointer but index into geomap</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span>(</span><span class="z-support">uint8</span><span> i</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> precision</span><span>;</span><span> i</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>)</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> c </span><span class="z-keyword">=</span><span class="z-entity z-name"> chartobase32</span><span>(</span><span>geohash</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> next </span><span class="z-keyword">=</span><span> geomap</span><span>[</span><span>node</span><span>]</span><span>[</span><span>pointer</span><span>]</span><span>.</span><span>children</span><span>[</span><span>c</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>next </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> nothing found for this geohash.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> return early.</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ret</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span> pointer </span><span class="z-keyword">=</span><span> next</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> pointer is now node representing the resolution of the query geohash.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> DFS until all addresses found or ret[] is full.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Do not use recursion because blockchain...</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span> indexes_to_visit </span><span class="z-keyword">=</span><span class="z-keyword"> new</span><span class="z-support"> uint</span><span>[](</span><span class="z-variable">TREE_VISITATION_QUEUESZ</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> indexes_to_visit</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> =</span><span> pointer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> front_i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> back_i </span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> while</span><span>(</span><span>front_i </span><span class="z-keyword">!=</span><span> back_i</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> Node </span><span class="z-storage z-type">memory</span><span> cur_node </span><span class="z-keyword">=</span><span> geomap</span><span>[</span><span>node</span><span>]</span><span>[</span><span>indexes_to_visit</span><span>[</span><span>front_i</span><span>]</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> front_i </span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> if not a leaf node...</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>cur_node</span><span>.</span><span>data </span><span class="z-keyword">==</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> visit all the chilins</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span>(</span><span class="z-support">uint</span><span> i</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span> i</span><span class="z-keyword">&lt;</span><span>cur_node</span><span>.</span><span>children</span><span>.</span><span>length</span><span>;</span><span> i</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> only visit valid children</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>cur_node</span><span>.</span><span>children</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> !=</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> assert</span><span>(</span><span>back_i </span><span class="z-keyword">&lt;</span><span> TREE_VISITATION_QUEUESZ</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> indexes_to_visit</span><span>[</span><span>back_i</span><span>]</span><span class="z-keyword"> =</span><span> cur_node</span><span>.</span><span>children</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> back_i </span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span> ret</span><span>[</span><span>ret_i</span><span>]</span><span class="z-keyword"> =</span><span> cur_node</span><span>.</span><span>data</span><span>;</span></span> <span class="giallo-l"><span> ret_i </span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>ret_i </span><span class="z-keyword">&gt;</span><span> MAX_ADDR_RETURNS</span><span>)</span><span class="z-keyword"> break</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ret</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> when setting, geohash must be precise to 8 digits.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setGeoAddr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes8</span><span class="z-variable"> geohash</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> addr</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> authorised</span><span>(</span><span class="z-entity z-name">node</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>(</span><span>node</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> single node georesolver ignores node</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> create root node if not yet created</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>geomap</span><span>[</span><span>node</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> geomap</span><span>[</span><span>node</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-entity z-name"> Node</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> data</span><span class="z-keyword">:</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> parent</span><span class="z-keyword">:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> children</span><span class="z-keyword">:</span><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[](</span><span class="z-constant">32</span><span>)</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> walk into the geomap data structure</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> pointer </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> not actual pointer but index into geomap</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span>(</span><span class="z-support">uint</span><span> i</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> geohash</span><span>.</span><span>length</span><span>;</span><span> i</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>)</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> c </span><span class="z-keyword">=</span><span class="z-entity z-name"> chartobase32</span><span>(</span><span>geohash</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>geomap</span><span>[</span><span>node</span><span>]</span><span>[</span><span>pointer</span><span>]</span><span>.</span><span>children</span><span>[</span><span>c</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> nothing found for this geohash.</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> we need to create a path to the leaf</span></span> <span class="giallo-l"><span> geomap</span><span>[</span><span>node</span><span>]</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-entity z-name"> Node</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> data</span><span class="z-keyword">:</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span></span> <span class="giallo-l"><span> parent</span><span class="z-keyword">:</span><span> pointer</span><span>,</span></span> <span class="giallo-l"><span> children</span><span class="z-keyword">:</span><span class="z-keyword"> new</span><span class="z-support"> uint256</span><span>[](</span><span class="z-constant">32</span><span>)</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> geomap</span><span>[</span><span>node</span><span>]</span><span>[</span><span>pointer</span><span>]</span><span>.</span><span>children</span><span>[</span><span>c</span><span>]</span><span class="z-keyword"> =</span><span> geomap</span><span>[</span><span>node</span><span>]</span><span>.</span><span>length </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> pointer </span><span class="z-keyword">=</span><span> geomap</span><span>[</span><span>node</span><span>]</span><span>[</span><span>pointer</span><span>]</span><span>.</span><span>children</span><span>[</span><span>c</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Node </span><span class="z-storage z-type">storage</span><span> cur_node </span><span class="z-keyword">=</span><span> geomap</span><span>[</span><span>node</span><span>]</span><span>[</span><span>pointer</span><span>]</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> storage = get reference</span></span> <span class="giallo-l"><span> cur_node</span><span>.</span><span>data </span><span class="z-keyword">=</span><span> addr</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> GeoENSRecordChanged</span><span>(</span><span>node</span><span>,</span><span> geohash</span><span>,</span><span> addr</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> interfaceID </span><span class="z-keyword">==</span><span> ERC2390 </span><span class="z-keyword">||</span><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>interfaceID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This contract has similar functionality to ENS Resolvers - refer there for security considerations. Additionally, this contract has a dimension of data privacy. Users query via the geoAddr function specifying a geohash of less than 8 characters which defines the query region. Users who run light clients leak the query region to their connected full-nodes. Users who rely on nodes run by third parties (like Infura) will also leak the query region. Users who run their own full node or have access to a trusted full node do not leak any location data.</p> <p>Given the way most location services work, the query region is likely to contain the user's actual location. The difference between API access, light, and full nodes has always had an impact on privacy but now the impact is underscored by the involvement of coarse granularity user location.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-11-13T00:00:00+00:00 2026-02-11T14:49:27+00:00 James Hancockhttps://github.com/MadeofTin https://wg-eips.ritovision.com/2378/ <h2 id="simple-summary">Simple Summary</h2> <p>As part of an EIP centric forking model, this EIP tracks the first step in the approval process for any EIP to be included in a fork or upgrade. Specifically, the stage where the Core Developers vet the concept of an EIP and give a "green light" sufficient for EIP authors to move forward in development.</p> <h2 id="abstract">Abstract</h2> <p>The pipeline for Core EIPs, per the EIP-Centric upgrade model, is as follows.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>[ DRAFT ] -&gt; [ ELLIGLE FOR INCLUSION ] -&gt; [ IMPLEMENTATION ] -&gt; [ TESTING ] -&gt; [ ACCEPTED ] -&gt; [ DEPLOYED ]</span></span></code></pre> <p>This EIP documents all EIPs marked as <strong>Eligible For Inclusion</strong> by the All Core Devs. Typically to reach this stage, an EIP must be discussed in brief on an AllCoreDevs Call and motioned by rough consenses to be moved to this stage. Any additions to this list are required to provide a link to the meeting notes when this discussion and decision took place.</p> <p>The requirements for <strong>Eligible for Inclusion</strong> is that the AllCoreDevs, representing the major clients and ecosystem stakeholders etc:</p> <ul> <li>Are positive towards the EIP,</li> <li>Would accept (well written) PRs to include the EIP into the codebase. <ul> <li>So that it could be toggled on for testing…</li> <li>…but not with an actual block number for activation</li> </ul> </li> </ul> <h2 id="motivation">Motivation</h2> <p>Development of clear specifications and pull requests to existing Ethereum Clients is a large investment of time and resources. The state of <em>Eligible for Inclusion</em> is a signal from the Ethereum Core Developers to an EIP Author validiating the idea behind an EIP and confirms investing their time further pursing it is worthwhile.</p> <h2 id="specification">Specification</h2> <table><thead><tr><th>EIP</th><th>Title</th><th>Pipeline Status</th><th>Date of Initial Decision</th><th>REF</th></tr></thead><tbody> <tr><td>EIP-663</td><td>Unlimited SWAP and DUP instructions</td><td>ELIGIBLE</td><td>2019-11-01</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2074.md">🔗</a></td></tr> <tr><td>EIP-1057</td><td>ProgPoW, a Programmatic Proof-of-Work</td><td>ELIGIBLE</td><td>2019-11-01</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2074.md">🔗</a></td></tr> <tr><td>EIP-1380</td><td>Reduced gas cost for call to self</td><td>ELIGIBLE</td><td>2019-11-01</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2074.md">🔗</a></td></tr> <tr><td>EIP-1559</td><td>Fee market change for ETH 1.0 chain</td><td>ELIGIBLE</td><td>2019-11-01</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2074.md">🔗</a></td></tr> <tr><td>EIP-1702</td><td>Generalized Account Versioning Scheme</td><td>ELIGIBLE</td><td>2019-11-01</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2074.md">🔗</a></td></tr> <tr><td>EIP-1962</td><td>EC arithmetic and pairings with runtime definitions</td><td>ELIGIBLE</td><td>2019-11-01</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2074.md">🔗</a></td></tr> <tr><td>EIP-1985</td><td>Sane limits for certain EVM parameters</td><td>ELIGIBLE</td><td>2019-11-01</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2074.md">🔗</a></td></tr> <tr><td>EIP-2046</td><td>Reduced gas cost for static calls made to precompiles</td><td>ELIGIBLE</td><td>2019-11-01</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/AllCoreDevs-EL-Meetings/Meeting%2074.md">🔗</a></td></tr> <tr><td>EIP-2315</td><td>Simple Subroutines for the EVM</td><td>ELIGIBLE</td><td>2020-02-21</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/All%20Core%20Devs%20Meetings/Meeting%2081.md#decisions">🔗</a></td></tr> <tr><td>EIP-2537</td><td>Precompile for BLS12-381 curve operations</td><td>ELIGIBLE</td><td>2020-03-06</td><td><a rel="external" href="https://github.com/ethereum/pm/blob/master/All%20Core%20Devs%20Meetings/Meeting%2082.md">🔗</a></td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p><strong>EIP Number</strong></p> <p><strong>Title</strong></p> <p><strong>Pipeline Status</strong> : Show the current status in the context of the EIP centric model. The list is sorted by furthest along in the process.</p> <p><strong>Date of Initial Decision</strong> : Date of the initial decision for Eligibility for Inclusion</p> <p><strong>REF</strong> : Link to the decision on the AllCoreDevs Notes</p> <h2 id="references">References</h2> <ul> <li>EIP Centric Forking Model Proposal by @holiman - https://notes.ethereum.org/@holiman/S1ELAYY7S?type=view</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-11-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Ricardo Guilherme Schmidthttps://github.com/3esmit Eric Dvorsakhttps://github.com/yenda https://wg-eips.ritovision.com/2400/

URI format for submitted transactions with complete information for transaction decoding

<h2 id="abstract">Abstract</h2> <p>A transaction hash is not very meaningful on its own, because it looks just like any other hash, and it might lack important information for reading a transaction.</p> <p>This standard includes all needed information for displaying a transaction and its details, such as <code>chainId</code>, <code>method</code> signature called, and <code>events</code> signatures emitted.</p> <h2 id="motivation">Motivation</h2> <p>Interoperability between ethereum clients, allowing different systems to agree on a standard way of representing submitted transactions hashes, optionally with necessary information for decoding transaction details.</p> <h3 id="use-cases">Use-cases</h3> <p>Transaction Receipt URIs embedded in QR-codes, hyperlinks in web-pages, emails or chat messages provide for robust cross-application signaling between very loosely coupled applications. A standardized URI format allows for instant invocation of the user’s preferred transaction explorer application. Such as:</p> <ul> <li>In web3 (dapps, mining pools, exchanges), links would automatically open user's preferred transaction explorer;</li> <li>In wallets, for users sharing transaction receipts easier;</li> <li>In chat applications, as a reply to an <a href="https://wg-eips.ritovision.com/681/">EIP-681</a> transaction request;</li> <li>In crypto vending machines, a QRCode can be displayed when transactions are submitted;</li> <li>Anywhere transaction receipts are presented to users.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="syntax">Syntax</h3> <p>Transaction receipt URLs contain "ethereum" in their schema (protocol) part and are constructed as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>receipt = schema_part transaction_hash [ &quot;@&quot; chain_id ] [ &quot;?&quot; parameters ]</span></span> <span class="giallo-l"><span>schema_part = &quot;ethereum:tx-&quot; </span></span> <span class="giallo-l"><span>transaction_hash = &quot;0x&quot; 64*HEXDIG </span></span> <span class="giallo-l"><span>chain_id = 1*DIGIT</span></span> <span class="giallo-l"><span>parameters = parameter *( &quot;&amp;&quot; parameter )</span></span> <span class="giallo-l"><span>parameter = key &quot;=&quot; value</span></span> <span class="giallo-l"><span>key = &quot;method&quot; / &quot;events&quot;</span></span> <span class="giallo-l"><span>value = function_signature / event_list</span></span> <span class="giallo-l"><span>function_signature = function_name &quot;(&quot; TYPE *( &quot;,&quot; TYPE) &quot;)&quot;</span></span> <span class="giallo-l"><span>function_name = STRING</span></span> <span class="giallo-l"><span>event_list = event_signature *( &quot;;&quot; event_signature )</span></span> <span class="giallo-l"><span>event_signature = event_name &quot;(&quot; event_type *( &quot;,&quot; event_type) &quot;)&quot;</span></span> <span class="giallo-l"><span>event_name = STRING</span></span> <span class="giallo-l"><span>event_type = [&quot;!&quot;] TYPE</span></span></code></pre> <p>Where <code>TYPE</code> is a standard ABI type name, as defined in Ethereum Contract ABI specification. <code>STRING</code> is a URL-encoded unicode string of arbitrary length.</p> <p>The exclamation symbol (<code>!</code>), in <code>event_type</code>, is used to identify indexed event parameters.</p> <h3 id="semantics">Semantics</h3> <p><code>transaction_hash</code> is mandatory. The hash must be looked up in the corresponding <code>chain_id</code> transaction history, if not found it should be looked into the pending transaction queue and rechecked until is found. If not found anequivalent error as "transaction not found error" should be shown instead of the transaction. When the transaction is pending, it should keep checking until the transaction is included in a block and becomes "unrevertable" (usually 12 blocks after transaction is included).</p> <p><code>chain_id</code> is specified by <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> optional and contains the decimal chain ID, such that transactions on various test and private networks can be represented as well. If no <code>chain_id</code> is present, the $ETH/mainnet (<code>1</code>) is considered.</p> <p>If <code>method</code> is not present, this means that the transaction receipt URI does not specify details, or that it was a transaction with no calldata. When present it needs to be validated by comparing the first 4 bytes of transaction calldata with the first 4 bytes of the keccak256 hash of <code>method</code>, if invalid, an equivalent error as "method validation error" must be shown instead of the transaction.</p> <p>If <code>events</code> is not present, this means that the transaction receipt URI does not specify details, or that the transaction did not raised any events. Pending and failed transactions don't validate events, however, when transaction is successful (or changes from pending to success) and events are present in URI, each event in the <code>event_list</code> must occur at least once in the transaction receipt event logs, otherwise an equivalent error as "event validation error: {event(s) [$event_signature, ...] not found}" should be shown instead of the transaction. A URI might contain the event signature for all, some or none of the raised events.</p> <h4 id="examples">Examples</h4> <h5 id="simple-eth-transfer">Simple ETH transfer:</h5> <p><code>ethereum:tx-0x1143b5e38fe3cf585fb026fb9b5ce35c85a691786397dc8a23a07a62796d8172@1</code></p> <h5 id="standard-token-transfer">Standard Token transfer:</h5> <p><code>ethereum:tx-0x5375e805b0c6afa20daab8d37352bf09a533efb03129ba56dee869e2ce4f2f92@1?method="transfer(address,uint256)"&amp;events="Transfer(!address,!address,uint256)"</code></p> <h5 id="complex-contract-transaction">Complex contract transaction:</h5> <p><code>ethereum:tx-0x4465e7cce3c784f264301bfe26fc17609855305213ec74c716c7561154b76fec@1?method="issueAndActivateBounty(address,uint256,string,uint256,address,bool,address,uint256)"&amp;events="Transfer(!address,!address,uint256);BountyIssued(uint256);ContributionAdded(uint256,!address,uint256);BountyActivated(uint256,address)"</code></p> <h2 id="rationale">Rationale</h2> <p>The goal of this standard envolves only the transport of submitted transactions, and therefore transaction data must be loaded from blockchain or pending transaction queue, which also serves as a validation of the transaction existence.</p> <p>Transaction hash not found is normal in fresh transactions, but can also mean that effectively a transaction was never submitted or have been replaced (through "higher gasPrice" nonce override or through an uncle/fork).</p> <p>In order to decode transaction parameters and events, a part of the ABI is required. The transaction signer have to know the ABI to sign a transaction, and is also who is creating a transaction receipt, so the transaction receipt can optionally be shared with the information needed to decode the transaction call data and it's events.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Future upgrades that are partially or fully incompatible with this proposal must use a prefix other than <code>tx-</code> that is separated by a dash (-) character from whatever follows it.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-10-29T00:00:00+00:00 2026-02-11T14:49:28+00:00 Dominic Letzhttps://github.com/dominicletz Santiago Palladinohttps://github.com/spalladino https://wg-eips.ritovision.com/2330/

A new EVM opcode to read external contract storage data.

<h2 id="abstract">Abstract</h2> <p>This proposal adds a new opcode <code>EXTSLOAD</code> at <code>0x5c</code> which pops two items from the stack: <code>&lt;account address&gt; &lt;storage key&gt;</code> and pushes one item: <code>&lt;storage value&gt;</code>. The gas cost is sum of account access cost and storage read based on <a href="https://wg-eips.ritovision.com/2929/">EIP-2929</a> Access Lists.</p> <h2 id="motivation">Motivation</h2> <p>While any off-chain application can read all contract storage data of all contracts, this is not possible for deployed smart contracts themselves. These are bound to use contract calls for any interaction including reading data from other contracts. This EIP adds an EVM opcode to directly read external contract storage.</p> <p>The gas cost when reading from registry style contract such as <a href="https://wg-eips.ritovision.com/20/">EIP-20s</a>, ENS and other data contracts is very high, because they incur cross contract call cost, cost for ABI encoding, decoding and dispatching and finally loading the data. In many cases the underlying storage that is being queried is though just a simple mapping. On top of that, the view function may SLOAD many other slots which caller may not be interested in, which further adds to the gas costs. In these cases a new <code>EXTSLOAD</code> call directly accessing the mapping in storage could not only <strong>reduce the gas cost</strong> of the interaction more than 10x, but also it would make the gas cost <strong>predictable</strong> for the reading contract.</p> <h2 id="specification">Specification</h2> <p>A new EVM instruction <code>EXTSLOAD (0x5c)</code> that works like <code>SLOAD (0x54)</code> but an additional parameter representing the contract that is to be read from.</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">EXTSLOAD</span><span> (0x5c</span><span>)</span></span></code></pre> <p>The <code>EXTSLOAD</code> instruction pops 2 values from the stack, first <code>contract</code> a contract address and then second <code>slot</code> a storage address within <code>contract</code>. As result <code>EXTSLOAD</code> pushes on the stack the value from the contract storage of <code>contract</code> at the storage <code>slot</code> address or <code>0</code> in case the account <code>contract</code> does not exist.</p> <h3 id="gas-cost-pre-verkle">Gas cost pre-verkle</h3> <p>Gas to be charged before Verkle Tree change is specified as <code>ACCOUNT_ACCESS_COST + STORAGE_READ_COST</code> where:</p> <ul> <li><code>ACCOUNT_ACCESS_COST</code> is <code>0</code> if the account address is already in <code>accessed_addresses</code> set, otherwise <code>COLD_ACCOUNT_ACCESS_COST</code>.</li> <li><code>STORAGE_READ_COST</code> is <code>WARM_STORAGE_READ_COST</code> if storage key is already in <code>accessed_storage_keys</code> set, otherwise <code>COLD_STORAGE_READ_COST</code>.</li> </ul> <h3 id="gas-cost-post-verkle">Gas cost post-verkle</h3> <p>It is important to consider that post Verkle tree change, <code>ACCOUNT_ACCESS_COST</code> will not be needed since a single account's storage would be spread across the entire global trie. Hence gas to be charged post Verkle Tree change is just <code>STORAGE_READ_COST</code>, which is as specified in <a href="https://wg-eips.ritovision.com/2330/#gas-cost-pre-verkle">Gas cost pre-verkle</a>.</p> <h2 id="rationale">Rationale</h2> <ul> <li>Without this EIP, a contract can still opt-in to make their entire state public, by having a method that simply SLOADs and returns the values (<a href="https://wg-eips.ritovision.com/2330/./assets/Extsload.sol">example</a>). The complexity of the gas cost can be seen as <code>1</code>x CALL cost + <code>N</code>x SLOAD cost. Hence, the gas cost specified for using EXTSLOAD opcode on an account for <code>N</code> times, the charge of <code>1</code>x <code>COLD_ACCOUNT_ACCESS_COST</code> and <code>N</code>x <code>STORAGE_READ_COST</code> is hereby justified.</li> <li>Without this EIP, a contract can still use internal state of other contracts. An external party can supply a value and proof to a contract, which the contract can verify using <code>BLOCKHASH</code>. This is only possible for the previous blocks and not the latest state (since current blockhash cannot be determined before execution).</li> <li>This opcode can be seen as breaking object-oriented (OO) model because it allows to read storage of other contracts. In usual systems using OO is net positive, because there is no limit on machine code and it hardly adds any cost to add more methods or use single method to get a ton of data while the caller needs to just a small portion of data. However on EVM, there are visible costs, i.e. about $0.2 per SLOAD (20 gwei and ETHUSD 2000). Also, OO has caused misleading assumptions for developers where variables marked as "private" in smart contracts are encrypted in some way/impossible to read which has resulted bad designs. Hence, this EIP can be beneficial in terms of making smart contract systems more efficient as well as preventing misconceptions as well.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is fully backwards compatible since it adds a new instruction.</p> <h2 id="security-considerations">Security Considerations</h2> <ul> <li>Since the opcode is similar to SLOAD, it should be easy to implement in various clients.</li> <li>This opcode allows the callee <code>A</code> to re-enter a caller contract <code>B</code> and read state of <code>B</code> and <code>B</code> cannot stop <code>A</code> from doing that. Since this does not change any state, it should not be a security issue. Contracts generally use re-entrancy guards, but that is only added to write methods. So even currently without EXTSLOAD, <code>A</code> can re-enter <code>B</code> and read their state exposed by any view methods and it has not been an issue.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-10-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Martin Lundfallhttps://github.com/MrChico https://wg-eips.ritovision.com/2327/ <h2 id="simple-summary">Simple Summary</h2> <p>Introduces a new opcode <code>BEGINDATA</code>, which indicates that the remaining bytes of the contract should be regarded as data rather than contract code and cannot be executed.</p> <h2 id="abstract">Abstract</h2> <p>It is common for smart contracts to efficiently store data directly in the contract bytecode. Examples include constructor arguments, constant variables, compiler metadata and the contract runtime during the init phase. Currently, such data is not distinguished from normal bytecode and is still being analysed for <code>JUMPDEST</code>s by EVM interpreters. This EIP introduces a new opcode <code>BEGINDATA</code> at byte <code>0xb6</code>, which marks the remainding bytecode as data, indicating to EVM interpreters, static analysis tools and chain explorers that the remaining bytes do not represent opcodes.</p> <h2 id="motivation">Motivation</h2> <p>The <code>BEGINDATA</code> opcode has been suggested before as part of the EIP <code>Subroutines and Static Jumps for the EVM</code> <a href="https://wg-eips.ritovision.com/615/">EIP-615</a> as a way to determine the position of jumptables in contract bytecode. It is here introduced in its own right in order to exclude data from the <code>JUMPDEST</code> analysis of contracts, making it impossible to jump to data. This makes it easier for static analysis tools to analyse contracts, allows disassemblers, chain explorers and debuggers to not display data as a mess of INVALID opcodes and may even provide a marginal improvement in performance. It also helps scalability because it improves on-chain evaluation of transactions from other chains in that the validation that the code conforms to a certain pattern does not need to do a full jumpdest analysis to see that data is not executed and thus does not have to conform to the pattern (used by the optimism project). Additionally, it paves the way for suggestions such as <a rel="external" href="https://github.com/ethereum/EIPs/pull/1712">EIP-1712</a> to disallow unused opcodes, jumptables <a href="https://wg-eips.ritovision.com/615/">EIP-615</a> and speculative proposals to disallow for deployment of contracts with stack usage violations.</p> <h2 id="specification">Specification</h2> <p>While computing the valid <code>JUMPDEST</code>s of a contract, halt analysis once the first <code>BEGINDATA</code> is encountered. In other words: A jump to any codelocation equal to or greater than the location of the first <code>BEGINDATA</code> causes a <code>BAD_JUMP_DESTINATION</code> error. If <code>BEGINDATA</code> is encountered during contract execution, it has the same semantics as <code>STOP</code>. It uses 0 gas.</p> <p>Bytes past <code>BEGINDATA</code> remain accessible via <code>CODECOPY</code> and <code>EXTCODECOPY</code>. <code>BEGINDATA</code> does not influence <code>CODESIZE</code> or <code>EXTCODESIZE</code>.</p> <h2 id="rationale">Rationale</h2> <p>The byte <code>0xb6</code> was chosen to align with <a href="https://wg-eips.ritovision.com/615/">EIP-615</a>. The choice to <code>STOP</code> if <code>BEGINDATA</code> is encountered is somewhat arbitrary. An alternative would be to be to abort the execution with an out-of-gas error.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The proposal will not change any existing contracts unless their current behaviour relies upon the usage of unused opcodes.</p> <p>Since contracts have been using data from the very start, in a sense all of them use unused opcodes, but they would have to use data in a way that it is skipped during execution and jumped over. The Solidity compiler never generated such code. It has to be evaluated whether contracts created by other means could have such a code structure.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases should include:</p> <ol> <li>A contract which jumps to a destination <code>X</code>, where <code>X</code> has a pc value higher than the <code>BEGINDATA</code> opcode, and the byte at <code>X</code> is <code>0x5b</code>. This should fail with a <code>BAD_JUMP_DESTINATION</code> error.</li> <li>A contract which encounters the <code>BEGINDATA</code> opcode (should stop executing the current call frame)</li> </ol> <h2 id="implementation">Implementation</h2> <p>Not yet.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-09-19T00:00:00+00:00 2026-02-11T14:49:27+00:00 Zainan Victor Zhouhttps://github.com/xinbenlv Alex Beregszaszihttps://github.com/axic Bryant Eisenbachhttps://github.com/fubuloubu https://wg-eips.ritovision.com/2294/

Adds a maximum value to the Chain ID parameter to avoid potential encoding issues that may occur when using large values of the parameter.

<h2 id="abstract">Abstract</h2> <p>This EIP informationally defines the "Safe Range" and "Max Range" of ChainId based on a few known restrictions such as <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> and major wallet and JSON-RPC representation of ChainId.</p> <h2 id="motivation">Motivation</h2> <ol> <li>We want chainId to be safe across the different components of the ecosystem such as smart contract, wallet, dApp and JSON-RPC etc.</li> <li>We want to enable Cross-Chain function call</li> <li>We want to ensure <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> domains have a clear definition of how to pack ChainID.</li> <li>Enable possible expansion of chains, such as increasing amount of L2s, L3s, or shards of Ethereum mainnets.</li> <li>Enable hashed based temporary chain: There have been suggestions of using a hash-based identifier in place on Chain ID to allow the value to adapt over time to different contentious forks and other scenarios. This proposal does not describe this behavior, but ~63 bits of entropy should be enough to ensure that no collisions are likely for reasonable (e.g. non-malicious) uses of this feature for that purpose.</li> </ol> <h2 id="specification">Specification</h2> <p>We declared the following chainID range</p> <ol> <li>(1, 2^31 - 1): "Safe Range", the higher bound is decided by Javascript number</li> <li>(1, MAX_CHAIN_ID); "Max Range", in which <code>MAX_CHAIN_ID := floor(MAX_UINT64 / 2) - 36 = 9,223,372,036,854,775,771</code>:</li> </ol> <h2 id="rationale">Rationale</h2> <h3 id="beyond-max-range-the-eip-155-will-overflow-as-discussed-below">Beyond "Max Range", the EIP-155 will overflow as discussed below</h3> <p>The <code>MAX_CHAIN_ID</code> is calculated to avoid overflow when performing uint64 math. For reference, a value of 0 or less is also disallowed.</p> <p>Due to how the calculation for chain ID is performed, the maximum value seen during the arithmetic is <code>CHAIN_ID * 2 + 36</code>, so clients must test to ensure no overflow conditions are encountered when the highest value is used. No underflow is possible.</p> <p>EIP-155 introduces the Chain ID parameter, which is an important parameter used for domain separation (replay protection) of Ethereum protocol signed messages. However, it does not specify any properties about the size that this parameter takes. Allowing it to be 256-bit wide means that the RLP encoding of a transaction must use &gt;256-bit arithmetic to calculate the v field.</p> <p>and suggests a reasonable maximum enforced size in order to ensure that there are no issues when encoding this parameter. This would allow a sufficient amount of different values for this parameter, which is typically chosen by community consensus as a genesis parameter for a given chain and thus does not change often.</p> <p>Without a well-chosen value of Chain ID, there could be differences in the implementation of <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> (and <a href="https://wg-eips.ritovision.com/1344/">EIP-1344</a> by derivative) in both client codebase and external tooling that could lead to consensus-critical vulnerabilities being introduced to the network. By making this limit explicit, we avoid this scenario for Ethereum and any project which uses the Ethereum codebase.</p> <p>Also, the field <code>chainID</code> has experienced increasing usage and dependencies, due more and more contracts are depending on <a href="https://wg-eips.ritovision.com/1344/">EIP-1344</a> to expose CHAIN ID in the smart contract execution. For example when used with <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>, <a href="https://wg-eips.ritovision.com/1271/">ERC-1271</a> for on-contract signature verification, chainId has been increasingly introduced for replay attack prevention. It's security critical to ensure clients depending on the chainId computation in cryptography yields identical result for verification in all cases.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces a change that affects previous implementations of this feature. However, as of time of writing(2022-10-18) no known chain makes use of a value outside of the suggested bounds, there should not be an issue in adopting this limit on the size of this parameter, therefore the impact should be non-existent.</p> <p>If any other chain is operating with an incompatible <code>chainId</code>, we advised they make proper arrangement when this EIP becomes adopted.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Needs discussion.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-09-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonnick@ens.domains https://wg-eips.ritovision.com/2304/ <h2 id="abstract">Abstract</h2> <p>This EIP introduces new overloads for the <code>addr</code> field for ENS resolvers, which permit resolution of addresses for other blockchains via ENS.</p> <h2 id="motivation">Motivation</h2> <p>With the increasing uptake of ENS by multi-coin wallets, wallet authors have requested the ability to resolve addresses for non-Ethereum chains inside ENS. This specification standardises a way to enter and retrieve these addresses in a cross-client fashion.</p> <h2 id="specification">Specification</h2> <p>A new accessor function for resolvers is specified:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> coinType</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre> <p>The EIP165 interface ID for this function is 0xf1cb7e06.</p> <p>When called on a resolver, this function must return the cryptocurrency address for the specified namehash and coin type. A zero-length string must be returned if the specified coin ID does not exist on the specified node.</p> <p><code>coinType</code> is the cryptocurrency coin type index from <a rel="external" href="https://github.com/satoshilabs/slips/blob/master/./00044.md">SLIP44</a>.</p> <p>The return value is the cryptocurency address in its native binary format. Detailed descriptions of the binary encodings for several popular chains are provided in the Address Encoding section below.</p> <p>A new event for resolvers is defined:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> AddressChanged</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> node</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> coinType</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> newAddress</span><span>)</span><span>;</span></span></code></pre> <p>Resolvers MUST emit this event on each change to the address for a name and coin type.</p> <h3 id="recommended-accessor-functions">Recommended accessor functions</h3> <p>The following function provides the recommended interface for changing the addresses stored for a node. Resolvers SHOULD implement this interface for setting addresses unless their needs dictate a different interface.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setAddr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> coinType</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> addr</span><span>)</span><span>;</span></span></code></pre> <p><code>setAddr</code> adds or replaces the address for the given node and coin type. The parameters for this function are as per those described in <code>addr()</code> above.</p> <p>This function emits an <code>AddressChanged</code> event with the new address; see also the backwards compatibility section below for resolvers that also support <code>addr(bytes32)</code>.</p> <h3 id="address-encoding">Address Encoding</h3> <p>In general, the native binary representation of the address should be used, without any checksum commonly used in the text representation.</p> <p>A table of encodings for common blockchains is provided, followed by a more detailed description of each format. In the table, 'encodings' lists the address encodings supported by that chain, along with any relevant parameters. Details of those address encodings are described in the following sections.</p> <table><thead><tr><th>Cryptocurrency</th><th>Coin Type</th><th>Encoding</th></tr></thead><tbody> <tr><td>Bitcoin</td><td>0</td><td>P2PKH(0x00), P2SH(0x05), SegWit('bc')</td></tr> <tr><td>Litecoin</td><td>2</td><td>P2PKH(0x30), P2SH(0x32), P2SH(0x05), SegWit('ltc')</td></tr> <tr><td>Dogecoin</td><td>3</td><td>P2PKH(0x1e), P2SH(0x16)</td></tr> <tr><td>Monacoin</td><td>22</td><td>P2PKH(0x32), P2SH(0x05)</td></tr> <tr><td>Ethereum</td><td>60</td><td>ChecksummedHex</td></tr> <tr><td>Ethereum Classic</td><td>61</td><td>ChecksummedHex</td></tr> <tr><td>Rootstock</td><td>137</td><td>ChecksummedHex(30)</td></tr> <tr><td>Ripple</td><td>144</td><td>Ripple</td></tr> <tr><td>Bitcoin Cash</td><td>145</td><td>P2PKH(0x00), P2SH(0x05), CashAddr</td></tr> <tr><td>Binance</td><td>714</td><td>Bech32('bnb')</td></tr> </tbody></table> <h4 id="p2pkh-version">P2PKH(version)</h4> <p>Pay to Public Key Hash addresses are <a rel="external" href="https://en.bitcoin.it/wiki/Base58Check_encoding">base58check</a> encoded. After decoding, the first byte is a version byte. For example, the Bitcoin address <code>1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa</code> base58check decodes to the 21 bytes <code>0062e907b15cbf27d5425399ebf6f0fb50ebb88f18</code>.</p> <p>P2PKH addresses have a version byte, followed by a 20 byte pubkey hash. Their canonical encoding is their scriptPubkey encoding (specified <a rel="external" href="https://en.bitcoin.it/wiki/Transaction#Types_of_Transaction">here</a>) is <code>OP_DUP OP_HASH160 &lt;pubKeyHash&gt; OP_EQUALVERIFY OP_CHECKSIG</code>.</p> <p>The above example address is thus encoded as the 25 bytes <code>76a91462e907b15cbf27d5425399ebf6f0fb50ebb88f1888ac</code>.</p> <h5 id="p2sh-version">P2SH(version)</h5> <p>P2SH addresses are base58check encoded in the same manner as P2PKH addresses. P2SH addresses have a version, followed by a 20 byte script hash. Their scriptPubkey encoding (specified <a rel="external" href="https://en.bitcoin.it/wiki/Transaction#Pay-to-Script-Hash">here</a>) is <code>OP_HASH160 &lt;scriptHash&gt; OP_EQUAL</code>. A Bitcoin address of <code>3Ai1JZ8pdJb2ksieUV8FsxSNVJCpoPi8W6</code> decodes to the 21 bytes <code>0562e907b15cbf27d5425399ebf6f0fb50ebb88f18</code> and is encoded as the 23 bytes <code>a91462e907b15cbf27d5425399ebf6f0fb50ebb88f1887</code>.</p> <h5 id="segwit-hrp">SegWit(hrp)</h5> <p>SegWit addresses are encoded with <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki">bech32</a>. Bech32 addresses consist of a human-readable part - 'bc' for Bitcoin mainnet - and a machine readable part. For SegWit addresses, this decodes to a 'witness version', between 0 and 15, and a 'witness program', as defined in <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki">BIP141</a>.</p> <p>The scriptPubkey encoding for a bech32 address, as defined in BIP141, is <code>OP_n</code>, where <code>n</code> is the witness version, followed by a push of the witness program. Note this warning from BIP173:</p> <blockquote> <p>Implementations should take special care when converting the address to a scriptPubkey, where witness version n is stored as OP_n. OP_0 is encoded as 0x00, but OP_1 through OP_16 are encoded as 0x51 though 0x60 (81 to 96 in decimal). If a bech32 address is converted to an incorrect scriptPubKey the result will likely be either unspendable or insecure.</p> </blockquote> <p>For example, the Bitcoin SegWit address <code>BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4</code> decodes to a version of <code>0</code> and a witness script of <code>751e76e8199196d454941c45d1b3a323f1433bd6</code>, and then encodes to a scriptPubkey of <code>0014751e76e8199196d454941c45d1b3a323f1433bd6</code>.</p> <h4 id="checksummedhex-chainid">ChecksummedHex(chainId?)</h4> <p>To translate a text format checksummed hex address into binary format, simply remove the '0x' prefix and hex decode it. <code>0x314159265dD8dbb310642f98f50C066173C1259b</code> is hex-decoded and stored as the 20 bytes <code>314159265dd8dbb310642f98f50c066173c1259b</code>.</p> <p>A checksum format is specified by <a href="https://wg-eips.ritovision.com/55/">EIP-55</a>, and extended by <a rel="external" href="https://github.com/rsksmart/RSKIPs/blob/master/IPs/RSKIP60.md">RSKIP60</a>, which specifies a means of including the chain ID in the checksum. The checksum on a text format address must be checked. Addresses with invalid checksums that are not all uppercase or all lowercase MUST be rejected with an error. Implementations may choose whether to accept non-checksummed addresses, but the authors recommend at least providing a warning to users in this situation.</p> <p>When encoding an address from binary to text, an EIP55/RSKIP60 checksum MUST be used - so the correct encoding of the above address for Ethereum is <code>0x314159265dD8dbb310642f98f50C066173C1259b</code>.</p> <h4 id="ripple">Ripple</h4> <p>Ripple addresses are encoded using a version of base58check with an alternative alphabet, described <a rel="external" href="https://xrpl.org/base58-encodings.html">here</a>. Two types of ripple addresses are supported, 'r-addresses', and 'X-addresss'. r-addresses consist of a version byte followed by a 20 byte hash, while X-addresses consist of a version byte, a 20 byte hash, and a tag, specified <a rel="external" href="https://github.com/xrp-community/standards-drafts/issues/6">here</a>.</p> <p>Both address types should be stored in ENS by performing ripple's version of base58check decoding and storing them directly (including version byte). For example, the ripple address <code>rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn</code> decodes to and is stored as <code>004b4e9c06f24296074f7bc48f92a97916c6dc5ea9</code>, while the address <code>X7qvLs7gSnNoKvZzNWUT2e8st17QPY64PPe7zriLNuJszeg</code> decodes to and is stored as <code>05444b4e9c06f24296074f7bc48f92a97916c6dc5ea9000000000000000000</code>.</p> <h4 id="cashaddr">CashAddr</h4> <p>Bitcoin Cash defines a new address format called 'CashAddr', specified <a rel="external" href="https://github.com/bitcoincashorg/bitcoincash.org/blob/master/spec/cashaddr.md">here</a>. This uses a variant of bech32 encoding to encode and decode (non-segwit) Bitcoin Cash addresses, using a prefix of 'bitcoincash:'. A CashAddr should be decoded using this bech32 variant, then converted and stored based on its type (P2PKH or P2SH) as described in the relevant sections above.</p> <h4 id="bech32">Bech32</h4> <p><a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0173.mediawiki">Bech32</a> addresses consist of a human-readable part - for example, 'bnb' for Binance - and a machine readable part. The encoded data is simply the address, which can be converted to binary and stored directly.</p> <p>For example, the BNB address <code>bnb1grpf0955h0ykzq3ar5nmum7y6gdfl6lxfn46h2</code> decodes to the binary representation <code>40c2979694bbc961023d1d27be6fc4d21a9febe6</code>, which is stored directly in ENS.</p> <h3 id="example">Example</h3> <p>An example implementation of a resolver that supports this EIP is provided here:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.8</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> AddrResolver</span><span class="z-storage"> is</span><span class="z-entity z-name"> ResolverBase</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> private</span><span> ADDR_INTERFACE_ID </span><span class="z-keyword">=</span><span class="z-constant"> 0x3b3b57de</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> private</span><span> ADDRESS_INTERFACE_ID </span><span class="z-keyword">=</span><span class="z-constant"> 0xf1cb7e06</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> private</span><span> COIN_TYPE_ETH </span><span class="z-keyword">=</span><span class="z-constant"> 60</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AddrChanged</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> node</span><span>, </span><span class="z-support">address</span><span class="z-variable"> a</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AddressChanged</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> node</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> coinType</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> newAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword">=&gt;</span><span class="z-storage z-type">mapping</span><span>(</span><span class="z-support">uint</span><span class="z-keyword">=&gt;</span><span class="z-support">bytes</span><span>)</span><span>)</span><span> _addresses</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Sets the address associated with an ENS node.</span></span> <span class="giallo-l"><span class="z-comment"> * May only be called by the owner of that node in the ENS registry.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> node</span><span class="z-comment"> The node to update.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> a</span><span class="z-comment"> The address to set.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setAddr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> a</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> authorised</span><span>(</span><span class="z-entity z-name">node</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> setAddr</span><span>(</span><span>node</span><span>,</span><span> COIN_TYPE_ETH</span><span>,</span><span class="z-entity z-name"> addressToBytes</span><span>(</span><span>a</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * Returns the address associated with an ENS node.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> node</span><span class="z-comment"> The ENS node to query.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> The</span><span class="z-comment"> associated address.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span> a </span><span class="z-keyword">=</span><span class="z-entity z-name"> addr</span><span>(</span><span>node</span><span>,</span><span> COIN_TYPE_ETH</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>a</span><span>.</span><span>length </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> bytesToAddress</span><span>(</span><span>a</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setAddr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> coinType</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> a</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> authorised</span><span>(</span><span class="z-entity z-name">node</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> AddressChanged</span><span>(</span><span>node</span><span>,</span><span> coinType</span><span>,</span><span> a</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>coinType </span><span class="z-keyword">==</span><span> COIN_TYPE_ETH</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> AddrChanged</span><span>(</span><span>node</span><span>,</span><span class="z-entity z-name"> bytesToAddress</span><span>(</span><span>a</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> _addresses</span><span>[</span><span>node</span><span>]</span><span>[</span><span>coinType</span><span>]</span><span class="z-keyword"> =</span><span> a</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addr</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> coinType</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _addresses</span><span>[</span><span>node</span><span>]</span><span>[</span><span>coinType</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> interfaceID </span><span class="z-keyword">==</span><span> ADDR_INTERFACE_ID </span><span class="z-keyword">||</span><span> interfaceID </span><span class="z-keyword">==</span><span> ADDRESS_INTERFACE_ID </span><span class="z-keyword">||</span><span class="z-variable z-language"> super</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span>interfaceID</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="implementation">Implementation</h3> <p>An implementation of this interface is provided in the <a rel="external" href="https://github.com/ensdomains/resolvers/">ensdomains/resolvers</a> repository.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>If the resolver supports the <code>addr(bytes32)</code> interface defined in EIP137, the resolver MUST treat this as a special case of this new specification in the following ways:</p> <ol> <li>The value returned by <code>addr(node)</code> from EIP137 should always match the value returned by <code>addr(node, 60)</code> (60 is the coin type ID for Ethereum).</li> <li>Anything that causes the <code>AddrChanged</code> event from EIP137 to be emitted must also emit an <code>AddressChanged</code> event from this EIP, with the <code>coinType</code> specified as 60, and vice-versa.</li> </ol> <h2 id="tests">Tests</h2> <p>The table below specifies test vectors for valid address encodings for each cryptocurrency described above.</p> <table><thead><tr><th>Cryptocurrency</th><th>Coin Type</th><th>Text</th><th>Onchain (hex)</th></tr></thead><tbody> <tr><td>Bitcoin</td><td>0</td><td><code>1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa</code></td><td><code>76a91462e907b15cbf27d5425399ebf6f0fb50ebb88f1888ac</code></td></tr> <tr><td></td><td></td><td><code>3Ai1JZ8pdJb2ksieUV8FsxSNVJCpoPi8W6</code></td><td><code>a91462e907b15cbf27d5425399ebf6f0fb50ebb88f1887</code></td></tr> <tr><td></td><td></td><td><code>BC1QW508D6QEJXTDG4Y5R3ZARVARY0C5XW7KV8F3T4</code></td><td><code>0014751e76e8199196d454941c45d1b3a323f1433bd6</code></td></tr> <tr><td>Litecoin</td><td>2</td><td><code>LaMT348PWRnrqeeWArpwQPbuanpXDZGEUz</code></td><td><code>76a914a5f4d12ce3685781b227c1f39548ddef429e978388ac</code></td></tr> <tr><td></td><td></td><td><code>MQMcJhpWHYVeQArcZR3sBgyPZxxRtnH441</code></td><td><code>a914b48297bff5dadecc5f36145cec6a5f20d57c8f9b87</code></td></tr> <tr><td></td><td></td><td><code>ltc1qdp7p2rpx4a2f80h7a4crvppczgg4egmv5c78w8</code></td><td><code>0014687c150c26af5493befeed7036043812115ca36c</code></td></tr> <tr><td>Dogecoin</td><td>3</td><td><code>DBXu2kgc3xtvCUWFcxFE3r9hEYgmuaaCyD</code></td><td><code>76a9144620b70031f0e9437e374a2100934fba4911046088ac</code></td></tr> <tr><td></td><td></td><td><code>AF8ekvSf6eiSBRspJjnfzK6d1EM6pnPq3G</code></td><td><code>a914f8f5d99a9fc21aa676e74d15e7b8134557615bda87</code></td></tr> <tr><td>Monacoin</td><td>22</td><td><code>MHxgS2XMXjeJ4if2PRRbWYcdwZPWfdwaDT</code></td><td><code>76a9146e5bb7226a337fe8307b4192ae5c3fab9fa9edf588ac</code></td></tr> <tr><td>Ethereum</td><td>60</td><td><code>0x314159265dD8dbb310642f98f50C066173C1259b</code></td><td><code>314159265dd8dbb310642f98f50c066173c1259b</code></td></tr> <tr><td>Ethereum Classic</td><td>61</td><td><code>0x314159265dD8dbb310642f98f50C066173C1259b</code></td><td><code>314159265dd8dbb310642f98f50c066173c1259b</code></td></tr> <tr><td>Rootstock</td><td>137</td><td><code>0x5aaEB6053f3e94c9b9a09f33669435E7ef1bEAeD</code></td><td><code>5aaeb6053f3e94c9b9a09f33669435e7ef1beaed</code></td></tr> <tr><td>Ripple</td><td>144</td><td><code>rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn</code></td><td><code>004b4e9c06f24296074f7bc48f92a97916c6dc5ea9</code></td></tr> <tr><td></td><td></td><td><code>X7qvLs7gSnNoKvZzNWUT2e8st17QPY64PPe7zriLNuJszeg</code></td><td><code>05444b4e9c06f24296074f7bc48f92a97916c6dc5ea9000000000000000000</code></td></tr> <tr><td>Bitcoin Cash</td><td>145</td><td><code>1BpEi6DfDAUFd7GtittLSdBeYJvcoaVggu</code></td><td><code>76a91476a04053bda0a88bda5177b86a15c3b29f55987388ac</code></td></tr> <tr><td></td><td></td><td><code>bitcoincash:qpm2qsznhks23z7629mms6s4cwef74vcwvy22gdx6a</code></td><td><code>76a91476a04053bda0a88bda5177b86a15c3b29f55987388ac</code></td></tr> <tr><td></td><td></td><td><code>3CWFddi6m4ndiGyKqzYvsFYagqDLPVMTzC</code></td><td><code>a91476a04053bda0a88bda5177b86a15c3b29f55987387</code></td></tr> <tr><td></td><td></td><td><code>bitcoincash:ppm2qsznhks23z7629mms6s4cwef74vcwvn0h829pq</code></td><td><code>a91476a04053bda0a88bda5177b86a15c3b29f55987387</code></td></tr> <tr><td>Binance</td><td>714</td><td><code>bnb1grpf0955h0ykzq3ar5nmum7y6gdfl6lxfn46h2</code></td><td><code>40c2979694bbc961023d1d27be6fc4d21a9febe6</code></td></tr> </tbody></table> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-08-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Loredana Cirsteahttps://github.com/loredanacirstea https://wg-eips.ritovision.com/2256/ <h2 id="simple-summary">Simple Summary</h2> <p>This is a proposal for a new JSON-RPC call for retrieving from a wallet a selection of owned assets by an Ethereum address, with the user's permission.</p> <h2 id="abstract">Abstract</h2> <p>There is no standardized way for a dApp to request a list of owned assets from a user. Now, each dApp needs to keep a list of all the popular or existing assets and check the user's balance against the blockchain, for each of these assets. This leads to duplicated effort across dApps. It also leads to the user being presented with asset options that the user does not care about, from various, unwanted airdrops.</p> <h2 id="motivation">Motivation</h2> <p>There are financial dApps that require a list of owned assets from a user, for various purposes - calculating taxes, selecting customized payment options, etc. Each of these dApps are now forced to keep a list of popular assets (smart contract addresses, ABIs) and retrieve the user's data from the blockchain, for each asset. This leads to effort duplication and nonoptimal UX where the user is presented with either more or less asset options than the user would like - various airdrops, incomplete list of assets kept by the dApp.</p> <p>This list of owned assets can be retrieved from the wallet used by the user. The wallet can allow the user to manage only the assets that the user is interested in. Therefore, a new JSON-RPC method is proposed: <code>wallet_getOwnedAssets</code>. This method is complementary to <a href="https://wg-eips.ritovision.com/747/">EIP-747</a>, which proposes a way for sites to suggest users new assets to watch on their wallet.</p> <h2 id="specification">Specification</h2> <p>New JSON-RPC method to be added to web3 browsers: <code>wallet_getOwnedAssets</code>. This method is for dApp-wallet communication and only targets the assets that have already been whitelisted by the wallet, for the user account.</p> <p><strong>Arguments:</strong></p> <ul> <li>type <code>address</code>, Ethereum address that owns the assets</li> <li>options object, optional: <ul> <li><code>chainId</code> - type <code>uint</code>, chain id respecting <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>; optional</li> <li><code>limit</code> - type <code>uint</code>, the maximum number of owned assets expected by the dApp to be returned; optional</li> <li><code>types</code> - type <code>string[]</code>, array of asset interface identifiers such as <code>['ERC20', 'ERC721']</code>; optional</li> <li><code>justification</code> - type <code>string</code>, human-readable text provided by the dApp, explaining the intended purpose of this request; optional but recommended</li> </ul> </li> </ul> <p><strong>Result:</strong></p> <ul> <li>array with asset records: <ul> <li><code>address</code> - type <code>address</code>, Ethereum checksummed address</li> <li><code>chainId</code> - type <code>uint</code>, identifier for the chain on which the assets are deployed</li> <li><code>type</code> - type <code>string</code>, asset interface ERC identifier; e.g. <code>ERC20</code>; optional - <a href="https://wg-eips.ritovision.com/1820/">EIP-1820</a> could be used</li> <li><code>options</code> - an object with asset-specific fields; <code>ERC20</code> tokens example: <ul> <li><code>name</code> - type <code>string</code>, token name; optional if the token does not implement it</li> <li><code>symbol</code> - type <code>string</code>, token symbol; optional if the token does not implement it</li> <li><code>icon</code>- type <code>base64</code>, token icon; optional</li> <li><code>balance</code> - type <code>uint</code>, the number of tokens that the user owns, in the smallest token denomination</li> <li><code>decimals</code> - type <code>uint</code>, the number of decimals implemented by the token; optional</li> </ul> </li> </ul> </li> </ul> <h3 id="examples">Examples</h3> <p><strong>1) A request to return all of the user's owned assets:</strong></p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_getOwnedAssets</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x3333333333333333333333333333333333333333</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">justification</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The dApp needs to know about all your assets in order to calculate your taxes properly.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Result:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000001</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC20</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">options</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">TokenA</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">TKA</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">icon</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">data:image/gif;base64,R0lGODlhAQABAIABAP///wAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">balance</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1000000000000</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">decimals</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 18</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000002</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 3</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC20</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">options</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">TokenB</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">TKB</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">icon</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">data:image/gif;base64,R0lGODlhAQABAIABAP///wAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">balance</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 2000000000000</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">decimals</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 18</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000003</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 42</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC721</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">options</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">TokenC</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">TKC</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">icon</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">data:image/gif;base64,R0lGODlhAQABAIABAP///wAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">balance</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 10</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>2) A request to return one <code>ERC20</code> owned asset, deployed on <code>chainId</code> 1:</strong></p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">wallet_getOwnedAssets</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x3333333333333333333333333333333333333333</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">limit</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">types</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERC20</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">justification</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Select your token of choice, in order to pay for our services.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Result:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant">1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">address</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000001</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">chainId</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ERC20</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">options</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">TokenA</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">symbol</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">TKA</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">icon</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">data:image/gif;base64,R0lGODlhAQABAIABAP///wAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">balance</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1000000000000</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">decimals</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 18</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="ui-best-practices">UI Best Practices</h3> <p>The wallet should display a UI to the user, showing the request. The user can:</p> <ul> <li>accept the request, in which case the dApp receives all the requested assets</li> <li>reject the request</li> <li>amend the request by lowering the number of owned assets returned to the dApp</li> </ul> <p>If all owned assets are requested, the total number of owned assets will be shown to the user. The user can also choose to select the assets that will be returned to the dApp, amending the request.</p> <p>If a selection is requested, the user will select from the list of owned assets.</p> <p>As an optimization, wallets can keep a list of frequently used assets by the user, and show that list first, with the option of expanding that list with owned assets that the user uses less frequently.</p> <h2 id="rationale">Rationale</h2> <p>In order to avoid duplication of effort for dApps that require keeping a list of all or popular assets and to provide optimal UX, the <code>wallet_getOwnedAssets</code> JSON-RPC method is proposed.</p> <p>The <code>chainId</code> and <code>types</code> optional parameters enable dApps to provide options in order to restrict the selection list that the user will be presented with by the wallet, in accordance with the dApp's functionality. The <code>limit</code> parameter enables the dApp to tell the user an upper limit of accounts that the user can select. It remains to be seen if a lower bound should also be provided. At the moment, this lower bound can be considered as being <code>1</code>.</p> <p>The <code>options</code> response field provides the dApp with asset-specific options, enabling better UX through using the same visual and text identifiers that the wallet uses, making it easier for the user to understand the dApp's UI.</p> <p>The <code>address</code>, <code>type</code> response fields provide enough information about the asset, enabling dApps to provide additional asset-specific functionality.</p> <p>The <code>balance</code> response field is an optimization, allowing dApps to show the user's balance without querying the blockchain. Usually, this information is already public.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Not relevant, as this is a new method.</p> <h2 id="test-cases">Test Cases</h2> <p>To be done.</p> <h2 id="implementation">Implementation</h2> <p>To be done.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-08-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 John Adlerhttps://github.com/adlerjohn https://wg-eips.ritovision.com/2242/ <h2 id="simple-summary">Simple Summary</h2> <p>An additional, optional transaction field is added for "postdata," data that is posted on-chain but that cannot be read from the EVM.</p> <h2 id="abstract">Abstract</h2> <p>A paradigm shift in how blockchains are used has been seen recently in Eth 2.0, with the rise of <a rel="external" href="https://notes.ethereum.org/w1Pn2iMmSTqCmVUTGV4T5A?view"><em>Execution Environments</em></a> (EEs), and <a rel="external" href="https://ethresear.ch/t/the-stateless-client-concept/172"><em>stateless clients</em></a>. This shift involves blockchains serving as a secure data availability and arbitration layer, <em>i.e.</em>, they provide a globally-accepted source of available data, and process fraud/validity and data availability proofs. This same paradigm can be applied on Eth 1.x, replacing EEs with <a rel="external" href="https://ethresear.ch/t/building-scalable-decentralized-payment-systems-request-for-feedback/5312">trust-minimized side chains</a>.</p> <h2 id="motivation">Motivation</h2> <p>While <a href="https://wg-eips.ritovision.com/2028/">EIP-2028</a> provides a reduction in gas cost of calldata, and is a step in the right direction of encouraging use of history rather than state, the EVM does not actually need to see all data that is posted on-chain. Following the principle of "don't pay for what you don't use," a distinct way of posting data on-chain, but without actually being usable within the EVM, is needed.</p> <p>For <a rel="external" href="https://ethresear.ch/t/minimal-viable-merged-consensus/5617">trust-minimized side chains with fraud proofs</a>, we simply need to ensure that the side chain block proposer has attested that <em>some</em> data is available. Authentication can be performed as part of a fraud proof should that data end up invalid. Note that <a rel="external" href="https://ethresear.ch/t/on-chain-scaling-to-potentially-500-tx-sec-through-mass-tx-validation/3477">trust-minimized side chains with validity proofs</a> can't make use of the changes proposed in this EIP, as they required immediate authentication of the posted data. This will be <a rel="external" href="https://ethresear.ch/t/multi-threaded-data-availability-on-eth-1/5899">the topic of a future EIP</a>.</p> <h2 id="specification">Specification</h2> <p>We propose a consensus modification, beginning at <code>FORK_BLKNUM</code>:</p> <p>An additional optional field, <code>postdata</code>, is added to transactions. Serialized transactions now have the format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&quot;from&quot;: bytes20,</span></span> <span class="giallo-l"><span>&quot;to&quot;: bytes20,</span></span> <span class="giallo-l"><span>&quot;startGas&quot;: uint256,</span></span> <span class="giallo-l"><span>&quot;gasPrice&quot;: uint256,</span></span> <span class="giallo-l"><span>&quot;value&quot;: uint256,</span></span> <span class="giallo-l"><span>&quot;data&quot;: bytes,</span></span> <span class="giallo-l"><span>&quot;nonce&quot;: uint256,</span></span> <span class="giallo-l"><span>[&quot;postdata&quot;: bytes],</span></span></code></pre> <p>with witnesses signing over the <a rel="external" href="https://github.com/ethereum/wiki/wiki/RLP">RLP encoding</a> of the above. <code>postdata</code> is data that is posted on-chain, for later historical retrieval by layer-2 systems.</p> <p><code>postdata</code> is an RLP-encoded twople <code>(version: uint64, data: bytes)</code>.</p> <ol> <li><code>version</code> is <code>0</code>.</li> <li><code>data</code> is an RLP-encoded list of binary data. This EIP does not interpret the data in any way, simply considering it as a binary blob, though future EIPs may introduce different interpretation schemes for different values of <code>version</code>.</li> </ol> <p>The gas cost of the posted data is <code>1 gas per byte</code>. This cost is deducted from the <code>startGas</code>; if the remaining gas is non-positive the transaction immediately reverts with an out of gas exception.</p> <h2 id="rationale">Rationale</h2> <p>The changes proposed are as minimal and non-disruptive to the existing EVM and transaction format as possible while also supporting possible <a rel="external" href="https://ethresear.ch/t/multi-threaded-data-availability-on-eth-1/5899">future extensions</a> through a version code.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The new transaction format is backwards compatible, as the new <code>postdata</code> field is optionally appended to existing transactions.</p> <p>The proposed changes are not forwards-compatible, and will require a hard fork.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO</p> <h2 id="implementation">Implementation</h2> <p>TODO</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-07-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 Loredana Cirsteahttps://github.com/loredanacirstea Christian Tzurcanuhttps://github.com/ctzurcanu https://wg-eips.ritovision.com/2193/ <h2 id="simple-summary">Simple Summary</h2> <p>We are proposing Alias - a semantic standard for identifying on-chain resources by human-readable qualifiers, supporting any type of data.</p> <h2 id="abstract">Abstract</h2> <p>The dType Alias is a system for providing human-readable resource identifiers to on-chain content. A resource identifier is based on the type of data (identifier provided by dType, <a href="https://wg-eips.ritovision.com/1900/">EIP-1900</a>) and the data content (identifier provided by a dType Storage Contract, <a href="https://wg-eips.ritovision.com/2157/">EIP-2157</a>). It is a universal way of addressing content, supporting any type of data.</p> <h2 id="motivation">Motivation</h2> <p>There are standards that currently address the need for attaching human-readable identifiers to Ethereum accounts, such as <a href="https://wg-eips.ritovision.com/137/">EIP-137</a>. These standards are an attempt to bring domain names to Ethereum, following the same format as DNS: <code>subdomain.domain.tld</code>. This leaf -&gt; root format is unintuitive and contradicts the semantic meaning that <code>.</code> has in programming languages, which is a root -&gt; leaf connection (e.g. in OOP, when accessing an object's property). A more intuitive and widely used approach is a root-&gt;leaf format, used in file browsers, hierarchical menus, and even in other decentralized systems, which give unique identifiers to resources (e.g. <code>0x56.Currency.TCoin</code> in <a rel="external" href="https://medium.com/r/?url=https%3A%2F%2Fdevelopers.libra.org">Libra</a>.</p> <p>Moreover, <a href="https://wg-eips.ritovision.com/137/">EIP-137</a> is not flexible enough to address smart contract content, which can contain heterogeneous data that belongs to various accounts. For example, a <code>PaymentChannel</code> smart contract can have an domain name. However, the <code>Alice-Bob</code> channel data from inside the smart contract, cannot have a subdomain name. Having uniquely identified, granular resources opens the way to creating both human and machine-readable protocols on top of Ethereum. It also provides a basis for protocols based on functional programming.</p> <p>This ERC proposes a set of separators which maintain their semantic meaning and provides a way to address any type of resource - from Ethereum addresses, to individual <code>struct</code> instances inside smart contracts.</p> <p>Imagine the following dType types: <code>SocialNetwork</code> and <code>Profile</code>, with related storage data about user profiles. One could access such a profile using an alias for the data content: <code>alice@socialnetwork.profile</code>. For a <code>PaymentChannel</code> type, Alice can refer to her channel with Bob with <code>alice-bob.paymentchannel</code>. This alias system can be used off-chain, to replace the old DNS system with a deterministic and machine-readable way of displaying content, based on the dType type's metadata.</p> <h2 id="specification">Specification</h2> <p>The dType registry will provide domain and subdomain names for the resource type. Subdomains can be attributed recursively, to dType types which contain other complex types in their composition.</p> <p>We define an <code>Alias</code> registry contract, that keeps track of the human-readable identifiers for data resources, which exist in dType storage contracts. Anyone can set an alias in the <code>Alias</code> registry, as long as the Ethereum address that signs the alias data has ownership on the resource, in the dType storage contract. Storage contract data ownership will be detailed in <a href="https://wg-eips.ritovision.com/2157/">EIP-2157</a>. An owner can update or delete an alias at any time.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> Alias</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AliasSet</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dtypeIdentifier</span><span>, </span><span class="z-support">bytes1</span><span class="z-variable"> separator</span><span>, </span><span class="z-support">string</span><span class="z-variable"> name</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identifier</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setAlias</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> dtypeIdentifier</span><span>,</span><span class="z-support"> bytes1</span><span class="z-variable"> separator</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> identifier</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> signature</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAliased</span><span>(</span><span class="z-support">bytes1</span><span class="z-variable"> separator</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li><code>dtypeIdentifier</code>: Type identifier from the dType registry, needed to ensure uniqueness of <code>name</code> for a dType type. <code>dtypeIdentifier</code> is checked to see if it exists in the dType registry. The dType registry also links the type's data storage contract, where the existence and ownership of the <code>identifier</code> is checked.</li> <li><code>name</code>: user-defined human-readable name for the resource referenced by <code>identifier</code></li> <li><code>separator</code>: Character acting as a separator between the name and the rest of the alias. Allowed values: <ul> <li><code>.</code>: general domain separation, using root-&gt;leaf semantics. E.g. <code>domain.subdomain.leafsubdomain.resource</code></li> <li><code>@</code>: identifying actor-related data, such as user profiles, using leaf-&gt;root semantics. E.g. <code>alice@socialnetwork.profile</code> or <code>alice@dao@eth</code></li> <li><code>#</code>: identifying concepts, using root-&gt;leaf semantics. E.g. <code>topicX#postY</code></li> <li><code>/</code>: general resource path definition, using root-&gt;leaf semantics. E.g. <code>resourceRoot/resource</code></li> </ul> </li> <li><code>identifier</code>: Resource identifier from a smart contract linked with dType</li> <li><code>signature</code>: Alias owner signature on <code>dtypeIdentifier</code>, <code>identifier</code>, <code>name</code>, <code>separator</code>, <code>nonce</code>, <code>aliasAddress</code>, <code>chainId</code>. <ul> <li><code>nonce</code>: monotonically increasing counter, used to prevent replay attacks</li> <li><code>aliasAddress</code>: Ethereum address of <code>Alias</code> contract</li> <li><code>chainId</code>: chain on which the <code>Alias</code> contract is deployed, as detailed in <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>, used to prevent replay attacks when updating the <code>identifier</code> for an alias.</li> </ul> </li> </ul> <p>Content addressability can be done:</p> <ul> <li>using the <code>bytes32</code> identifiers directly, e.g. <code>0x0b5e76559822448f6243a6f76ac7864eba89c810084471bdee2a63429c92d2e7@0x9dbb9abe0c47484c5707699b3ceea23b1c2cca2ac72681256ab42ae01bd347da</code></li> <li>using the human identifiers, e.g. <code>alice@socialnetwork</code></li> </ul> <p>Both of the above examples will resolve to the same content.</p> <h2 id="rationale">Rationale</h2> <p>Current attempts to solve content addressability, such as <a href="https://wg-eips.ritovision.com/137/">EIP-137</a>, only target Ethereum accounts. These are based on inherited concepts from HTTP and DNS, which are not machine friendly.</p> <p>With <a href="https://wg-eips.ritovision.com/1900/">EIP-1900</a> and <a href="https://wg-eips.ritovision.com/2157/">EIP-2157</a>, general content addressability can be achieved. dType provides type information and a reference to the smart contract where the type instances are stored. Additionally, Alias uses the semantic meaning of subdomain separators to have a <a rel="external" href="https://github.com/loredanacirstea/articles/blob/master/articles/Flexible_Alias_or_Why_ENS_is_Obsolete.md">intuitive order rule</a>.</p> <p>Multiple aliases can be assigned to a single resource. Either by using a different <code>name</code> or by using a different <code>separator</code>. Each <code>separator</code> can have a specific standard for displaying and processing data, based on its semantic meaning.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Will be added.</p> <h2 id="test-cases">Test Cases</h2> <p>Will be added.</p> <h2 id="implementation">Implementation</h2> <p>An in-work implementation can be found at https://github.com/pipeos-one/dType/blob/master/contracts/contracts/Alias.sol. This proposal will be updated with an appropriate implementation when consensus is reached on the specifications.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-06-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Loredana Cirsteahttps://github.com/loredanacirstea Christian Tzurcanuhttps://github.com/ctzurcanu https://wg-eips.ritovision.com/2157/ <h2 id="simple-summary">Simple Summary</h2> <p>This ERC is an extension of ERC-1900, proposing an optional storage extension for dType, a decentralized type system, specifying a general ABI for all storage contracts that contain type instances.</p> <h2 id="abstract">Abstract</h2> <p>The storage extension will enable easy navigation and retrieval of type data that is intended to be of public use. This is possible through standardizing the ABI of the dType storage contracts, with the effect of having a deterministic path to a type instance record. This standardization enables a more effective on-chain and off-chain use of data and opens up possibilities for decentralized applications, enabling developers to build on top of public global data.</p> <h2 id="motivation">Motivation</h2> <p>Currently, Ethereum does not have standardization of data addressability. This might not be needed for data that is meant to be quasi-private, however, it is needed for data that is meant for public consumption. ERC-1900 has started standardizing data types for increasing interoperability between projects, but this is not enough if we want to build a global ecosystem. Deterministic data addressability will enable anyone to build upon the same public data sets, off-chain or on-chain.</p> <p>It is true that with ERC-1900, blockchain data analysis and type-specific data retrieval will be possible off-chain, but this implies relying on centralized data caches (blockchain explorers) or maintaining your own data cache. Moreover, this option does not allow on-chain standardization on data retrieval paths, therefore limiting the type of on-chain interoperable operations that can be done.</p> <p>Having a clear way of retrieving data, instead of analyzing the blockchain for contracts that have a certain type in their ABI or bytecode, will make development easier and more decentralized for applications that target global data on specific types.</p> <p>For example, a decentralized market place can be built on top of some marketplace-specific types, and by knowing exactly where the type data is stored, it is easy to create custom algorithms that provide the user with the product information they seek. Everyone has access to the data and the data path is standardized.</p> <p>Moreover, by standardizing storage contract interfaces, ABI inference is possible. The common interface, together with the dType registry will provide all the data needed to reconstruct the ABI.</p> <p>This system can be extended with access and mutability control later on, in a future proposal. Access and mutability control will be necessary for public-use global systems. Moreover, we can have a homogeneous application of permissions across system components. This is not detailed in the present proposal.</p> <p>Another use case is data bridges between Ethereum shards or between Ethereum and other chains. Data syncing between shards/chains can be done programmatically, across data types (from various projects). Imagine a user having a public profile/identity contract on one chain, wishing to move that profile on Ethereum. By supporting the origin chain types and having a standardized storage mechanism, data moving processes will be the same.</p> <p>This pattern of separating data type definitions and storage allows developers to create functional programming-like patterns on Ethereum, even though languages such as Solidity are not functional.</p> <h2 id="specification">Specification</h2> <h3 id="typerootcontract">TypeRootContract</h3> <p>ERC-1900 defines a <code>contractAddress</code> field in the type metadata. For the limited purpose of ERC-1900, this field contains the value of the Ethereum type library in which the type definition exists. For the purpose of this ERC, the <code>contractAddress</code> will contain the Etherereum address of a <code>TypeRootContract</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> TypeRootContract</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> libraryAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> storageAddress</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _library</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _storage</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> libraryAddress </span><span class="z-keyword">=</span><span> _library</span><span>;</span></span> <span class="giallo-l"><span> storageAddress </span><span class="z-keyword">=</span><span> _storage</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li><code>libraryAddress</code> - Ethereum address of the type definition library, from ERC-1900</li> <li><code>storageAddress</code> - Ethereum address of the type data storage contract</li> </ul> <h3 id="typestoragecontract">TypeStorageContract</h3> <p>This contract will use the type library to define the internal data stored in it. Each record will be a type instance, addressable by a primary identifier. The primary identifier is calculated by the type library's <code>getIdentifier</code> function, based on the type instance values.</p> <p>We propose a Solidity CRUD pattern, as described in https://medium.com/robhitchens/solidity-crud-part-1-824ffa69509a, where records can also be retrieved using their index - a monotonically increasing counter.</p> <p>An stub implementation for the TypeStorageContract would look like:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;./TypeALib.sol&#39;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> TypeAStorage</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> TypeALib</span><span class="z-keyword"> for</span><span class="z-entity z-name"> TypeALib</span><span>.</span><span>TypeA</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> public</span><span> typeIndex</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword"> =&gt;</span><span> Type</span><span>)</span><span class="z-storage z-type"> public</span><span> typeStruct</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Type</span><span> {</span></span> <span class="giallo-l"><span> TypeALib</span><span>.</span><span>TypeA data</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> index</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LogNew</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identifier</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> index</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LogUpdate</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identifier</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> index</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LogRemove</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identifier</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> index</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> insert</span><span>(</span><span class="z-storage z-type">TypeALib</span><span>.</span><span class="z-support z-variable">TypeA</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> insertBytes</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> remove</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> index</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> update</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>,</span><span class="z-storage z-type"> TypeALib</span><span>.</span><span class="z-support z-variable">TypeA</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> isStored</span><span>(</span><span class="z-entity z-name">bytes32</span><span class="z-entity z-name"> identifier</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> stored</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getByHash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-storage z-type">TypeALib</span><span>.</span><span class="z-support z-variable">TypeA</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getByIndex</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> index</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-storage z-type">TypeALib</span><span>.</span><span class="z-support z-variable">TypeA</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> count</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> counter</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>We are now thinking about a building block as a smart contract with an encapsulated object that contains state changing functions that are only understood from within. This is more akin to Object-Oriented Programming and poses interoperability and scalability issues. Not necessarily for an individual project, but for a global Ethereum OS. This is why we are proposing to separate data from business logic and data structure definitions.</p> <p>When you have public aggregated data, categorized on each type, anyone can build tools on top of it. This is a radical change from the closed or dispersed data patterns that we find in web2.</p> <p>We have chosen to define a <code>TypeRootContract</code> instead of extending the dType registry with fields for the TypeStorage contract, because this approach enables easier interface updates in the future. It is more extensible.</p> <p>The storage pattern used for dType itself and all the Type Storage contracts can be the same. This lowers the cost of building, testing and auditing the code.</p> <p>The <code>TypeStorageContract</code> pattern should ensure:</p> <ul> <li>type instance addressability by the primary identifier</li> <li>a way to retrieve all records from the contract</li> <li>counting the number of records</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal does not affect existent Ethereum standards or implementations. It uses the present experimental version of ABIEncoderV2.</p> <h2 id="test-cases">Test Cases</h2> <p>Will be added.</p> <h2 id="implementation">Implementation</h2> <p>An in-work implementation can be found at https://github.com/pipeos-one/dType/tree/master/contracts/contracts. This proposal will be updated with an appropriate implementation when consensus is reached on the specifications.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Casey Detriohttps://github.com/cdetrio Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/2045/ <h2 id="abstract">Abstract</h2> <p>According to recent benchmarks, EVM opcodes for computation (<code>ADD</code>, <code>SUB</code>, <code>MUL</code>, etc.) are generally overpriced relative to opcodes for storage I/O (<code>SLOAD</code>, <code>SSTORE</code>, etc.). Currently the minimum gas cost is 1 (i.e. one unit of gas), and most computational opcodes have a cost near to 1 (e.g. 3, 5, or 8), so the range in possible cost reduction is limited. A new minimum unit of gas, called a "particle", which is a fraction of 1 gas, would expand the range of gas costs and thus enable reductions below the current minimum.</p> <h2 id="motivation">Motivation</h2> <p>The transaction capacity of an Ethereum block is determined by the gas cost of transactions relative to the block gas limit. One way to boost the transaction capacity is to raise the block gas limit. Unfortunately, raising the block gas limit would also increase the rate of state growth, unless the costs of state-expanding storage opcodes (<code>SSTORE</code>, <code>CREATE</code>, etc.) are simultaneously increased to the same proportion. Increasing the cost of storage opcodes may have adverse side effects, such as shifting the economic assumptions around gas fees of deployed contracts, or possibly breaking invariants in current contract executions (as mentioned in <a href="https://wg-eips.ritovision.com/2035/">EIP-2035</a>^{<a href="https://wg-eips.ritovision.com/2045/#eip2035">1</a>}, more research is needed on the potential effects of increasing the cost of storage opcodes).</p> <p>Another way to boost the transaction capacity of a block is to reduce the gas cost of transactions. Reducing the gas costs of computational opcodes while keeping the cost of storage opcodes the same, is effectively equivalent to raising the block gas limit and simultaneously increasing the cost of storage opcodes. However, reducing the cost of computational opcodes might avoid the adverse side effects of an increase in cost of storage opcodes (again, more research is needed on this topic).</p> <p>Currently, computational opcode costs are already too close to the minimum unit of 1 gas to achieve the large degree of cost reductions that recent benchmarks^{<a href="https://wg-eips.ritovision.com/2045/#evmbenchmarks">2</a>} indicate would be needed to tune opcode gas costs to the performance of optimized EVM implementations. A smaller minimum unit called a "particle", which is a fraction (or subdivision) of 1 gas, would enable large cost reductions.</p> <h2 id="specification">Specification</h2> <p>A new gas counter <code>particlesUsed</code> is added to the EVM, in addition to the existing gas counter <code>gasUsed</code>. The unit 1 gas is equal to 10000 particles (<code>PARTICLES_PER_GAS</code>). The <code>particlesUsed</code> counter is only increased for opcodes priced in particles (i.e. opcodes that cost less than 1 gas). If increasing <code>particlesUsed</code> results in an excess of 1 gas, then 1 gas is added to <code>gasUsed</code> (and deducted from <code>particlesUsed</code>).</p> <p>Where the current gas logic looks like this:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> vm_execute</span><span>(</span><span class="z-variable z-parameter z-function">ext</span><span>,</span><span class="z-variable z-parameter z-function"> msg</span><span>,</span><span class="z-variable z-parameter z-function"> code</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Initialize stack, memory, program counter, etc</span></span> <span class="giallo-l"><span> compustate</span><span class="z-keyword"> =</span><span> Compustate</span><span>(</span><span class="z-variable">gas</span><span class="z-keyword">=</span><span>msg</span><span>.</span><span>gas</span><span>)</span></span> <span class="giallo-l"><span> codelen</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> compustate</span><span>.</span><span>pc</span><span class="z-keyword"> &lt;</span><span> codelen</span><span>:</span></span> <span class="giallo-l"><span> opcode</span><span class="z-keyword"> =</span><span> code</span><span>[</span><span>compustate</span><span>.</span><span>pc</span><span>]</span></span> <span class="giallo-l"><span> compustate</span><span>.</span><span>pc</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> compustate</span><span>.</span><span>gasUsed</span><span class="z-keyword"> +=</span><span> opcode</span><span>.</span><span>gas_fee</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> out of gas error</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> compustate</span><span>.</span><span>gasUsed</span><span class="z-keyword"> &gt;</span><span> compustate</span><span>.</span><span>gasLimit</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> vm_exception</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">OUT OF GAS</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> op</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">STOP</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> peaceful_exit</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> op</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">ADD</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span></span> <span class="giallo-l"><span> stk</span><span>.</span><span>append</span><span>(</span><span>stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span> stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> op</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">SUB</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span></span> <span class="giallo-l"><span> stk</span><span>.</span><span>append</span><span>(</span><span>stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span class="z-keyword"> -</span><span> stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> op</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">MUL</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span></span> <span class="giallo-l"><span> stk</span><span>.</span><span>append</span><span>(</span><span>stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span class="z-keyword"> *</span><span> stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant">...</span><span>.</span><span>.</span></span></code></pre> <p>The new gas logic using particles might look like this:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-constant">PARTICLES_PER_GAS</span><span class="z-keyword"> =</span><span class="z-constant"> 10000</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> vm_execute</span><span>(</span><span class="z-variable z-parameter z-function">ext</span><span>,</span><span class="z-variable z-parameter z-function"> msg</span><span>,</span><span class="z-variable z-parameter z-function"> code</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> Initialize stack, memory, program counter, etc</span></span> <span class="giallo-l"><span> compustate</span><span class="z-keyword"> =</span><span> Compustate</span><span>(</span><span class="z-variable">gas</span><span class="z-keyword">=</span><span>msg</span><span>.</span><span>gas</span><span>)</span></span> <span class="giallo-l"><span> codelen</span><span class="z-keyword"> =</span><span class="z-support"> len</span><span>(</span><span>code</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> compustate</span><span>.</span><span>pc</span><span class="z-keyword"> &lt;</span><span> codelen</span><span>:</span></span> <span class="giallo-l"><span> opcode</span><span class="z-keyword"> =</span><span> code</span><span>[</span><span>compustate</span><span>.</span><span>pc</span><span>]</span></span> <span class="giallo-l"><span> compustate</span><span>.</span><span>pc</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> opcode</span><span>.</span><span>gas_fee</span><span>:</span></span> <span class="giallo-l"><span> compustate</span><span>.</span><span>gasUsed</span><span class="z-keyword"> +=</span><span> opcode</span><span>.</span><span>gas_fee</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> opcode</span><span>.</span><span>particle_fee</span><span>:</span></span> <span class="giallo-l"><span> compustate</span><span>.</span><span>particlesUsed</span><span class="z-keyword"> +=</span><span> opcode</span><span>.</span><span>particle_fee</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> compustate</span><span>.</span><span>particlesUsed</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> PARTICLES_PER_GAS</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> particlesUsed will be between 1 and 2 gas (over 10000 but under 20000)</span></span> <span class="giallo-l"><span> compustate</span><span>.</span><span>gasUsed</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> remainder stays in particle counter</span></span> <span class="giallo-l"><span> compustate</span><span>.</span><span>particlesUsed</span><span class="z-keyword"> =</span><span> compustate</span><span>.</span><span>particlesUsed</span><span class="z-keyword"> %</span><span class="z-constant"> PARTICLES_PER_GAS</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> out of gas error</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> compustate</span><span>.</span><span>gasUsed</span><span class="z-keyword"> &gt;</span><span> compustate</span><span>.</span><span>gasLimit</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> vm_exception</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">OUT OF GAS</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> op</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">STOP</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> peaceful_exit</span><span>(</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> op</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">ADD</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span></span> <span class="giallo-l"><span> stk</span><span>.</span><span>append</span><span>(</span><span>stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span> stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> op</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">SUB</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span></span> <span class="giallo-l"><span> stk</span><span>.</span><span>append</span><span>(</span><span>stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span class="z-keyword"> -</span><span> stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span> op</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">MUL</span><span class="z-punctuation z-definition z-string">&#39;</span><span>:</span></span> <span class="giallo-l"><span> stk</span><span>.</span><span>append</span><span>(</span><span>stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span class="z-keyword"> *</span><span> stk</span><span>.</span><span>pop</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-constant">...</span><span>.</span><span>.</span></span></code></pre> <p>The above pseudocode is written for clarity. A more performant implementation might instead keep a single <code>particlesUsed</code> counter by multiplying opcode gas costs by 10000 and the <code>gasLimit</code> by 10000, and convert particles back to gas with <code>ceil(particlesUsed / PARTICLES_PER_GAS)</code> at the end of execution. It may also be more performant to use a <code>PARTICLES_PER_GAS</code> ratio that is a power of 2 (such as 8192 or 16384) instead of 10000; the spec above is a draft and updates in response to feedback are expected.</p> <h4 id="opcode-cost-changes">Opcode cost changes</h4> <p>Many computational opcodes will undergo a cost reduction, with new costs suggested by benchmark analyses. For example, the cost of <code>DUP</code> and <code>SWAP</code> are reduced from 3 gas to 3000 particles (i.e. 0.3 gas). The cost of <code>ADD</code> and <code>SUB</code> are reduced from 3 gas to 6000 particles. The cost of <code>MUL</code> is reduced from 5 gas to 5000 particles (i.e. 0.5 gas).</p> <h2 id="rationale">Rationale</h2> <p>Adoption of fractional gas costs should only be an implementation detail inside the EVM, and not alter the current user experience around transaction gas limits and block gas limits. The concept of <code>particles</code> need not be exposed to Ethereum users nor most contract authors, but only to EVM implementers and contract developers concerned with optimized gas usage. Furthermore, only the EVM logic for charging gas per opcode executed should be affected by this change. All other contexts dealing with gas and gas limits, such as block headers and transaction formats, should be unaffected.</p> <h3 id="ewasm">Ewasm</h3> <p>The term "particles" was first introduced for Ewasm^{<a href="https://wg-eips.ritovision.com/2045/#particle">3</a>} to enable gas accounting for low cost wasm instructions, while remaining compatible with EVM gas costs. This EIP proposes introducing particles as a new minimum gas unit for EVM opcodes, and is not related to Ewasm.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not backwards compatible and requires a hard fork to be activated.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO</p> <h2 id="implementation">Implementation</h2> <p>TODO</p> <h2 id="references">References</h2> <p><a name="eip2035">1</a>. <a href="https://wg-eips.ritovision.com/2035/">EIP-2035</a>: Stateless Clients - Repricing SLOAD and SSTORE to pay for block proofs</p> <p><a name="evmbenchmarks">2</a>. https://github.com/ewasm/benchmarking</p> <p><a name="particle">3</a>. The term "particle" was inspired by a proposal for <a rel="external" href="https://github.com/ewasm/design/blob/e77d8e3de42784f40a803a23f58ef06881142d9f/determining_wasm_gas_costs.md">Ewasm gas costs</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/2046/ <h2 id="simple-summary">Simple Summary</h2> <p>This change reduces the gas cost of using precompiled contracts.</p> <h2 id="abstract">Abstract</h2> <p>Reduce the base gas cost of calling precompiles using <code>STATICCALL</code> from 700 to 40. This should allow more efficient use of precompiles as well as precompiles with a total cost below 700.</p> <h2 id="motivation">Motivation</h2> <p>The Spurious Dragon hard fork increased the cost of calls significantly to account for loading contract code from the state without making an exception for precompiles, whose "code" is always loaded.</p> <p>This made use of certain precompiles impractical.</p> <p>FIXME: extend this with recent reasoning about ECC repricings.</p> <h2 id="specification">Specification</h2> <p>After block <code>HF</code> the <code>STATICCALL</code> (<code>0xfa</code>) instruction charges different basic gas cost (G_call in <a rel="external" href="https://github.com/ethereum/yellowpaper">Yellow Paper</a>'s notation) depending on the destination address provided:</p> <ul> <li>for precompiles (address range as per <a href="https://wg-eips.ritovision.com/1352/">EIP-1352</a>) the cost is <code>40</code></li> <li>for every other address the cost remains unchanged (<code>700</code>)</li> </ul> <h2 id="rationale">Rationale</h2> <p>Only the <code>STATICCALL</code> instruction was changed to reduce the impact of the change. This should not be a limiting factor, given precompiles (currently) do not have a state and cannot change the state. However, contracts created and deployed before Byzantium likely will not use <code>STATICCALL</code> and as a result this change will not reduce their costs.</p> <p>Contrary to EIP-1109 gas reduction to <code>0</code> is not proposed. The cost <code>40</code> is kept as a cost representing the context switching needed.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP should be backwards compatible. The only effect is that the cost is reduced. Since the cost is not reduced to zero, it should not be possible for a malicious proxy contract, when deployed before the <code>HF</code>, to do any state changing operation.</p> <h2 id="test-cases">Test Cases</h2> <p>TBA</p> <h2 id="implementation">Implementation</h2> <p>TBA</p> <h2 id="references">References</h2> <p>This has been previously suggested as part of <a href="https://wg-eips.ritovision.com/1109/">EIP-1109</a> and <a rel="external" href="https://github.com/ethereum/EIPs/pull/1231">EIP-1231</a>. However EIP-1109 was later changed to a very different approach. The author <a rel="external" href="https://ethereum-magicians.org/t/eip-1109-remove-call-costs-for-precompiled-contracts/447/7">has suggested to change EIP-1109</a>.</p> <h2 id="acknowledgements">Acknowledgements</h2> <p>Jordi Baylina (@jbaylina) and Matthew Di Ferrante (@mattdf) who have proposed this before.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alexey Akhunovhttps://github.com/AlexeyAkhunov https://wg-eips.ritovision.com/2035/ <h2 id="simple-summary">Simple Summary</h2> <p>The gas cost of EVM opcodes <code>SLOAD</code> and <code>SSTORE</code> increases in order to accommodate extra bandwidth required to propagate block proof together with the block headers and block bodies, as explained <a rel="external" href="https://medium.com/@akhounov/data-from-the-ethereum-stateless-prototype-8c69479c8abc">here</a>.</p> <h2 id="abstract">Abstract</h2> <p>It is part of the State Rent roadmap. This particular change prepares Ethereum for introduction of the block proofs (current understanding is that they can be introuced without a hard fork). The introduction of the block proofs allows any Ethereum node that wishes to receive them, to process transactions in the blocks without needing to access the Ethereum state. All necessary information for the execution (and the proof of validity) is continued in the block proofs. In most Ethereum nodes, it will speed up the block processing and reduce the memory footprint of such processing. For mining nodes, however, there will be more work to do to construct and transmit the block proofs. Therefore, the extra charge (payable to the miners) is introduced. In the first phase, only contract storage will be covered by the block proofs. It means that the Ethereum nodes will still need access to the accounts in the state, but block proofs will make it optional to have access to contract storage for executing transactions. Therefore, only <code>SSTORE</code> and <code>SLOAD</code> opcodes are affected.</p> <h2 id="motivation">Motivation</h2> <p>There is <a rel="external" href="https://github.com/holiman/vmstats/blob/master/README.md">empirical analysis</a> showing that <code>SLOAD</code> opcode is currently underpriced in terms of execution latency it adds to the block processing. The hypothesis is that it is due to the latency of the database accesses. In the same analysis, <code>SSTORE</code> is not considered, because its effect on the database accesses can be (and are in many implementations) delayed until the end of the block. Stateless clients approach to the contract storage will largely negate that latency because no database accesses will be required. Instead, bandwidth consumption goes up. There is emprical analysis (unpublished, but will be) suggesting that 1 uncached <code>SSTORE</code> or <code>SLOAD</code> adds at most 1 kB to the block proofs. At the current cost of data transmission (68 gas per byte), this translates to the increase of gas cost of both operations by 69k gas. However, in light of proposal in <a href="https://wg-eips.ritovision.com/2028/">EIP-2028</a>, the increase can be made much smaller.</p> <h2 id="specification">Specification</h2> <p>Not very formal at the moment, but will be formalised with more research and prototyping. Gas of operations <code>SLOAD</code> and <code>SSTORE</code> increases by <code>X</code> gas when the storage slots accessed (read by <code>SLOAD</code> or written by <code>SSTORE</code>) were not previously accessed (by another <code>SLOAD</code> or <code>SSTORE</code>) during the same transaction.</p> <p>Future variant (will be possible after the implementation of the <em>Gross contract size acccounting</em>) is researched, where the increase is varied depending on the size of the contract storage, i.e. <code>SLOAD</code> and <code>SSTORE</code> for smaller contracts will be cheaper.</p> <h2 id="rationale">Rationale</h2> <p><a href="https://wg-eips.ritovision.com/1884/">EIP-1884</a> seeks to increase the gas cost of <code>SLOAD</code> but using a different justification (latency of the execution as described in the Motivation). This EIP is likely to increase the cost of <code>SLOAD</code> by a larger amount, therefore partially (because EIP-1884 also proposed other increases) supersedes EIP-1884.</p> <p><a href="https://wg-eips.ritovision.com/2028/">EIP-2028</a> describes the model that can be used for deciding the gas cost of data transmission. It is relevant because in the stateless client regime <code>SSTORE</code> and <code>SLOAD</code> operations add more data to be transmitted (as well as computation to verify the proofs).</p> <p>The main alternate design is the rent proportional to the size of the contract storage, which unfortunately introduces a serious griefing vulnerability problem, and so far the solution seems to be in redesigning and rewriting smart contracts in a way, which makes them not vulnerable. However, this approach is likely to be very expensive on the non-technical (ecosystem) level.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not backwards compatible and requires hard fork to be activated. There might also be an adverse effect of this change on the already deployed contract. It is expected that after this EIP and <a href="https://wg-eips.ritovision.com/2026/">EIP-2026</a> (rent prepayment for accounts), the recommendation will be made to raise the gas limit. This can somewhat dampen the adverse effect of EIP. The most problematic cases would be with the contracts that assume certain gas costs of <code>SLOAD</code> and <code>SSTORE</code> and hard-code them in their internal gas computations. For others, the cost of interacting with the contract storage will rise and may make some dApps based on such interactions, non-viable. This is a trade off to avoid even bigger adverse effect of the rent proportional to the contract storage size. However, more research is needed to more fully analyse the potentially impacted contracts.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests cases will be generated out of a reference implementation.</p> <h2 id="implementation">Implementation</h2> <p>There will be proof of concept implementation to refine and clarify the specification.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alexey Akhunovhttps://github.com/AlexeyAkhunov https://wg-eips.ritovision.com/2029/ <h2 id="simple-summary">Simple Summary</h2> <p>A smart contract is deployed on all Ethereum networks, at a pre-determined address, with the code that simply reads the slot in its storage specified by the only parameter. Later, this contract becomes "special" in that Ethereum start writing state counters (number of total transactions, number of accounts, etc.) into that contract.</p> <h2 id="abstract">Abstract</h2> <p>This is part of the State Rent roadmap. This particular change introduces a place in the Ethereum state where various state counters can be stored. At this point, the most important counter is the total number of transactions happened, and this counter will be used to populate the nonces of newly created non-contract accounts. This way of populating nonce ensures replay protection for accounts that were evicted and then brought back by sending ether to them.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum currently does not have a special place in the state for tracking state counters such as number of transactions or number of accounts.</p> <h2 id="specification">Specification</h2> <p>Prior to the block A, a contract is deployed with the following code: <code>0x60 0x20 0x60 0x00 0x80 0x80 0x35 0x54 0x90 0x52 0xF3</code>, which corresponds to this assembly: <code>PUSH1 32 PUSH1 0 DUP1 DUP1 CALLDATALOAD SLOAD SWAP1 MSTORE RETURN</code> Call to this contract accepts one 32-byte argument, <code>x</code>, and returns the value of the storage item [<code>x</code>].</p> <p>This contract is deployed using <code>CREATE2</code> opcode in such a way that it has the same address on any network.</p> <h2 id="rationale">Rationale</h2> <p>Two alternative solutions were considered so far:</p> <ol> <li>Extending the structure of the Ethereum state to introduce more fields, and hence change the way the state root is constructed. The main downside of this approach is the impact on the software what is currently coupled with the particular way the state root is constructed. Particularly it affects the software that deals with merkle proofs derived from the state root.</li> <li>Extended State Oracle (<a href="https://wg-eips.ritovision.com/2014/">EIP-2014</a>). Under such proposal, there will be a precompile contract with standardised interface, capable of returning current values of the counters. However, the actual data being returned by such oracle is not explicitly in the state, and is not Merkelised. It means that all the counters need to be added to the snapshots when the snapshot sync is perform, so they still present in the state, but implicitly.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is backwards compatible and does not require hard fork to be activated.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests cases will be created to ensure that the state counter contract returns its storage items correctly.</p> <h2 id="implementation">Implementation</h2> <p>Implementation is envisaged as a transaction that can be posted from any Ethereum address and will cause the deployment of the state counter contract.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alexey Akhunovhttps://github.com/AlexeyAkhunov https://wg-eips.ritovision.com/2031/ <h2 id="simple-summary">Simple Summary</h2> <p>Ethereum starts to track the number of transactions inside its state (for now, only number of transactions after this change is introduced, therefore it is called <em>Net</em> transaction count). It is done by incrementing a storage slot in the special contract, called <em>State counter contract</em> (<a href="https://wg-eips.ritovision.com/2029/">EIP-2029</a>).</p> <h2 id="abstract">Abstract</h2> <p>It is part of the State Rent roadmap. This particular change makes any Ethereum transaction increment the transaction counter, which is a special storage slot in the <em>State counter contract</em>. This counter will be used to populate the nonces of newly created non-contract accounts. This way of populating nonce ensures replay protection for accounts that were evicted and then brought back by sending ether to them.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum currently does not have a special place in the state for tracking number of transactions.</p> <h2 id="specification">Specification</h2> <p>A new field, with the location 0 (that means it resides in the storage slot 0 in the state counter contract, and can be read by calling that contract with argument being 32 zero bytes), is added to the state counter contract. It will eventually contain <code>txCount</code>, the total number of transactions processed up until that point. On an after block B, or after the deployment of the state counter contract (which comes first), the field <code>txCount</code> is incremented after each transaction. Updating <code>txCount</code> means updating the storage of state counter contract at the location 0. These changes are never reverted.</p> <h2 id="rationale">Rationale</h2> <p>Two main alternatives were proposed for the replay protection of the accounts that were evicted by subsequently brought back by sending ether to them:</p> <ol> <li>Temporal replay protection. The nonce of the new accounts (and those brought back) is still zero, but a new <code>valid-until</code> field is introduced, making transactions invalid for inclusion after the time specified in this field. This, however, has unwanted side effected related to the fact that account nonces are not only used for replay protection, but also for computing the addresses of the deployed contracts (except those created by <code>CREATE2</code>).</li> <li>Setting nonce of new accounts (and those brought back) to something depending on the current block number. This approach requires coming up with an arbitrary parameter, which is the maximum number of transaction in the block, so that the new nonces never clash with the existing nonces. This is mostly a concern for private networks at the moment, because they will potentially have significantly more transactions in a block.</li> </ol> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not backwards compatible and requires hard fork to be activated.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests cases will be generated out of a reference implementation.</p> <h2 id="implementation">Implementation</h2> <p>There will be proof of concept implementation to refine and clarify the specification.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alexey Akhunovhttps://github.com/AlexeyAkhunov https://wg-eips.ritovision.com/2026/ <h2 id="simple-summary">Simple Summary</h2> <p>Creation of new accounts (both contracts and non-contracts) requires a fixed one-off rent prepayment. Pre-existed accounts require the same prepayment upon the first modification. The act of rent prepayment causes the addition of an extra field to accounts, called <code>rentbalance</code>. This field becomes part of state.</p> <h2 id="abstract">Abstract</h2> <p>This is part of the State Rent roadmap. This particular change introduces a fixed charge for state expansion that comes from adding new accounts to the state. Theoretically, it puts a bound on the number of accounts that can be ever created, because that fixed charge cannot be recycled via mining.</p> <h2 id="motivation">Motivation</h2> <p>The penalty is levied to the transaction sender. Rather than raising the gas cost of account creation (that would direct levy towards the miner), this change directs prepayment into the account's special field, <code>rentbalance</code>. It addresses several shortcomings of the simple raising of the gas cost:</p> <ol> <li>Prepayments cannot be recycled via mining, which puts a theoretical bound on number of accounts in the state (though it is unlikely to ever be reached).</li> <li>It is not possible for miners to circumvent the penalty or to extend such circumventions onto other users (via private fee rebates, for example).</li> <li>This prepayment will be used to cover state rent in the future, and it will allow newly created contracts with 0 endowment not to be evicted in the same block.</li> <li>It makes is possible to refund <code>rentbalance</code> upon self-destruction - when contract is self-destructed, both <code>balance</code> and <code>rentbalance</code> are returned.</li> <li>Prepayments on pre-existing accounts are necessary to prevent hoarding of accounts ahead of this change.</li> </ol> <h2 id="specification">Specification</h2> <p>On and after block <code>H</code>, every newly created account gets a new field <code>rentbalance</code> of type unsigned 256-bit integer. On and after block <code>H</code>, any operation that leads to the creation of a new account, deducts the amount <code>ACCOUNT_PREPAYMENT</code> from <code>tx.origin</code>. This amount is added to the <code>rentbalance</code> field of the created account. On and after block <code>H</code>, any operation that modifies an account that does not yet have <code>rentbalance</code> field, deducts the amount <code>ACCOUNT_PREPAYEMENT</code> from <code>tx.origin</code>. This amount is added to the <code>rentbalance</code> field of the modified account. This is an anti-hoarding measure.</p> <p>Operations leading to the creations of a new account:</p> <ol> <li>Creation of a non-contract account by sending non-zero ETH to an address with no associated account</li> <li>Creation of a non-contract account by the block with <code>coinbase</code> pointing to an address with no associated account</li> <li>Creation of a non-contract account by <code>SELFDESTRUCT</code> with the argument being an address with no associated account</li> <li>Creation of a contract by transaction without destination but with data. This can result in either converting a non-countract account into a contract account, or creation of a contract account.</li> <li>Creation of a contract by execution of <code>CREATE</code> or <code>CREATE2</code>. This can result in either converting a non-countract account into a contract account, or creation of a contract account.</li> </ol> <p>After prepayments are introduced, there can be two reasons for ether to be deducted from <code>tx.origin</code>: purchasing and spending gas, and spending gas for prepayments. Gaslimit of a transaction currently plays a role of safety limit, where <code>gaslimit</code> * <code>gasprice</code> represents the maximum amount of wei the sender (<code>tx.origin</code>) authorises the transaction to deduct from its account. After prepayments are introduced, <code>gaslimit</code> * <code>gasprice</code> will still represent the maximum amount of wei spend, but it will be used for both gas purchases and prepayments, as necessary.</p> <h2 id="rationale">Rationale</h2> <p>Prior to rent prepayments, other alternatives were considered:</p> <ol> <li>Simple raising of the gas cost - discussed in the Motivation section.</li> <li>In <a rel="external" href="https://github.com/ledgerwatch/eth_state/blob/master/State_rent.pdf">first version of State Rent proposal</a>, there was no notion of extra levy upon account creation. It created a slight usability issue, where newly created contracts with 0 endowment would be evicted in the same block (when rent is introduced). It delays the benefits of the State Rent programme until the actual introduction of rent (in second or third hard-fork).</li> <li>In the <a rel="external" href="https://github.com/ledgerwatch/eth_state/blob/master/State_Rent_2.pdf">second version of State Rent proposal</a>, there was a notion of lock-up. It is very similar to rent prepayment, with the different that lock-up would not be covering future rent payments.</li> </ol> <p>An alternative approach to limiting the prepayments (instead of the using <code>gaslimit</code> * <code>gasprice</code> as the limit) is to introduce a new dedicated field <code>prepaymenlimit</code> into the transaction. This field would only limit prepayments. Such approach would require changes in the transaction format, as well as changes in the user interface for transaction sender, and having two counters during the transaction execution - one for gas, and one for prepayments.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not backwards compatible and requires hard fork to be activated. It might have some adverse effects on the existing contracts, due to more gas needed to be allocated for the creation of new accounts. These adverse effects need to analysed in more detail.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests cases will be generated out of a reference implementation.</p> <h2 id="implementation">Implementation</h2> <p>There will be proof of concept implementation to refine and clarify the specification.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alexey Akhunovhttps://github.com/AlexeyAkhunov https://wg-eips.ritovision.com/2027/ <h2 id="simple-summary">Simple Summary</h2> <p>Ethereum starts counting the number of storage slots filled and emptied in the contracts. Since the number of pre-existing slots is not currently accounted in the state, effectively, only net change in the number of slots is tracked. In the subsequent change, called <em>Gross contract size accounting</em>, the total number of storage slots starts being tracked.</p> <h2 id="abstract">Abstract</h2> <p>This is part of the State Rent roadmap. This particular change introduces initial, net accounting of the number of the contract storage slots. Though not very useful on its own, it makes it possible to introduce gross accounting of the number of storage slots, which is useful for number of things:</p> <ol> <li>Gas cost of operations suchs as <code>SLOAD</code> and <code>SSTORE</code> will need to be increased to compensate for extra bandwidth consumed by the block proofs. Although in the beginning the cost would be fixed, it will later be automatically calibrated depending on the size of the contract <code>SLOAD</code> and <code>SSTORE</code> operate on.</li> <li>Snapshot sync protocols, like <em>fast sync</em>, <em>warp sync</em>, <em>firehose</em>, <em>red queen</em>, and perhaps others, will benefit from having the correct size of the contract storage present in the state (and therefore being provable via Merkle proofs).</li> </ol> <h2 id="motivation">Motivation</h2> <p>Ethereum currently does not track the number of contract storage slots at all, and producing such number given the downloaded state cannot be done in constant <em>O(1)</em> time.</p> <h2 id="specification">Specification</h2> <p>Each contract (account with <code>codeHash</code> field not equal to 0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470, which the hash of the empty code) gets a new uint64 field, called <code>storagesize</code>. On and after block <code>C</code>, the semantics of the operation <code>SSTORE</code> (<code>location</code>, <code>value</code>) changes as follows:</p> <ul> <li>If previous value of the [<code>location</code>] is 0, and value is not 0, <em>increment</em> <code>storagesize</code> (semantics of <em>increment</em> described below)</li> <li>If previous value of the [<code>location</code>] is not 0, and value is 0, <em>decrement</em> <code>storagesize</code> (semantics of <em>decrement</em> described below)</li> <li>As with other state changes, changes of <code>storagesize</code> get reverted when the execution frame reverts, i.e. it needs to use the same techniques as storage values, like journalling (in Geth), and substates (in Parity). Value of <code>storagesize</code> is not observable from contracts at this point.</li> </ul> <h3 id="semantics-of-increment-storagesize">Semantics of <em>increment</em> <code>storagesize</code></h3> <p>If <code>storagesize</code> is not present, <code>storagesize</code> = <code>HUGE_NUMBER</code> + 1. If <code>storagesize</code> is present, <code>storagesize</code> = <code>storagesize</code> + 1.</p> <h3 id="semantics-of-decrement-storagesize">Semantics of <em>decrement</em> <code>storagesize</code></h3> <p>If <code>storagesize</code> is not present, <code>storagesize</code> = <code>HUGE_NUMBER</code> - 1. If <code>storagesize</code> is present, <code>storagesize</code> = <code>storagesize</code> - 1.</p> <h3 id="note-of-huge-number">Note of <code>HUGE_NUMBER</code></h3> <p>There is a constant <code>HUGE_NUMBER</code>. It needs to be large enough so that no real metrics (contract storage size, number of accounts, number of contracts, total size of code, total size of storage) will never reach that number, and small enough that it fits in an unsigned 64-bit integer. Current suggestion is to have <code>HUGE_NUMBER</code> = 2^63, which is binary representation is the a single bit in a 64-bit number.</p> <p>The idea is to make it decidable later whether the storagesize was ever incremented/decremented (presence of the field), and whether it has been converted from net to gross (by value being smaller than <code>HUGE_NUMBER/2</code> - because it will not be possible for any contract be larger than 2^62 at the block <code>C</code>).</p> <h2 id="rationale">Rationale</h2> <p>A mechanism for estimation of contract storage size has been proposed <a rel="external" href="https://medium.com/@akhounov/estimation-approximate-of-the-size-of-contracst-in-ethereum-4642fe92d6fe">here</a>. But it does have a big drawback of introducing a lot of complexity into the consensus (in the form of estimation algorithm, which has quite a few edge cases to cater for different sizes of the storage).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not backwards compatible and requires hard fork to be activated. Since the newly introduced field is not observable, this change does not impact any operations of the existing smart contracts.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests cases will be generated out of a reference implementation.</p> <h2 id="implementation">Implementation</h2> <p>There will be proof of concept implementation to refine and clarify the specification.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-12T00:00:00+00:00 2026-02-11T14:49:27+00:00 Pedro Gomeshttps://github.com/pedrouid Erik Markshttps://github.com/rekmarks Pandapip1https://github.com/Pandapip1 https://wg-eips.ritovision.com/2015/

Adds an RPC method to switch between EVM-compatible chains

<h2 id="abstract">Abstract</h2> <p>This EIP adds a wallet-namespaced RPC endpoint, <code>wallet_updateEthereumChain</code>, providing a standard interface for switching chains. The method takes the minimal parameters of <code>chainId</code>, <code>chainName</code>, <code>rpcUrl</code>, <code>nativeCurrency</code> and <code>blockExplorerUrl</code>.</p> <h2 id="specification">Specification</h2> <p>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> <p>This proposal adds a method to a wallet's web3 provider API: <code>wallet_updateEthereumChain</code>.</p> <h3 id="wallet-updateethereumchain"><code>wallet_updateEthereumChain</code></h3> <p>The <code>wallet_updateEthereumChain</code> method is used to switch to a network, and registering it with the wallet if it isn't already recognized.</p> <p>The <code>wallet_updateEthereumChain</code> method takes one parameter, an <code>EthereumChainSwitchRequest</code> object, defined below:</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> NativeCurrencyData</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> name</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> symbol</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> decimals</span><span class="z-keyword">:</span><span class="z-support"> number</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EthereumChainSwitchRequest</span><span> {</span></span> <span class="giallo-l"><span class="z-variable"> chainId</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> chainName</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> rpcUrls</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>[</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> nativeCurrency</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-entity z-name"> NativeCurrencyData</span><span>;</span></span> <span class="giallo-l"><span class="z-variable"> blockExplorerUrl</span><span class="z-keyword">?</span><span class="z-keyword">:</span><span class="z-support"> string</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>chainId</code> is the <code>0x</code>-prefixed <a href="https://wg-eips.ritovision.com/155/">EIP-155</a>-compliant chain ID. The <code>chainName</code> is a suggested human-readable name of the chain, to be displayed to the user. The <code>rpcUrls</code> array is a list of RPC endpoints for the given <code>chainId</code>. The <code>nativeCurrency</code> object suggests how the native currency should be displayed. Its parameters, <code>name</code>, <code>symbol</code>, and <code>decimals</code>, should be interpreted like in <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>. Finally, the <code>blockExplorerUrl</code> should link to a block explorer compatible with the given <code>chainId</code>.</p> <p>All keys other than the <code>chainId</code> are optional. All keys other than <code>chainId</code> are suggestions to the wallet. Wallets can choose to ignore or display other data to users. Wallets should prompt the user before switching or adding chains. Wallets should also store a default list of data for commonly-used chains, in order to avoid phishing attacks. Wallets MUST sanitize each RPC url before using it to send other requests, including ensuring that it responds correctly to the <code>net_version</code> and <code>eth_chainId</code> methods.</p> <p>The <code>wallet_updateEthereumChain</code> method returns <code>true</code> if the active chain matches the requested chain, regardless of whether the chain was already active or was added to the wallet previously. If the user rejects the request, it must return an error with code <code>4001</code>.</p> <h2 id="rationale">Rationale</h2> <p>The <code>wallet_updateEthereumChain</code> method is designed to be as simple as possible, while still providing the necessary information for a wallet to switch to a new chain. The <code>chainId</code> is the only required parameter, as it is the only parameter that is guaranteed to be unique. The <code>chainName</code> is included to provide a human-readable name for the chain, and the <code>rpcUrls</code> array is included to provide a list of RPC endpoints for the chain. The <code>nativeCurrency</code> object is included to provide a suggestion for how the native currency should be displayed. Finally, the <code>blockExplorerUrl</code> is included to provide a link to a block explorer for the chain.</p> <p>The <code>wallet_updateEthereumChain</code> method is namespaced under <code>wallet_</code> to avoid conflicts with other methods. The <code>wallet_</code> prefix is used by other methods that are wallet-specific, such as <code>wallet_addEthereumChain</code> and <code>wallet_switchEthereumChain</code>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible.</p> <h2 id="security-considerations">Security Considerations</h2> <h3 id="server-side-request-forgery-ssrf">Server-Side Request Forgery (SSRF)</h3> <p>The <code>rpcUrls</code> parameter is a list of RPC endpoints for the chain. Wallets should sanitize each RPC url before using it to send other requests, including ensuring that it responds correctly to the <code>net_version</code> and <code>eth_chainId</code> methods.</p> <h3 id="phishing">Phishing</h3> <p>Wallets should store a default list of data for commonly-used chains, in order to avoid phishing attacks.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/2014/ <h2 id="simple-summary">Simple Summary</h2> <h2 id="abstract">Abstract</h2> <p>Introduce a new system contract with an extensible interface following the <a rel="external" href="https://solidity.readthedocs.io/en/latest/abi-spec.html">Contract ABI Encoding</a> to access extended data sets, such as chain identifiers, block hashes, etc.</p> <p>This allows Ethereum contract languages to interact with this contract as if it were a regular contract and not needing any language support.</p> <h2 id="motivation">Motivation</h2> <p>Over the past couple of years several proposals were made to extend the EVM with more data. Some examples include extended access to block hashes (<a href="https://wg-eips.ritovision.com/210/">EIP-210</a>) and chain identifiers (<a href="https://wg-eips.ritovision.com/1344/">EIP-1344</a>).</p> <p>Adding them as EVM opcodes seems to be using the scarce opcode space for relatively less frequently used features, while adding them as precompiles is perceived as more complicated due to an interface needs to be defined and agreed on for every case.</p> <p>This proposal tries to solve both issues with defining an extensible standard interface.</p> <h2 id="specification">Specification</h2> <p>A new system contract ("precompile") is introduced at address <code>0x0000000000000000000000000000000000000009</code> called ESO (Extended State Oracle).</p> <p>It can be queried using <code>CALL</code> or <code>STATICCALL</code> and follows the <a rel="external" href="https://solidity.readthedocs.io/en/latest/abi-spec.html">Contract ABI Encoding</a> for the inputs and outputs. Using elementary types in the ABI encoding is encouraged to keep complexity low.</p> <p>In the future it could be possible to extend ESO to have a state and accept transactions from a system address to store the passed data -- similarly to what <a href="https://wg-eips.ritovision.com/210/">EIP-210</a> proposed.</p> <p>Proposals wanting to introduce more data to the state, which is not part of blocks or transactions, should aim to extend the ESO.</p> <p>At this time it is not proposed to make the ESO into a contract existing in the state, but to include it as a precompile and leave the implementation details to the client. In the future if it is sufficiently extended and a need arises to have a state, it would make sense to move it from being a precompile and have actual code.</p> <h3 id="chain-identifier">Chain identifier</h3> <p>Initially, a feature to read the current chain identifier is introduced: <code>getCurrentChainId()</code> returns the current chain identifier as a <code>uint64</code> encoded value. It should be a non-payable function, which means sending any value would revert the transaction as described in <a href="https://wg-eips.ritovision.com/140/">EIP-140</a>. This has been proposed as <a href="https://wg-eips.ritovision.com/1344/">EIP-1344</a>.</p> <p>The contract ABI JSON is the following:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">constant</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> true</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">getCurrentChainId</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">outputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint64</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">payable</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">stateMutability</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">pure</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">function</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>]</span></span></code></pre> <p>This will be translated into sending the bytes <code>5cf0e8a4</code> to the ESO and returning the bytes <code>0000000000000000000000000000000000000000000000000000000000000001</code> for Ethereum mainnet.</p> <p><strong>Note:</strong> It should be possible to introduce another interface checking the validity of a chain identifier in the chain history or for a given block (see <a rel="external" href="https://github.com/ethereum/EIPs/pull/1959">EIP-1959</a> and <a rel="external" href="https://github.com/ethereum/EIPs/pull/1965">EIP-1965</a>).</p> <h2 id="rationale">Rationale</h2> <p>TBA</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>TBA</p> <h2 id="test-cases">Test Cases</h2> <p>TBA</p> <h2 id="implementation">Implementation</h2> <p>TBA</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Fernando Parisfer@io.builders Julio Faurajulio@adhara.io Daniel Lehrnerdaniel@io.builders https://wg-eips.ritovision.com/2019/ <h2 id="simple-summary">Simple Summary</h2> <p>An extension to the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard token that allows Token wallet owners to request a wallet to be funded, by calling the smart contract and attaching a fund instruction string.</p> <h2 id="actors">Actors</h2> <h4 id="token-wallet-owners">Token Wallet Owners</h4> <p>The person or company who owns the wallet, and will order a token fund request into the wallet.</p> <h4 id="token-contract-owner-agent">Token contract owner / agent</h4> <p>The entity, company responsible/owner of the token contract, and token issuing/minting. This actor is in charge of trying to fulfill all fund request(s), reading the fund instruction(s), and correlate the private payment details.</p> <h4 id="orderer">Orderer</h4> <p>An actor who is enabled to initiate funding orders on behalf of a token wallet owner.</p> <h2 id="abstract">Abstract</h2> <p>Token wallet owners (or approved addresses) can order tokenization requests through blockchain. This is done by calling the <code>orderFund</code> or <code>orderFundFrom</code> methods, which initiate the workflow for the token contract operator to either honor or reject the fund request. In this case, fund instructions are provided when submitting the request, which are used by the operator to determine the source of the funds to be debited in order to do fund the token wallet (through minting).</p> <p>In general, it is not advisable to place explicit routing instructions for debiting funds on a verbatim basis on the blockchain, and it is advised to use a private communication alternatives, such as private channels, encrypted storage or similar, to do so (external to the blockchain ledger). Another (less desirable) possibility is to place these instructions on the instructions field in encrypted form.</p> <h2 id="motivation">Motivation</h2> <p>Nowadays most of the token issuing/funding request, based on any fiat based payment method need a previous centralized transaction, to be able to get the desired tokens issued on requester's wallet. In the aim of trying to bring all the needed steps into decentralization, exposing all the needed steps of token lifecycle and payment transactions, a funding request can allow wallet owner to initiate the funding request via blockchain. Key benefits:</p> <ul> <li>Funding and payment traceability is enhanced bringing the initiation into the ledger. All payment stat s can be stored on chain.</li> <li>Almost all money/token lifecycle is covered via a decentralized approach, complemented with private communications which is common use in the ecosystem.</li> </ul> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IFundable</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC-20 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> FundStatusCode</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Nonexistent</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Ordered</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> InProcess</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Executed</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Rejected</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Cancelled</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizeFundOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> orderer</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeFundOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> orderer</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> ;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> orderFund</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> instructions</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> orderFundFrom</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> walletToFund</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> instructions</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelFund</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> processFund</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeFund</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> rejectFund</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> reason</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isFundOperatorFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> walletToFund</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> orderer</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> retrieveFundData</span><span>(</span><span class="z-support">address</span><span class="z-variable"> orderer</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> walletToFund</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> instructions</span><span>,</span><span class="z-storage z-type"> FundStatusCode</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundOrdered</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> indexed</span><span> ,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>, </span><span class="z-support">string</span><span class="z-variable"> instructions</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundInProcess</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundExecuted</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundRejected</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> reason</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundCancelled</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundOperatorAuthorized</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> walletToFund</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> FundOperatorRevoked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> walletToFund</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="functions">Functions</h3> <h4 id="authorizefundoperator">authorizeFundOperator</h4> <p>Wallet owner, authorizes a given address to be fund orderer.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer.</td></tr> </tbody></table> <h4 id="revokefundoperator">revokeFundOperator</h4> <p>Wallet owner, revokes a given address to be fund orderer.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer.</td></tr> </tbody></table> <h4 id="orderfund">orderFund</h4> <p>Creates a fund request, that will be processed by the token operator. The function must revert if the operation ID has been used before.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request</td></tr> <tr><td>value</td><td>The amount to be funded.</td></tr> <tr><td>instruction</td><td>A string including the payment instruction.</td></tr> </tbody></table> <h4 id="orderfundfrom">orderFundFrom</h4> <p>Creates a fund request, on behalf of a wallet owner, that will be processed by the token operator. The function must revert if the operation ID has been used before.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request</td></tr> <tr><td>walletToFund</td><td>The wallet to be funded on behalf.</td></tr> <tr><td>value</td><td>The amount to be funded.</td></tr> <tr><td>instruction</td><td>A string including the payment instruction.</td></tr> </tbody></table> <h4 id="cancelfund">cancelFund</h4> <p>Cancels a funding request.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request that is going to be cancelled. This can only be done by token holder, or the fund initiator.</td></tr> </tbody></table> <h4 id="processfund">processFund</h4> <p>Marks a funding request as on process. After the status is on process, order cannot be cancelled.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request is in process.</td></tr> </tbody></table> <h4 id="executefund">executeFund</h4> <p>Issues the amount of tokens and marks a funding request as executed.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request that has been executed.</td></tr> </tbody></table> <h4 id="rejectfund">rejectFund</h4> <p>Rejects a given operation with a reason.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request that has been executed.</td></tr> <tr><td>reason</td><td>The specific reason that explains why the fund request was rejected. EIP 1066 codes can be used</td></tr> </tbody></table> <h4 id="isfundoperatorfor">isFundOperatorFor</h4> <p>Checks that given player is allowed to order fund requests, for a given wallet.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>walletToFund</td><td>The wallet to be funded, and checked for approval permission.</td></tr> <tr><td>orderer</td><td>The address of the orderer, to be checked for approval permission.</td></tr> </tbody></table> <h4 id="retrievefunddata">retrieveFundData</h4> <p>Retrieves all the fund request data. Only operator, tokenHolder, and orderer can get the given operation data.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the fund order.</td></tr> </tbody></table> <h3 id="events">Events</h3> <h4 id="fundordered">FundOrdered</h4> <p>Emitted when an token wallet owner orders a funding request.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request</td></tr> <tr><td>walletToFund</td><td>The wallet that the player is allowed to start funding requests</td></tr> <tr><td>value</td><td>The amount to be funded.</td></tr> <tr><td>instruction</td><td>A string including the payment instruction.</td></tr> </tbody></table> <h4 id="fundinprocess">FundInProcess</h4> <p>Emitted when an operator starts a funding request after validating the instruction, and the operation is marked as in process.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the fund request orderer.</td></tr> <tr><td>operationId</td><td>The unique ID to identify the fund.</td></tr> </tbody></table> <h4 id="fundexecuted">FundExecuted</h4> <p>Emitted when an operator has executed a funding request.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the fund request orderer.</td></tr> <tr><td>operationId</td><td>The unique ID to identify the fund.</td></tr> </tbody></table> <h4 id="fundrejected">FundRejected</h4> <p>Emitted when an operator has rejected a funding request.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the fund request orderer.</td></tr> <tr><td>operationId</td><td>The unique ID to identify the fund.</td></tr> <tr><td>reason</td><td>The specific reason that explains why the fund request was rejected. EIP 1066 codes can be used</td></tr> </tbody></table> <h4 id="fundcancelled">FundCancelled</h4> <p>Emitted when a token holder, orderer, has cancelled a funding request. This can only be done if the operator hasn't put the funding order in process.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the fund request orderer.</td></tr> <tr><td>operationId</td><td>The unique ID to identify the fund.</td></tr> </tbody></table> <h4 id="fundoperatorauthorized">FundOperatorAuthorized</h4> <p>Emitted when a given player, operator, company or a given persona, has been approved to start fund request for a given token holder.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>walletToFund</td><td>The wallet that the player is allowed to start funding requests</td></tr> <tr><td>orderer</td><td>The address that allows the player to start requests.</td></tr> </tbody></table> <h4 id="fundoperatorrevoked">FundOperatorRevoked</h4> <p>Emitted when a given player has been revoked initiate funding requests.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>walletToFund</td><td>The wallet that the player is allowed to start funding requests</td></tr> <tr><td>orderer</td><td>The address that allows the player to start requests.</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>This standards provides a functionality to allow token holders to start funding requests in a decentralized way.</p> <p>It's important to highlight that the token operator, need to process all funding request, updating the fund status based on the linked payment that will be done.</p> <p>Funding instruction format is open. ISO payment standard like is a good start point,</p> <p>The <code>operationId</code> is a string and not something more gas efficient to allow easy traceability of the hold and allow human readable ids. It is up to the implementer if the string should be stored on-chain or only its hash, as it is enough to identify a hold.</p> <p>The <code>operationId</code> is a competitive resource. It is recommended, but not required, that the hold issuers used a unique prefix to avoid collisions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible as its implementation extends the functionality of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>.</p> <h2 id="implementation">Implementation</h2> <p>The GitHub repository <a rel="external" href="https://github.com/IoBuilders/fundable-token">IoBuilders/fundable-token</a> contains the work in progress implementation.</p> <h2 id="contributors">Contributors</h2> <p>This proposal has been collaboratively implemented by <a rel="external" href="https://adhara.io/">adhara.io</a> and <a rel="external" href="https://io.builders/">io.builders</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Julio Faurajulio@adhara.io Fernando Parisfer@io.builders Daniel Lehrnerdaniel@io.builders https://wg-eips.ritovision.com/2020/ <h2 id="simple-summary">Simple Summary</h2> <p>The E-Money Standard Token aims to enable the issuance of regulated electronic money on blockchain networks, and its practical usage in real financial applications.</p> <h2 id="actors">Actors</h2> <h4 id="operator">Operator</h4> <p>An account, which has been approved by an account to perform an action on the behalf of another account.</p> <h2 id="abstract">Abstract</h2> <p>Financial institutions work today with electronic systems, which hold account balances in databases on core banking systems. In order for an institution to be allowed to maintain records of client balances segregated and available for clients, such institution must be regulated under a known legal framework and must possess a license to do so. Maintaining a license under regulatory supervision entails ensuring compliance (i.e. performing KYC on all clients and ensuring good AML practices before allowing transactions) and demonstrating technical and operational solvency through periodic audits, so clients depositing funds with the institution can rest assured that their money is safe.</p> <h2 id="motivation">Motivation</h2> <p>There are only a number of potential regulatory license frameworks that allow institutions to issue and hold money balances for customers (be it retail corporate or institutional types). The most important and practical ones are three:</p> <ul> <li><strong>Electronic money entities</strong>: these are legally regulated vehicles that are mostly used today for cash and payments services, instead of more complex financial services. For example prepaid cards or online payment systems such as PayPal run on such schemes. In most jurisdictions, electronic money balances are required to be 100% backed by assets, which often entails holding cash on an omnibus account at a bank with 100% of the funds issued to clients in the electronic money ledger.</li> <li><strong>Banking licenses</strong>: these include commercial and investment banks, which segregate client funds using current and other type of accounts implemented on core banking systems. Banks can create money by lending to clients, so bank money can be backed by promises to pay and other illiquid assets.</li> <li><strong>Central banks</strong>: central banks hold balances for banks in RTGS systems, similar to core banking systems but with much more restricted yet critical functionality. Central banks create money by lending it to banks, which pledge their assets to central banks as a lender of last resort for an official interest rate.</li> </ul> <p>Regulations for all these types of electronic money are local, i.e. only valid for each jurisdiction and not valid in others. Regulations can vary as well dramatically in different jurisdictions — for example there are places with no electronic money frameworks, on everything has to be done through banking licenses or directly with a central bank. But in all cases compliance with existing regulation needs to ensured, in particular:</p> <ul> <li><strong>Know Your Customer (KYC)</strong>: the institution needs to identify the client before providing them with the possibility of depositing money or transact. In different jurisdictions and for different types of licenses there are different levels of balance and activity that can be allowed for different levels of KYC. For example, low KYC requirements with little checks or even no checks at all can usually be acceptable in many jurisdictions if cashin balances are kept low (i.e. hundreds of dollars)</li> <li><strong>Anti Money Laundering (AML)</strong>: the institution needs to perform checks of parties transacting with its clients, typically checking against black lists and doing sanction screening, most notably in the context of international transactions</li> </ul> <p>Beyond cash, financial instruments such as equities or bonds are also registered in electronic systems in most cases, although all these systems and the bank accounting systems are only connected through rudimentary messaging means, which leads to the need for reconciliations and manual management in many cases. Cash systems to provide settlement of transactions in the capital markets are not well-connected to the transactional systems, and often entail delays and settlement risk.</p> <p>The E-Money Standard Token builds on Ethereum standards currently in use such as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, but it extends them to provide few key additional pieces of functionality, needed in the regulated financial world:</p> <ul> <li><strong>Compliance</strong>: E-Money Standard Token implements a set of methods to check in advance whether user-initiated transactions can be done from a compliance point of view. Implementations must <code>require</code> that these methods return a positive answer before executing the transaction.</li> <li><strong>Clearing</strong>: In addition to the standard <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> <code>transfer</code> method, E-Money Standard Token provides a way to submit transfers that need to be cleared by the token issuing authority off-chain. These transfers are then executed in two steps: <ol> <li>transfers are ordered</li> <li>after clearing them, transfers are executed or rejected by the operator of the token contract</li> </ol> </li> <li><strong>Holds</strong>: token balances can be put on hold, which will make the held amount unavailable for further use until the hold is resolved (i.e. either executed or released). Holds have a payer, a payee, and a notary who is in charge of resolving the hold. Holds also implement expiration periods, after which anyone can release the hold Holds are similar to escrows in that are firm and lead to final settlement. Holds can also be used to implement collateralization.</li> <li><strong>Funding requests</strong>: users can request for a wallet to be funded by calling the smart contract and attaching a debit instruction string. The tokenizer reads this request, interprets the debit instructions, and triggers a transfer in the bank ledger to initiate the tokenization process.</li> <li><strong>Payouts</strong>: users can request payouts by calling the smart contract and attaching a payment instruction string. The (de)tokenizer reads this request, interprets the payment instructions, and triggers the transfer of funds (typically from the omnibus account) into the destination account, if possible. Note that a redemption request is a special type of payout in which the destination (bank) account for the payout is the bank account linked to the token wallet.</li> </ul> <p>The E-Money Standard Token is thus different from other tokens commonly referred to as "stable coins" in that it is designed to be issued, burnt and made available to users in a compliant manner (i.e. with full KYC and AML compliance) through a licensed vehicle (an electronic money entity, a bank, or a central bank), and in that it provides the additional functionality described above, so it can be used by other smart contracts implementing more complex financial applications such as interbank payments, supply chain finance instruments, or the creation of E-Money Standard Token denominated bonds and equities with automatic delivery-vs-payment.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EMoneyToken</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC-1996, ERC-2018, ERC-2019, ERC-2021 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> currency</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> version</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> availableFunds</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkTransferAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkApproveAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkHoldAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> notary</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkAuthorizeHoldOperatorAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkOrderTransferAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkAuthorizeClearableTransferOperatorAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkOrderFundAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkAuthorizeFundOperatorAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkOrderPayoutAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkAuthorizePayoutOperatorAllowed</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="mandatory-checks">Mandatory checks</h3> <p>The checks must be verified in their corresponding actions. The action must only be successful if the check return an <code>Allowed</code> status code. In any other case the functions must revert.</p> <h3 id="status-codes">Status codes</h3> <p>If an action is allowed <code>0x11</code> (Allowed), or an issuer-specific code with equivalent but more precise meaning must be returned. If the action is not allowed the status must be <code>0x10</code> (Disallowed), or an issuer-specific code with equivalent but more precise meaning.</p> <h3 id="functions">Functions</h3> <h4 id="currency">currency</h4> <p>Returns the currency that backs the token. The value must be a code defined in <a rel="external" href="https://en.wikipedia.org/wiki/ISO_4217">ISO 4217</a>.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>-</td><td>-</td></tr> </tbody></table> <h4 id="version">version</h4> <p>Returns the current version of the smart contract. The format of the version is up to the implementer of the EIP.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>-</td><td>-</td></tr> </tbody></table> <h4 id="availablefunds">availableFunds</h4> <p>Returns the total net funds of an account. Taking into consideration the outright balance and the held balances.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>account</td><td>The account which available funds should be returned</td></tr> </tbody></table> <h4 id="checktransferallowed">checkTransferAllowed</h4> <p>Checks if the <code>transfer</code> or <code>transferFrom</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be transferred if executed</td></tr> <tr><td>value</td><td>The amount to be transferred</td></tr> </tbody></table> <h4 id="checkapproveallowed">checkApproveAllowed</h4> <p>Checks if the <code>approve</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>spender</td><td>The address of the spender, which potentially can initiate transfers on behalf of <code>from</code></td></tr> <tr><td>value</td><td>The maximum amount to be transferred</td></tr> </tbody></table> <h4 id="checkholdallowed">checkHoldAllowed</h4> <p>Checks if the <code>hold</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be transferred if executed</td></tr> <tr><td>notary</td><td>The address of the notary who is going to determine whether the hold is to be executed or released</td></tr> <tr><td>value</td><td>The amount to be transferred. Must be less or equal than the balance of the payer</td></tr> </tbody></table> <h4 id="checkauthorizeholdoperatorallowed">checkAuthorizeHoldOperatorAllowed</h4> <p>Checks if the <code>checkAuthorizeHoldOperatorAllowed</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be approved as operator of clearable transfers</td></tr> <tr><td>from</td><td>The address on which behalf holds could potentially be issued</td></tr> </tbody></table> <h4 id="checkordertransferallowed">checkOrderTransferAllowed</h4> <p>Checks if the <code>orderTransfer</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be paid if executed</td></tr> <tr><td>value</td><td>The amount to be transferred. Must be less or equal than the balance of the payer</td></tr> </tbody></table> <h4 id="checkauthorizeclearabletransferoperatorallowed">checkAuthorizeClearableTransferOperatorAllowed</h4> <p>Checks if the <code>authorizeClearableTransferOperator</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be approved as operator of clearable transfers</td></tr> <tr><td>from</td><td>The address on which behalf clearable transfers could potentially be ordered</td></tr> </tbody></table> <h4 id="checkorderfundallowed">checkOrderFundAllowed</h4> <p>Checks if the <code>orderFund</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>to</td><td>The address to which the tokens are to be given if executed</td></tr> <tr><td>operator</td><td>The address of the requester, which initiates the funding order</td></tr> <tr><td>value</td><td>The amount to be funded</td></tr> </tbody></table> <h4 id="checkauthorizefundoperatorallowed">checkAuthorizeFundOperatorAllowed</h4> <p>Checks if the <code>authorizeFundOperator</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be approved as operator of ordering funding</td></tr> <tr><td>to</td><td>The address which the tokens are to be given if executed</td></tr> </tbody></table> <h4 id="checkorderpayoutallowed">checkOrderPayoutAllowed</h4> <p>Checks if the <code>orderPayout</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>from</td><td>The address from whom the tokens are to be taken if executed</td></tr> <tr><td>operator</td><td>The address of the requester, which initiates the payout request</td></tr> <tr><td>value</td><td>The amount to be paid out</td></tr> </tbody></table> <h4 id="checkauthorizepayoutoperatorallowed">checkAuthorizePayoutOperatorAllowed</h4> <p>Checks if the <code>authorizePayoutOperator</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be approved as operator of ordering payouts</td></tr> <tr><td>from</td><td>The address from which the tokens are to be taken if executed</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>This EIP unifies <a href="https://wg-eips.ritovision.com/1996/">ERC-1996</a>, <a href="https://wg-eips.ritovision.com/2018/">ERC-2018</a>, <a href="https://wg-eips.ritovision.com/2019/">ERC-2019</a> and <a href="https://wg-eips.ritovision.com/2021/">ERC-2021</a> and adds the checks for the compliance on top of it. By this way the separate EIPs are otherwise independent of each other, and the E-Money Standard Token offers a solution for all necessary functionality of regulated electronic money.</p> <p>While not requiring it, the naming of the check functions was adopted from <a href="https://wg-eips.ritovision.com/1462/">ERC-1462</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible as its implementation extends the functionality of <a href="https://wg-eips.ritovision.com/1996/">ERC-1996</a>, <a href="https://wg-eips.ritovision.com/2018/">ERC-2018</a>, <a href="https://wg-eips.ritovision.com/2019/">ERC-2019</a>, <a href="https://wg-eips.ritovision.com/2021/">ERC-2021</a> and <a href="https://wg-eips.ritovision.com/1066/">ERC-1066</a>.</p> <h2 id="implementation">Implementation</h2> <p>The GitHub repository <a rel="external" href="https://github.com/IoBuilders/em-token">IoBuilders/em-token</a> contains the work in progress implementation.</p> <h2 id="contributors">Contributors</h2> <p>This proposal has been collaboratively implemented by <a rel="external" href="https://adhara.io/">adhara.io</a> and <a rel="external" href="https://io.builders/">io.builders</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Fernando Parisfer@io.builders Julio Faurajulio@adhara.io Daniel Lehrnerdaniel@io.builders https://wg-eips.ritovision.com/2021/ <h2 id="simple-summary">Simple Summary</h2> <p>An extension to the <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> standard token that allows Token wallet owners to request payout from their wallet, by calling the smart contract and attaching a payout instruction string.</p> <h2 id="actors">Actors</h2> <h4 id="token-wallet-owners">Token Wallet Owners</h4> <p>The person or company who owns the wallet, and will order payout.</p> <h4 id="token-contract-owner-agent">Token contract owner / agent</h4> <p>The entity, company responsible/owner of the token contract, and token issuing/minting. This actor is in charge of trying to fulfill all payout request(s), reading the payout instruction(s), and correlate the payout details.</p> <h4 id="orderer">Orderer</h4> <p>An actor who is enabled to initiate payout orders on behalf of a token wallet owner.</p> <h2 id="abstract">Abstract</h2> <p>Token wallet owners (or approved addresses) can order payout requests through blockchain. This is done by calling the <code>orderPayoutFrom</code> or <code>orderPayoutFrom</code> methods, which initiate the workflow for the token contract operator to either honor or reject the payout request. In this case, payout instructions are provided when submitting the request, which are used by the operator to determine the destination of the funds.</p> <p>In general, it is not advisable to place explicit routing instructions for the payouts on a verbatim basis on the blockchain, and it is advised to use a private communication alternatives, such as private channels, encrypted storage or similar, to do so (external to the blockchain ledger). Another (less desirable) possibility is to place these instructions on the instructions field in encrypted form.</p> <h2 id="motivation">Motivation</h2> <p>Nowadays most of the token payout requests, need a previous centralized transaction, to be able to define the payout destination to be able to execute the payout (burn transaction). In the aim of trying to bring all the needed steps into decentralization, exposing all the needed steps of token lifecycle and payment transactions, a payout request can allow wallet owner to initiate the payout order via blockchain. Key benefits:</p> <ul> <li>Payout, burning traceability is enhanced bringing the initiation into the ledger. All payment, payout statuses can be stored on chain.</li> <li>Almost all money/token lifecycle is covered via a decentralized approach, complemented with private communications which is common use in the ecosystem.</li> </ul> <p>In this case, the following movement of tokens are done as the process progresses:</p> <ul> <li>Upon launch of the payout request, the appropriate amount of funds are placed on a hold with a predefined notary defined by the platform, and the payout is placed into a <code>Ordered</code> state</li> <li>The operator then can put the payout request <code>InProcess</code>, which prevents the <em>orderer</em> of the payout from being able to cancel the payout request</li> <li>After checking the payout is actually possible the operator then executes the hold, which moves the funds to a suspense wallet and places the payout into the <code>FundsInSuspense</code> state</li> <li>The operator then moves the funds offchain (usually from the omnibus account) to the appropriate destination account, then burning the tokens from the suspense wallet and rendering the payout into the <code>Executed</code> state</li> <li>Either before or after placing the request <code>InProcess</code>, the operator can also reject the payout, which returns the funds to the payer and eliminates the hold. The resulting end state of the payout is <code>Rejected</code></li> <li>When the payout is <code>Ordered</code> and before the operator places it into the <code>InProcess</code> state, the orderer of the payout can also cancel it, which frees up the hold and puts the payout into the final <code>Cancelled</code> state</li> </ul> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IPayoutable</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC-20 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> PayoutStatusCode</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Nonexistent</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Ordered</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> InProcess</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> FundsInSuspense</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Executed</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Rejected</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Cancelled</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizePayoutOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> orderer</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokePayoutOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> orderer</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> orderPayout</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> instructions</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> orderPayoutFrom</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> walletToBePaidOut</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> instructions</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelPayout</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> processPayout</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> putFundsInSuspenseInPayout</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executePayout</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> rejectPayout</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> reason</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isPayoutOperatorFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> walletToDebit</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> orderer</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> retrievePayoutData</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> walletToDebit</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> instructions</span><span>,</span><span class="z-storage z-type"> PayoutStatusCode</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PayoutOrdered</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> walletToDebit</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>, </span><span class="z-support">string</span><span class="z-variable"> instructions</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PayoutInProcess</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PayoutFundsInSuspense</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PayoutExecuted</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PayoutRejected</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> reason</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PayoutCancelled</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PayoutOperatorAuthorized</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> walletToBePaidOut</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> PayoutOperatorRevoked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> walletToBePaidOut</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="functions">Functions</h3> <h4 id="authorizepayoutoperator">authorizePayoutOperator</h4> <p>Wallet owner, allows a given address to be payout orderer.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer.</td></tr> </tbody></table> <h4 id="revokepayoutoperator">revokePayoutOperator</h4> <p>Wallet owner, Revokes a given address to be payout orderer.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer.</td></tr> </tbody></table> <h4 id="orderpayout">orderPayout</h4> <p>Creates a payout request, that will be processed by the token operator. The function must revert if the operation ID has been used before.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request</td></tr> <tr><td>value</td><td>The amount to be paid out.</td></tr> <tr><td>instruction</td><td>A string including the payment instruction.</td></tr> </tbody></table> <h4 id="orderpayoutfrom">orderPayoutFrom</h4> <p>Creates a payout request, on behalf of a wallet owner, that will be processed by the token operator. The function must revert if the operation ID has been used before.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request</td></tr> <tr><td>walletToBePaidOut</td><td>The wallet to be paid out on behalf.</td></tr> <tr><td>value</td><td>The amount to be paid out.</td></tr> <tr><td>instruction</td><td>A string including the payment instruction.</td></tr> </tbody></table> <h4 id="cancelpayout">cancelPayout</h4> <p>Cancels a payout request.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request that is going to be cancelled. This can only be done by token holder, or the payout initiator/orderer.</td></tr> <tr><td>reason</td><td>The specific reason that explains why the payout request was rejected. <a href="https://wg-eips.ritovision.com/1066/">EIP-1066</a> codes can be used.</td></tr> </tbody></table> <h4 id="processpayout">processPayout</h4> <p>Marks a payout request as on process. After the status is on process, order cannot be cancelled.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify that the request is in process.</td></tr> </tbody></table> <h4 id="putfundsinsuspenseinpayout">putFundsInSuspenseInPayout</h4> <p>Put a given payout in suspense. Can only be done if it is in process.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify that the request is in process.</td></tr> </tbody></table> <h4 id="executepayout">executePayout</h4> <p>Burn the amount of tokens and marks a payout request as executed.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request that has been executed.</td></tr> </tbody></table> <h4 id="rejectpayout">rejectPayout</h4> <p>Rejects a given operation with a reason.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request that has been executed.</td></tr> <tr><td>reason</td><td>The specific reason that explains why the payout request was rejected. <a href="https://wg-eips.ritovision.com/1066/">EIP-1066</a> codes can be used</td></tr> </tbody></table> <h4 id="isapprovedtoorderpayout">isApprovedToOrderPayout</h4> <p>Checks that given player is allowed to order payout requests, for a given wallet.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>walletToBePaidOut</td><td>The wallet to be paid out, and checked for approval permission.</td></tr> <tr><td>orderer</td><td>The address of the orderer, to be checked for approval permission.</td></tr> </tbody></table> <h4 id="retrievepayoutdata">retrievePayoutData</h4> <p>Retrieves all the payout request data. Only operator, tokenHolder, and orderer can get the given operation data.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer, to correlate the right data.</td></tr> <tr><td>operationId</td><td>The unique ID to identify the payout order.</td></tr> </tbody></table> <h3 id="events">Events</h3> <h4 id="payout-ordered">Payout Ordered</h4> <p>Emitted when an token wallet owner orders a payout request.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the request</td></tr> <tr><td>walletToBePaidOut</td><td>The wallet that is requested to be paid out</td></tr> <tr><td>value</td><td>The amount to be funded.</td></tr> <tr><td>instruction</td><td>A string including the payment instruction.</td></tr> </tbody></table> <h4 id="payoutfundsinsuspense">PayoutFundsInSuspense</h4> <p>Emitted when an operator puts fund in suspense.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the payout request orderer.</td></tr> <tr><td>operationId</td><td>The unique ID to identify the payout.</td></tr> </tbody></table> <h4 id="payoutinprocess">PayoutInProcess</h4> <p>Emitted when an operator accepts a payout request, and the operation is in process.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the payout request orderer.</td></tr> <tr><td>operationId</td><td>The unique ID to identify the payout.</td></tr> </tbody></table> <h4 id="payoutexecuted">PayoutExecuted</h4> <p>Emitted when an operator has executed a payout request.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the payout request orderer.</td></tr> <tr><td>operationId</td><td>The unique ID to identify the payout.</td></tr> </tbody></table> <h4 id="payoutrejected">PayoutRejected</h4> <p>Emitted when an operator has rejected a payout request.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the payout request orderer.</td></tr> <tr><td>operationId</td><td>The unique ID to identify the payout.</td></tr> <tr><td>reason</td><td>The specific reason that explains why the payout request was rejected. <a href="https://wg-eips.ritovision.com/1066/">EIP-1066</a> codes can be used</td></tr> </tbody></table> <h4 id="payoutcancelled">PayoutCancelled</h4> <p>Emitted when a token holder, orderer, has cancelled a payout request. This can only be done if the operator hasn't put the payout order in process.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the payout request orderer.</td></tr> <tr><td>operationId</td><td>The unique ID per payout issuer to identify the payout.</td></tr> </tbody></table> <h4 id="payoutoperatorauthorized">PayoutOperatorAuthorized</h4> <p>Emitted when a given player, operator, company or a given persona, has been approved to start payout request for a given token holder.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>walletToBePaidOut</td><td>The wallet that the player is allowed to start payout requests</td></tr> <tr><td>orderer</td><td>The address that allows the player to start requests.</td></tr> </tbody></table> <h4 id="payoutoperatorrevoked">PayoutOperatorRevoked</h4> <p>Emitted when a given player has been revoked initiate payout requests.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>walletToBePaidOut</td><td>The wallet that the player is allowed to start payout requests</td></tr> <tr><td>orderer</td><td>The address that allows the player to start requests.</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>This standards provides a functionality to allow token holders to start payout requests in a decentralized way.</p> <p>It's important to highlight that the token operator, need to process all payout request, updating the payout status based on the linked payment that will be done.</p> <p>Payout instruction format is open. ISO payment standard like is a good start point.</p> <p>This EIP uses <a href="https://wg-eips.ritovision.com/1996/">EIP-1996</a> to hold the money after a payout is ordered. The token contract owner or agent, whose implementation is not part of this proposal, acts as a predefined notary to decide if the payout is executed or not.</p> <p>The <code>operationId</code> is a string and not something more gas efficient to allow easy traceability of the hold and allow human readable ids. It is up to the implementer if the string should be stored on-chain or only its hash, as it is enough to identify a hold.</p> <p>The <code>operationId</code> is a competitive resource. It is recommended, but not required, that the hold issuers used a unique prefix to avoid collisions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible as its implementation extends the functionality of <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> and [ERC-1996].</p> <h2 id="implementation">Implementation</h2> <p>The GitHub repository <a rel="external" href="https://github.com/IoBuilders/payoutable-token">IoBuilders/payoutable-token</a> contains the reference implementation.</p> <h2 id="contributors">Contributors</h2> <p>This proposal has been collaboratively implemented by <a rel="external" href="https://adhara.io/">adhara.io</a> and <a rel="external" href="https://io.builders/">io.builders</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-09T00:00:00+00:00 2026-02-11T14:49:27+00:00 Paweł Bylicahttps://github.com/chfast Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/2003/ <h2 id="abstract">Abstract</h2> <p><a rel="external" href="https://github.com/ethereum/evmc">EVMC</a> specifies a generic API for Ethereum execution engines. This EIP specifies a way of providing implementations of Ethereum precompiled contracts using the <a rel="external" href="https://ethereum.github.io/evmc/vmguide.html">EVMC VM API</a>.</p> <h2 id="specification">Specification</h2> <p>For the complete <a rel="external" href="https://github.com/ethereum/evmc">EVMC</a> specification visit the <a rel="external" href="https://ethereum.github.io/evmc/">EVMC documentation</a> first. This EIP is based on and is compatible with EVMC ABI version 6.</p> <p>The EVMC module with implementations of precompiled contracts SHOULD:</p> <ol> <li> <p>Advertise the <a rel="external" href="https://ethereum.github.io/evmc/group__EVMC.html#gga44f9ecb88cf6422a0072936494fd6ac7a43ea2aa7b099a2d67bc53c118ff3683d"><code>EVMC_CAPABILITY_PRECOMPILES</code></a> capability in the <a rel="external" href="https://ethereum.github.io/evmc/structevmc__instance.html#ae63b9ca898aa41cbd1e2fe86ca8f4e1c"><code>get_capabilities()</code></a> method.</p> </li> <li> <p>Implement the <a rel="external" href="https://ethereum.github.io/evmc/structevmc__instance.html#a0823ebff21f9b0395b157e8c6b14a207"><code>execute()</code></a> method in the following way:</p> <ol> <li> <p>Validate the incoming execution request requirements:</p> <ol> <li> <p>The message kind (<a rel="external" href="https://ethereum.github.io/evmc/structevmc__message.html#a691cb93e81d6dfd4fd7e2fa3d06a6bfa"><code>evmc_message::kind</code></a>) is a call (<a rel="external" href="https://ethereum.github.io/evmc/group__EVMC.html#ggab2fa68a92a6828064a61e46060abc634abcf3ae29d9a88ff70b98374fc665694a"><code>EVMC_CALL</code></a>).</p> </li> <li> <p>The call destination address (<a rel="external" href="https://ethereum.github.io/evmc/structevmc__message.html#a88ecfaa03a85a31c6da36fa043b98cea"><code>evmc_message::destination</code></a>) is within the range of precompiled contracts defined by <a href="https://wg-eips.ritovision.com/1352/">EIP-1352</a>.</p> </li> <li> <p>There is no code provided (the <code>code</code> argument is <code>NULL</code> and <code>code_size</code> argument is <code>0</code>).</p> </li> </ol> <p>If the requirements are not fulfilled, abort execution with the <a rel="external" href="https://ethereum.github.io/evmc/group__EVMC.html#gga4c0be97f333c050ff45321fcaa34d920a2f3e0d8777f8d974ead27ae2a6eb2005"><code>EVMC_REJECTED</code></a> status code.</p> </li> <li> <p>Check if the call destination address (<a rel="external" href="https://ethereum.github.io/evmc/structevmc__message.html#a88ecfaa03a85a31c6da36fa043b98cea"><code>evmc_message::destination</code></a>) targets existing precompiled contract. Consider the EVM revision (<a rel="external" href="https://ethereum.github.io/evmc/group__EVMC.html#gae5759b1590071966ccf6a505b52a0ef7"><code>evmc_revision</code></a>) requested by the <code>rev</code> parameter of <a rel="external" href="https://ethereum.github.io/evmc/structevmc__instance.html#a0823ebff21f9b0395b157e8c6b14a207"><code>execute()</code></a>.</p> <p>If yes, execute as follows:</p> <ol> <li> <p>Inspect the input data (<a rel="external" href="https://ethereum.github.io/evmc/structevmc__message.html#a1adee3454b105eb29cd659ee0cf65c77"><code>evmc_message::input_data</code></a>, <a rel="external" href="https://ethereum.github.io/evmc/structevmc__message.html#a2cf1deebd0dbbb20f25ecdfa299f4b5d"><code>evmc_message::input_size</code></a>) and calculate the <em>gas cost</em> of the execution.</p> </li> <li> <p>Compute the amount of <em>gas left</em> after execution by subtracting the <em>gas cost</em> from the call gas limit (<a rel="external" href="https://ethereum.github.io/evmc/structevmc__message.html#ae8deff46588584fa27890e74c82db5e7"><code>evmc_message::gas</code></a>).</p> </li> <li> <p>If <em>gas left</em> is negative, abort execution with the <a rel="external" href="https://ethereum.github.io/evmc/group__EVMC.html#gga4c0be97f333c050ff45321fcaa34d920abfc47f75656c996c0b29c0553c00fc18"><code>EVMC_OUT_OF_GAS</code></a> status code.</p> </li> <li> <p>Otherwise, execute the code of the precompiled contract, return the <a rel="external" href="https://ethereum.github.io/evmc/group__EVMC.html#gga4c0be97f333c050ff45321fcaa34d920a4bc3069fec2bab2a55355a72b7db68b7"><code>EVMC_SUCCESS</code></a> status code, the output and <em>gas left</em> (<a rel="external" href="https://ethereum.github.io/evmc/structevmc__result.html#a61978e85f9d795a7b9695b9cbf1748d6"><code>evmc_result::output_data</code></a>, <a rel="external" href="https://ethereum.github.io/evmc/structevmc__result.html#a93bb7419aff492cdef754421c6d74e26"><code>evmc_result::output_size</code></a>, <a rel="external" href="https://ethereum.github.io/evmc/structevmc__result.html#af8478c93dbcc3cb2876037c5a5afd4c0"><code>evmc_result::gas_left</code></a>).</p> </li> </ol> </li> <li> <p>Otherwise, emulate execution of empty code by returning the <a rel="external" href="https://ethereum.github.io/evmc/group__EVMC.html#gga4c0be97f333c050ff45321fcaa34d920a4bc3069fec2bab2a55355a72b7db68b7"><code>EVMC_SUCCESS</code></a> status code and <em>gas left</em> equal the call gas limit (<a rel="external" href="https://ethereum.github.io/evmc/structevmc__message.html#ae8deff46588584fa27890e74c82db5e7"><code>evmc_message::gas</code></a>).</p> </li> </ol> </li> </ol> <p>Precompiled contract implementations are allowed to return two more EVMC error codes:</p> <ul> <li><a rel="external" href="https://ethereum.github.io/evmc/group__EVMC.html#gga4c0be97f333c050ff45321fcaa34d920aed5b2a4afa5a47af732569445920a4a9"><code>EVMC_FAILURE</code></a> if the failure was caused due to something other than out of gas (e.g. input validation error)</li> <li><a rel="external" href="https://ethereum.github.io/evmc/group__EVMC.html#gga4c0be97f333c050ff45321fcaa34d920aed708e84d49cc1270e54ec20b0ca0a05"><code>EVMC_REVERT</code></a> if the precompile doesn't want to forfeit all supplied gas (as of May 2019 no such precompile exists)</li> </ul> <p>The Client is not required to provide the Host interface ([<code>evmc_context</code>] argument of <a rel="external" href="https://ethereum.github.io/evmc/structevmc__instance.html#a0823ebff21f9b0395b157e8c6b14a207"><code>execute()</code></a> is set to NULL). Therefore, the precompiled contracts implementation MUST NOT access the <code>evmc_context</code>.</p> <h2 id="rationale">Rationale</h2> <p>It is very unlikely that any precompile will need to access or modify a contract state. Not requiring the Client to implement the EVMC Host interface removes the big portion of work needed for full EVMC integration.</p> <h2 id="test-cases">Test Cases</h2> <p>EVMC provides the <a rel="external" href="https://evmc.ethereum.org/vmtester.html">evmc-vmtester</a> tool for checking compatibility with the EVMC specification.</p> <h2 id="implementations">Implementations</h2> <ul> <li><a rel="external" href="https://github.com/ethereum/evmc/blob/master/examples/example_precompiles_vm/example_precompiles_vm.cpp">Example of Precompiles VM implementation</a></li> <li><a rel="external" href="https://github.com/ewasm/ewasm-precompiles">ewasm precompiles</a></li> <li>Aleth code for precompiles</li> <li>Parity code for precompiles</li> <li><a rel="external" href="https://github.com/axic/eip1962-evmc">EIP-1962 implemented as an EVMC precompile module</a></li> </ul> <h2 id="references">References</h2> <ul> <li><a rel="external" href="https://github.com/ethereum/evmc">EVMC – Ethereum Client-VM Connector API</a></li> <li><a rel="external" href="https://ethereum.github.io/evmc/">EVMC documentation</a></li> <li><a rel="external" href="https://ethereum.github.io/evmc/vmguide.html">EVMC VM Implementation Guide</a></li> <li><a href="https://wg-eips.ritovision.com/1352/">EIP 1352: Specify restricted address range for precompiles/system contracts</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-05-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Daniel Lehrnerdaniel@io.builders https://wg-eips.ritovision.com/2009/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP proposes a service for decentralized compliance checks for regulated tokens.</p> <h2 id="actors">Actors</h2> <h4 id="operator">Operator</h4> <p>An account which has been approved by a token to update the tokens accumulated.</p> <h4 id="token">Token</h4> <p>An account, normally a smart contract, which uses the <code>Compliance Service</code> to check if the an action can be executed or not.</p> <h4 id="token-holder">Token holder</h4> <p>An account which is in possession of tokens and on for which the checks are made.</p> <h2 id="abstract">Abstract</h2> <p>A regulated token needs to comply with several legal requirements, especially <a rel="external" href="https://en.wikipedia.org/wiki/Know_your_customer">KYC</a> and <a rel="external" href="https://en.wikipedia.org/wiki/Money_laundering#Anti-money_laundering">AML</a>. If the necessary checks have to be made off-chain the token transfer becomes centralized. Further the transfer in this case takes longer to complete as it can not be done in one transaction, but requires a second confirmation step. The goal of this proposal is to make this second step unnecessary by providing a service for compliance checks.</p> <h2 id="motivation">Motivation</h2> <p>Currently there is no proposal on how to accomplish decentralized compliance checks. <a href="https://wg-eips.ritovision.com/1462/">ERC-1462</a> proposes a basic set of functions to check if <code>transfer</code>, <code>mint</code> and <code>burn</code> are allowed for a user, but not how those checks should be implemented. This EIP proposes a way to implement them fully on-chain while being generic enough to leave the actual implementation of the checks up to the implementers, as these may vary a lot between different tokens.</p> <p>The proposed <code>Compliance Service</code> supports more than one token. Therefore it could be used by law-makers to maintain the compliance rules of regulated tokens in one smart contract. This smart contract could be used by all of the tokens that fall under this jurisdiction and ensure compliance with the current laws.</p> <p>By having a standard for compliance checks third-party developers can use them to verify if token movements for a specific account are allowed and act accordingly.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> CompliantService</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkTransferAllowed</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkTransferFromAllowed</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkMintAllowed</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkBurnAllowed</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateTransferAccumulated</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateMintAccumulated</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateBurnAccumulated</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addToken</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> token</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> replaceToken</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> token</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeToken</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isToken</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTokenId</span><span>(</span><span class="z-support">address</span><span class="z-variable"> token</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizeAccumulatedOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeAccumulatedOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isAccumulatedOperatorFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenAdded</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> token</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenReplaced</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> previousAddress</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TokenRemoved</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AuthorizedAccumulatedOperator</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RevokedAccumulatedOperator</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="mandatory-checks">Mandatory checks</h3> <p>The checks must be verified in their corresponding actions. The action must only be successful if the check return an <code>Allowed</code> status code. In any other case the functions must revert.</p> <h3 id="status-codes">Status codes</h3> <p>If an action is allowed <code>0x11</code> (Allowed) or an issuer-specific code with equivalent but more precise meaning must be returned. If the action is not allowed the status must be <code>0x10</code> (Disallowed) or an issuer-specific code with equivalent but more precise meaning.</p> <h3 id="functions">Functions</h3> <h4 id="checktransferallowed">checkTransferAllowed</h4> <p>Checks if the <code>transfer</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be transferred if executed</td></tr> <tr><td>value</td><td>The amount to be transferred</td></tr> </tbody></table> <h4 id="checktransferfromallowed">checkTransferFromAllowed</h4> <p>Checks if the <code>transferFrom</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>sender</td><td>The address of the sender, who initiated the transaction</td></tr> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be transferred if executed</td></tr> <tr><td>value</td><td>The amount to be transferred</td></tr> </tbody></table> <h4 id="checkmintallowed">checkMintAllowed</h4> <p>Checks if the <code>mint</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be given if executed</td></tr> <tr><td>value</td><td>The amount to be minted</td></tr> </tbody></table> <h4 id="checkburnallowed">checkBurnAllowed</h4> <p>Checks if the <code>burn</code> function is allowed to be executed with the given parameters.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>value</td><td>The amount to be burned</td></tr> </tbody></table> <h4 id="updatetransferaccumulated">updateTransferAccumulated</h4> <p>Must be called in the same transaction as <code>transfer</code> or <code>transferFrom</code>. It must revert if the update violates any of the compliance rules. It is up to the implementer which specific logic is executed in the function.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be transferred if executed</td></tr> <tr><td>value</td><td>The amount to be transferred</td></tr> </tbody></table> <h4 id="updatemintaccumulated">updateMintAccumulated</h4> <p>Must be called in the same transaction as <code>mint</code>. It must revert if the update violates any of the compliance rules. It is up to the implementer which specific logic is executed in the function.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be given if executed</td></tr> <tr><td>value</td><td>The amount to be minted</td></tr> </tbody></table> <h4 id="updateburnaccumulated">updateBurnAccumulated</h4> <p>Must be called in the same transaction as <code>burn</code>. It must revert if the update violates any of the compliance rules. It is up to the implementer which specific logic is executed in the function.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>value</td><td>The amount to be minted</td></tr> </tbody></table> <h4 id="addtoken">addToken</h4> <p>Adds a token to the service, which allows the token to call the functions to update the accumulated. If an existing token id is used the function must revert. It is up to the implementer if adding a token should be restricted or not.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>token</td><td>The address from which the update functions will be called</td></tr> </tbody></table> <h4 id="replacetoken">replaceToken</h4> <p>Replaces the address of a added token with another one. It is up to the implementer if replacing a token should be restricted or not, but a token should be able to replace its own address.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>token</td><td>The address from which the update functions will be called</td></tr> </tbody></table> <h4 id="removetoken">removeToken</h4> <p>Removes a token from the service, which disallows the token to call the functions to update the accumulated. It is up to the implementer if removing a token should be restricted or not.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> </tbody></table> <h4 id="istoken">isToken</h4> <p>Returns <code>true</code> if the address has been added to the service, <code>false</code> if not.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>token</td><td>The address which should be checked</td></tr> </tbody></table> <h4 id="gettokenid">getTokenId</h4> <p>Returns the token id of a token. If the token has not been added to the service, '0' must be returned.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>token</td><td>The address which token id should be returned</td></tr> </tbody></table> <h4 id="authorizeaccumulatedoperator">authorizeAccumulatedOperator</h4> <p>Approves an operator to update accumulated on behalf of the token id of msg.sender.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be approved as operator of accumulated updates</td></tr> </tbody></table> <h4 id="revokeaccumulatedoperator">revokeAccumulatedOperator</h4> <p>Revokes the approval to update accumulated on behalf the token id the token id ofof msg.sender.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be revoked as operator of accumulated updates</td></tr> </tbody></table> <h4 id="isaccumulatedoperatorfor">isAccumulatedOperatorFor</h4> <p>Retrieves if an operator is approved to create holds on behalf of <code>tokenId</code>.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address which is operator of updating the accumulated</td></tr> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> </tbody></table> <h3 id="events">Events</h3> <h4 id="tokenadded">TokenAdded</h4> <p>Must be emitted after a token has been added.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>token</td><td>The address from which the update functions will be called</td></tr> </tbody></table> <h4 id="tokenreplaced">TokenReplaced</h4> <p>Must be emitted after the address of a token has been replaced.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> <tr><td>previousAddress</td><td>The previous address which was used before</td></tr> <tr><td>newAddress</td><td>The address which will be used from now on</td></tr> </tbody></table> <h4 id="tokenremoved">TokenRemoved</h4> <p>Must be emitted after the a token has been removed.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>tokenId</td><td>The unique ID which identifies a token</td></tr> </tbody></table> <h4 id="authorizedaccumulatedoperator">AuthorizedAccumulatedOperator</h4> <p>Emitted when an operator has been approved to update the accumulated on behalf of a token.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address which is operator of updating the accumulated</td></tr> <tr><td>tokenId</td><td>Token id on which behalf updates of the accumulated will potentially be made</td></tr> </tbody></table> <h4 id="revokedholdoperator">RevokedHoldOperator</h4> <p>Emitted when an operator has been revoked from updating the accumulated on behalf of a token.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address which was operator of updating the accumulated</td></tr> <tr><td>tokenId</td><td>Token id on which behalf updates of the accumulated could be made</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>The usage of a token id instead of the address has been chosen to give tokens the possibility to update their smart contracts and keeping all their associated accumulated. If the address would be used, a migration process would needed to be done after a smart contract update.</p> <p>No event is emitted after updating the accumulated as those are always associated with a <code>transfer</code>, <code>mint</code> or <code>burn</code> of a token which already emits an event of itself.</p> <p>While not requiring it, the naming of the functions <code>checkTransferAllowed</code>, <code>checkTransferFromAllowed</code>, <code>checkMintAllowed</code> and <code>checkBurnAllowed</code> was adopted from <a href="https://wg-eips.ritovision.com/1462/">ERC-1462</a>.</p> <p>While not requiring it, the naming of the functions <code>authorizeAccumulatedOperator</code>, <code>revokeAccumulatedOperator</code> and <code>isAccumulatedOperatorFor</code> follows the naming convention of <a href="https://wg-eips.ritovision.com/777/">ERC-777</a>.</p> <p>Localization is not part of this EIP, but <a href="https://wg-eips.ritovision.com/1066/">ERC-1066</a> and <a href="https://wg-eips.ritovision.com/1444/">ERC-1444</a> can be used together to achieve it.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As the EIP is not using any existing EIP there are no backwards compatibilities to take into consideration.</p> <h2 id="implementation">Implementation</h2> <p>The GitHub repository <a rel="external" href="https://github.com/IoBuilders/compliance-service">IoBuilders/compliance-service</a> contains the work in progress implementation.</p> <h2 id="contributors">Contributors</h2> <p>This proposal has been collaboratively implemented by <a rel="external" href="https://adhara.io/">adhara.io</a> and <a rel="external" href="https://io.builders/">io.builders</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-04-30T00:00:00+00:00 2026-02-11T14:48:25+00:00 Julio Faurajulio@adhara.io Fernando Parisfer@io.builders Daniel Lehrnerdaniel@io.builders https://wg-eips.ritovision.com/2018/ <h2 id="simple-summary">Simple Summary</h2> <blockquote> <p>"In banking and finance, clearing denotes all activities from the time a commitment is made for a transaction until it is settled." <a rel="external" href="https://en.wikipedia.org/wiki/Clearing_(finance)">[1]</a></p> </blockquote> <h2 id="actors">Actors</h2> <h4 id="clearing-agent">Clearing Agent</h4> <p>An account which processes, executes or rejects a clearable transfer.</p> <h4 id="operator">Operator</h4> <p>An account which has been approved by an account to order clearable transfers on its behalf.</p> <h4 id="orderer">Orderer</h4> <p>The account which orders a clearable transfer. This can be the account owner itself, or any account, which has been approved as an operator for the account.</p> <h2 id="abstract">Abstract</h2> <p>The clearing process turns the promise of a transfer into the actual movement of money from one account to another. A clearing agent decides if the transfer can be executed or not. The amount which should be transferred is not deducted from the balance of the payer, but neither is it available for another transfer and therefore ensures, that the execution of the transfer will be successful when it is executed.</p> <h2 id="motivation">Motivation</h2> <p>A regulated token needs to comply with all the legal requirements, especially <a rel="external" href="https://en.wikipedia.org/wiki/Know_your_customer">KYC</a> and <a rel="external" href="https://en.wikipedia.org/wiki/Money_laundering#Anti-money_laundering">AML</a>. Some of these checks may not be able to be done on-chain and therefore a transfer may not be completed in one step. Currently there is no EIP to make such off-chain checks possible. This proposal allows a user to order a transfer, which can be checked by a clearing agent off-chain. Depending on the result of it, the clearing agent will either execute or cancel the transfer. To provide more information why a transfer is cancelled, the clearing agent can add a reason why it is not executed.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ClearableToken</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC-1996 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> ClearableTransferStatusCode</span><span> {</span><span class="z-variable z-other z-enummember"> Nonexistent</span><span>,</span><span class="z-variable z-other z-enummember"> Ordered</span><span>,</span><span class="z-variable z-other z-enummember"> InProcess</span><span>,</span><span class="z-variable z-other z-enummember"> Executed</span><span>,</span><span class="z-variable z-other z-enummember"> Rejected</span><span>,</span><span class="z-variable z-other z-enummember"> Cancelled</span><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> orderTransfer</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> orderTransferFrom</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> cancelTransfer</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> processClearableTransfer</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeClearableTransfer</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> rejectClearableTransfer</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> reason</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> retrieveClearableTransferData</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-storage z-type"> ClearableTransferStatusCode</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizeClearableTransferOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeClearableTransferOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isClearableTransferOperatorFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ClearableTransferOrdered</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> operationId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ClearableTransferInProcess</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ClearableTransferExecuted</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ClearableTransferRejected</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> operationId</span><span>, </span><span class="z-support">string</span><span class="z-variable"> reason</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ClearableTransferCancelled</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> orderer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> operationId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AuthorizedClearableTransferOperator</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> account</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RevokedClearableTransferOperator</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> account</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="functions">Functions</h3> <h4 id="ordertransfer">orderTransfer</h4> <p>Orders a clearable transfer on behalf of the msg.sender in favor of <code>to</code>. A clearing agent is responsible to either execute or reject the transfer. The function must revert if the operation ID has been used before.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be paid if executed</td></tr> <tr><td>value</td><td>The amount to be transferred. Must be less or equal than the balance of the payer.</td></tr> </tbody></table> <h4 id="ordertransferfrom">orderTransferFrom</h4> <p>Orders a clearable transfer on behalf of the payer in favor of the <code>to</code>. A clearing agent is responsible to either execute or reject the transfer. The function must revert if the operation ID has been used before.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be paid if executed</td></tr> <tr><td>value</td><td>The amount to be transferred. Must be less or equal than the balance of the payer.</td></tr> </tbody></table> <h4 id="canceltransfer">cancelTransfer</h4> <p>Cancels the order of a clearable transfer. Only the orderer can cancel their own orders. It must not be successful as soon as the transfer is in status <code>InProcess</code>.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> </tbody></table> <h4 id="processclearabletransfer">processClearableTransfer</h4> <p>Sets a clearable transfer to status <code>InProcess</code>. Only a clearing agent can successfully execute this action. This status is optional, but without it the orderer can cancel the transfer at any time.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> </tbody></table> <h4 id="executeclearabletransfer">executeClearableTransfer</h4> <p>Executes a clearable transfer, which means that the tokens are transferred from the payer to the payee. Only a clearing agent can successfully execute this action.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> </tbody></table> <h4 id="rejectclearabletransfer">rejectClearableTransfer</h4> <p>Rejects a clearable transfer, which means that the amount that is held is available again to the payer and no transfer is done. Only a clearing agent can successfully execute this action.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> <tr><td>reason</td><td>A reason given by the clearing agent why the transfer has been rejected</td></tr> </tbody></table> <h4 id="retrieveclearabletransferdata">retrieveClearableTransferData</h4> <p>Retrieves all the information available for a particular clearable transfer.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> </tbody></table> <h4 id="authorizeclearabletransferoperator">authorizeClearableTransferOperator</h4> <p>Approves an operator to order transfers on behalf of msg.sender.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be approved as operator of clearable transfers</td></tr> </tbody></table> <h4 id="revokeclearabletransferoperator">revokeClearableTransferOperator</h4> <p>Revokes the approval to order transfers on behalf of msg.sender.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be revoked as operator of clearable transfers</td></tr> </tbody></table> <h4 id="isclearabletransferoperatorfor">isClearableTransferOperatorFor</h4> <p>Returns if an operator is approved to order transfers on behalf of <code>from</code>.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be an operator of clearable transfers</td></tr> <tr><td>from</td><td>The address on which the holds would be created</td></tr> </tbody></table> <h4 id="transfer">transfer</h4> <p>It is up to the implementer of the EIP if the <code>transfer</code> function of ERC-20 should always revert or is allowed under certain circumstances.</p> <h4 id="transferfrom">transferFrom</h4> <p>It is up to the implementer of the EIP if the <code>transferFrom</code> function of ERC-20 should always revert or is allowed under certain circumstances.</p> <h3 id="events">Events</h3> <h4 id="clearabletransferordered">ClearableTransferOrdered</h4> <p>Must be emitted when a clearable transfer is ordered.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer of the transfer</td></tr> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be paid if executed</td></tr> <tr><td>value</td><td>The amount to be transferred if executed</td></tr> </tbody></table> <h4 id="clearabletransferinprocess">ClearableTransferInProcess</h4> <p>Must be emitted when a clearable transfer is put in status <code>ÌnProcess</code>.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer of the transfer</td></tr> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> </tbody></table> <h4 id="clearabletransferexecuted">ClearableTransferExecuted</h4> <p>Must be emitted when a clearable transfer is executed.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer of the transfer</td></tr> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> </tbody></table> <h4 id="clearabletransferrejected">ClearableTransferRejected</h4> <p>Must be emitted when a clearable transfer is rejected.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer of the transfer</td></tr> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> <tr><td>reason</td><td>A reason given by the clearing agent why the transfer has been rejected</td></tr> </tbody></table> <h4 id="clearabletransfercancelled">ClearableTransferCancelled</h4> <p>Must be emitted when a clearable transfer is cancelled by its orderer.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>orderer</td><td>The address of the orderer of the transfer</td></tr> <tr><td>operationId</td><td>The unique ID to identify the clearable transfer</td></tr> </tbody></table> <h4 id="authorizedclearabletransferoperator">AuthorizedClearableTransferOperator</h4> <p>Emitted when an operator has been approved to order transfers on behalf of another account.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address which has been approved as operator of clearable transfers</td></tr> <tr><td>account</td><td>Address on which behalf transfers will potentially be ordered</td></tr> </tbody></table> <h4 id="revokedclearabletransferoperator">RevokedClearableTransferOperator</h4> <p>Emitted when an operator has been revoked from ordering transfers on behalf of another account.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address which has been revoked as operator of clearable transfers</td></tr> <tr><td>account</td><td>Address on which behalf transfers could potentially be ordered</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>This EIP uses <a href="https://wg-eips.ritovision.com/1996/">EIP-1996</a> to hold the money after a transfer is ordered. A clearing agent, whose implementation is not part of this proposal, acts as a predefined notary to decide if the transfer complies with the rules of the token or not.</p> <p>The <code>operationId</code> is a string and not something more gas efficient to allow easy traceability of the hold and allow human readable ids. It is up to the implementer if the string should be stored on-chain or only its hash, as it is enough to identify a hold.</p> <p>The <code>operationId</code> is a competitive resource. It is recommended, but not required, that the hold issuers used a unique prefix to avoid collisions.</p> <p>While not requiring it, the naming of the functions <code>authorizeClearableTransferOperator</code>, <code>revokeClearableTransferOperator</code> and <code>isClearableTransferOperatorFor</code> follows the naming convention of <a href="https://wg-eips.ritovision.com/777/">ERC-777</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible as its implementation extends the functionality of <a href="https://wg-eips.ritovision.com/1996/">EIP-1996</a>.</p> <h2 id="implementation">Implementation</h2> <p>The GitHub repository <a rel="external" href="https://github.com/IoBuilders/clearable-token">IoBuilders/clearable-token</a> contains the reference implementation.</p> <h2 id="contributors">Contributors</h2> <p>This proposal has been collaboratively implemented by <a rel="external" href="https://adhara.io/">adhara.io</a> and <a rel="external" href="https://io.builders/">io.builders</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> <p>[1] https://en.wikipedia.org/wiki/Clearing_(finance)</p> 2019-04-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Vlasovhttps://github.com/shamatar https://wg-eips.ritovision.com/1962/ <h1 id="simple-summary">Simple summary</h1> <p>This proposal is an extension and formalization of <a href="https://wg-eips.ritovision.com/1829/">EIP-1829</a> with an inclusion of pairings. <a href="https://wg-eips.ritovision.com/1109/">EIP-1109</a> is required due to low cost of some operations compared to the <code>STATICCALL</code> opcode (more information in the corresponding section below).</p> <h2 id="abstract">Abstract</h2> <p>This EIP proposes a new precompile to bring cryptographic functionality desired for privacy and scaling solutions. Functionality of such precompile will require the following:</p> <ul> <li>Implementation the following operations over elliptic curves in the Weierstrass form with curve parameters such as base field, A, B coefficients defined in runtime: <ul> <li>Point addition</li> <li>Multiplication of a single point over a scalar</li> <li>Multiexponentiation</li> </ul> </li> <li>Implementation pairing operation over elliptic curves from the following "families" with parameters such as base field, extension tower structure, coefficients defined in runtime: <ul> <li>BLS12</li> <li>BN</li> <li>MNT4/6 (Ate pairing)</li> </ul> </li> </ul> <p>Full functionality of the precompile is described below in <code>Specification</code> section.</p> <h2 id="motivation">Motivation</h2> <ul> <li>There is a pending proposal to implement base elliptic curve arithmetic is covered by <a href="https://wg-eips.ritovision.com/1829/">EIP-1829</a> and will allow to implement various privacy-preserving protocols with a reasonable gas costs per operation.</li> <li>Pairings are an important extension for basic arithmetic and so this new precompile is proposed with the following benefits: <ul> <li>Extended set of curves will be available to allow Ethereum users to choose their security parameters and required functionality.</li> <li>Generic approach of this precompile will allow Ethereum users to experiment with newly found curves of their choice and new constructions constructions without waiting for new forks.</li> <li>EC arithmetic is indeed re-implemented in this precompile, but it's strictly required. Most of the pairing-based protocols still need to perform standard EC multiplications or additions and thus such operations must be available on generic set of curves.</li> </ul> </li> <li>Gas costs - this EIP is designed to estimate gas-cost of performed operation as early as possible during the call and base if solely on specified parameters and operation type. This is a strict requirement for any precompile to allow Ethereum nodes to efficiently reject transactions and operations as early as possible.</li> </ul> <p>Functionality of this newly proposed precompile is different from <a href="https://wg-eips.ritovision.com/1829/">EIP-1829</a> in the following aspects:</p> <ul> <li>Operation on arbitrary-length modulus (up to some upper-limit) for a base field and scalar field of the curve</li> <li>Pairing operations are introduced</li> <li>Different ABI due to variable parameter length</li> </ul> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= XXXXX</code>, define a set of <code>10</code> new precompiles with an addresses <code>[0x.., 0x.., ...]</code> and the following functionality.</p> <ul> <li>Addition of points on the curve defined over base field</li> <li>Multiplication of a point on the curve defined over base field</li> <li>Multiexponentiation for <code>N</code> pairs of <code>(scalar, point)</code> on the curve defined over base field</li> <li>Addition of points on the curve defined over quadratic or cubic extension of the base field</li> <li>Multiplication of a point on the curve defined over quadratic or cubic extension of the base field</li> <li>Multiexponentiation for <code>N</code> pairs of <code>(scalar, point)</code> on the curve defined over quadratic or cubic extension of the base field</li> <li>Pairing operation on the curve of <code>BLS12</code> family</li> <li>Pairing operation on the curve of <code>BN</code> family</li> <li>Pairing operation on the curve of <code>MNT4</code> family</li> <li>Pairing operation on the curve of <code>MNT6</code> family</li> </ul> <p>Due to actuve development of the precompile and a lot of ongoing changes there is a single <a rel="external" href="https://github.com/matter-labs/eip1962/tree/master/documentation">source of truth</a>. It covers binary interface, gas schedule, integration guide for existing implementations.</p> <h3 id="possible-simplifications">Possible simplifications</h3> <p>Due to high complexity of the proposed operations in the aspects of implementation, debugging and evaluation of the factors for gas costs it may be appropriate to either limit the set of curves at the moment of acceptance to some list and then extend it. Another approach (if it's technically possible) would be to have the "whilelist" contract that can be updated without consensus changes (w/o fork).</p> <p>In the case of limited set of curve the following set is proposed as a minimal:</p> <ul> <li>BN254 curve from the current version of Ethereum</li> <li>BN curve from DIZK with 2^32 roots of unity</li> <li>BLS12-381</li> <li>BLS12-377 from ZEXE with large number of roots of unity</li> <li>MNT4/6 cycle from the original <a rel="external" href="https://eprint.iacr.org/2014/595.pdf">paper</a>. It's not too secure, but may give some freedom for experiments.</li> <li>MNT4/6 cycle from Coda if performance allows</li> <li>Set of CP generated curves that would allow embedding of BLS12-377 and may be some BN curve that would have large power of two divisor for both base field and scalar field modulus (example of CP curve for BLS12-377 can be found in ZEXE).</li> </ul> <h2 id="rationale">Rationale</h2> <p>Only the largest design decisions will be covered:</p> <ul> <li>While there is no arithmetic over the scalar field (which is modulo size of the main group) of the curve, it's required for gas estimation purposes.</li> <li>Multiexponentiation is a separate operation due to large cost saving</li> <li>There are no point decompressions due to impossibility to get universal gas estimation of square root operation. For a limited number of "good" cases prices would be too different, so specifying the "worst case" is expensive and inefficient, while introduction of another level if complexity into already complicated gas costs formula is not worth is.</li> </ul> <h3 id="this-precompile-and-eip-1109">This precompile and EIP 1109</h3> <p>While there is no strict requirement of EIP 1109 for functionality, here is an example why it would be desired:</p> <ul> <li>BLS12-381 curve, 381 bit modulus, 255 bit scalar field, no native arithmetic is available in EVM for this</li> <li>Point addition would take 5000ns (quite overestimated)</li> <li>Point multiplication would take roughly 150000ns</li> <li>Crude gas schedule 15 Mgas/second from ECRecover precompile</li> <li>Point addition would cost 75 gas, with <code>STATICCALL</code> adding another 700</li> <li>Point multiplication would cost 2250 gas</li> <li>One should also add the cost of memory allocation that is at least <code>1 + 1 + 48 + 48 + 48 + 1 + 32 + 2*48 + 2*48 = 371 byte</code> that is around 12 native Ethereum "words" and will require extra 36 gas (with negligible price for memory extension)</li> </ul> <p>Based on these quite crude estimations one can see that <code>STATICCALL</code> price will dominate the total cost (in case of addition) or bring significant overhead (in case of multiplication operation) in case of calls to this precompile.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change is not backwards compatible and requires hard fork to be activated.</p> <p>Functionality of the new precompile itself does not affect any existing functionality of Ethereum or EVM.</p> <p>This precompile may serve as a complete replacement of the current set of <code>ECADD</code>, <code>ECMUL</code> and pairing check precompiles (<code>0x06</code>, <code>0x07</code>, <code>0x08</code>)</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are the part of the implementation with a link below.</p> <h2 id="implementation">Implementation</h2> <p>There is an ongoing implementation effort <a rel="external" href="https://github.com/matter-labs/eip1829">here</a>. Right now:</p> <ul> <li>Non-pairing operations are implemented and tested.</li> <li>BLS12 family is completed and tested for BLS12-381 and BLS12-377 curves.</li> <li>BN family is completed and tested with BN254 curve.</li> <li>Cocks-Pinch method curve is tested for k=6 curve from ZEXE.</li> </ul> <h2 id="preliminary-benchmarks">Preliminary benchmarks</h2> <p>cp6 in benchmarks is a Cocks-Pinch method curve that embeds BLS12-377. Machine: Core i7, 2.9 GHz.</p> <p>Multiexponentiation benchmarks take 100 pairs <code>(generator, random scalar)</code> as input. Due to the same "base" it may be not too representative benchmark and will be updated.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>test pairings::bls12::tests::bench_bls12_381_pairing ... bench: 2,348,317 ns/iter (+/- 605,340)</span></span> <span class="giallo-l"><span>test pairings::cp::tests::bench_cp6_pairing ... bench: 86,328,825 ns/iter (+/- 11,802,073)</span></span> <span class="giallo-l"><span>test tests::bench_addition_bn254 ... bench: 388 ns/iter (+/- 73)</span></span> <span class="giallo-l"><span>test tests::bench_doubling_bn254 ... bench: 187 ns/iter (+/- 4)</span></span> <span class="giallo-l"><span>test tests::bench_field_inverse ... bench: 2,478 ns/iter (+/- 167)</span></span> <span class="giallo-l"><span>test tests::bench_field_mont_inverse ... bench: 2,356 ns/iter (+/- 51)</span></span> <span class="giallo-l"><span>test tests::bench_multiplication_bn254 ... bench: 81,744 ns/iter (+/- 6,984)</span></span> <span class="giallo-l"><span>test tests::bench_multiplication_bn254_into_affine ... bench: 81,925 ns/iter (+/- 3,323)</span></span> <span class="giallo-l"><span>test tests::bench_multiplication_bn254_into_affine_wnaf ... bench: 74,716 ns/iter (+/- 4,076)</span></span> <span class="giallo-l"><span>test tests::bench_naive_multiexp_bn254 ... bench: 10,659,911 ns/iter (+/- 559,790)</span></span> <span class="giallo-l"><span>test tests::bench_peppinger_bn254 ... bench: 2,678,743 ns/iter (+/- 148,914)</span></span> <span class="giallo-l"><span>test tests::bench_wnaf_multiexp_bn254 ... bench: 9,161,281 ns/iter (+/- 456,137)</span></span></code></pre><h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-04-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ronan Sandfordhttps://github.com/wighawag https://wg-eips.ritovision.com/1959/ <h2 id="simple-summary">Simple Summary</h2> <p>To protect off-chain messages from being reused across different chain, a mechanism need to be given to smart contract to only accept messages for that chain. Since a chain can change its chainID, the mechanism should consider old chainID valid.</p> <h2 id="abstract">Abstract</h2> <p>This EIP adds an opcode that returns whether the specific number passed in has been a valid chainID (EIP-155 unique identifier) in the history of the chain (including the current chainID).</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/155/">EIP-155</a> proposes to use the chain ID to prevent replay attacks between different chains. It would be a great benefit to have the same possibility inside smart contracts when handling signatures, especially for Layer 2 signature schemes using <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>.</p> <p><a href="https://wg-eips.ritovision.com/1344/">EIP-1344</a> is attempting to solve this by giving smart contract access to the tip of the chainID history. This is insufficient as such value is changing. Hence why EIP-1344 describes a contract based solution to work around the problem. It would be better to solve it in a simpler, cheaper and safer manner, removing the potential risk of misuse present in EIP-1344.</p> <h2 id="specification">Specification</h2> <p>Adds a new opcode <code>VALID_CHAINID</code> at 0x46, which uses 1 stack argument : a 32 bytes value that represent the chainID to test. It will push <code>0x1</code> onto the stack if the uint256 value is part of the history (since genesis) of chainIDs of that chain, <code>0x0</code> otherwise.</p> <p>The operation costs <code>G_blockhash</code> to execute.</p> <p>The cost of the operation might need to be adjusted later as the number of chainID in the history of the chain grows.</p> <p>Note though that the alternative to keep track of old chainID is to implement a smart contract based caching solution as EIP-1344 proposes comes with an overall higher gas cost. As such the gas cost is simply a necessary cost for the feature.</p> <h2 id="rationale">Rationale</h2> <p>The only approach available today is to specify the chain ID at compile time. Using this approach will result in problems after a contentious hardfork as the contract can't accept message signed with a new chainID.</p> <p>The approach proposed by EIP-1344 is to give access to the latest chainID. This is in itself not sufficient and pose the opposite of the problem mentioned above since as soon as a hardfork that change the chainID happens, every L2 messages signed as per <a href="https://wg-eips.ritovision.com/712/">EIP-712</a> (with the previous chainID) will fails to be accepted by the contracts after the fork.</p> <p>That's why in the rationale of EIP-1344 it is mentioned that users need to implement/use a mechanism to verify the validity of past chainID via a trustless cache implemented via smart contract.</p> <p>While this works (except for a temporary gap where the immediately previous chainID is not considered valid), this is actually a required procedure for all contracts that want to accept L2 messages since without it, messages signed before a hardfork that updated the chainID would be rejected. In other words, EIP-1344 expose such risk and it is easy for contract to not consider it by simply checking <code>chainID == CHAIN_ID()</code> without considering past chainIDs.</p> <p>Indeed letting contracts access the latest chainID for L2 message verification is dangerous. The latest chainID is only the tip of the chainID history. As a changing value, the latest chainID is thus not appropriate to ensure the validity of L2 messages.</p> <p>Users signing off-chain messages expect their messages to be valid from the time of signing and do not expect these message to be affected by a future hardfork. If the contract use the latest chainID as is for verification, the messages would be invalid as soon as a hardfork that update the chainID happens. For some applications, this will require users to resubmit a new message (think meta transaction), causing them potential loss (or some inconvenience during the hardfork transition), but for some other applications (think state channel) the whole off-chain state become inaccessible, resulting in potentially disastrous situations.</p> <p>In other words, we should consider all off-chain messages (with valid chainID) as part of the chain's offchain state. The opcode proposed here, offer smart contracts a simple and safe method to ensure that the offchain state stay valid across fork.</p> <p>As for replay protection, the idea of considering all of the off-chain messages signed with valid chainID as part of the chain's offchain-state means that all of these off-chain messages can be reused on the different forks which share a common chainID history (up to where they differ). This is actually an important feature since as mentioned, users expect their signed messages to be valid from the time of signing. From that time onwards these messages should be considered as part of the chain's offchain state. A hardfork should not thus render them invalid. This is similar to how the previous on-chain state is shared between 2 hardforks.</p> <p>The wallets will make sure that at any time, a signing message request use the latest chainID of the chain being used. This prevent replay attack onto chain that have different chainID histories (they would not have the same latest chainID).</p> <p>Now it is argued in the <a rel="external" href="https://ethereum-magicians.org/t/eip-1344-add-chain-id-opcode/1131">EIP1344 discussion</a> that when a contentious hardfork happen and one side of the fork decide to not update its chainID, that side of the chain would be vulnerable to replays since users will keep signing with a chainID that is also valid in the chain that forked. An issue also present in EIP-1344.</p> <p>This is simply a natural consequence of using chainID as the only anti-replay information for L2 messages. But this can indeed be an issue if the hardfork is created by a small minority. In that case if the majority ignore the fork and do not update its chainID, then all new message from the majority chain (until they update their chainID) can be replayed on the minority-led hardfork since the majority's current chainID is also part of the minority-led fork's chainID history.</p> <p>To fix this, every message could specify the block number representing the time it was signed. The contract could then verify that chainID specified as part of that message was valid at that particular block.</p> <p>While EIP-1344 can't do that accurately as the caching system might leave a gap, this proposal can solve it if it is modified to return the blockNumber at which a chainID become invalid. Unfortunately, this would be easy for contracts to not perform that check. And since it suffice of only one important applications to not follow this procedure to put the minority-led fork at a disadvantage, this would fail to achieve the desired goal of protecting the minority-led fork from replay.</p> <p>Since a minority-led fork ignored by the majority means that the majority will not keep track of the messages to be submitted (state channel, ...), if such fork get traction later, this would be at the expense of majority users who were not aware of it. As such this proposal assume that minority-led fork will not get traction later and thus do not require to be protected.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>TBD</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible with all chains which implement EIP-155 chain ID domain separator for transaction signing. Existing contract are not affected.</p> <p>Similarly to EIP-1344, it might be beneficial to update EIP-712 (still in Draft) to deal with chainID separately from the domain separator. Indeed since chainID is expected to change, if the domain separator include chainID, it would have to be dynamically computed. A caching mechanism could be used by smart contract instead though.</p> <h2 id="references">References</h2> <p>This was previously suggested as part of <a rel="external" href="https://ethereum-magicians.org/t/eip-1344-add-chain-id-opcode/1131/39">EIP-1344 discussion</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-04-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ronan Sandfordhttps://github.com/wighawag https://wg-eips.ritovision.com/1965/ <h2 id="abstract">Abstract</h2> <p>This EIP adds a precompile that returns whether a specific chainID (EIP-155 unique identifier) is valid at a specific blockNumber. ChainID are assumed to be valid up to the blockNumber at which they get replaced by a new chainID.</p> <h2 id="motivation">Motivation</h2> <p><a href="https://wg-eips.ritovision.com/155/">EIP-155</a> proposes to use the chain ID to prevent the replay of transactions between different chains. It would be a great benefit to have the same possibility inside smart contracts when handling off-chain message signatures, especially for Layer 2 signature schemes using <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>.</p> <p><a href="https://wg-eips.ritovision.com/1344/">EIP-1344</a> is attempting to solve this by giving smart contract access to the tip of the chainID history. This is insufficient as such value is changing. Hence why EIP-1344 describes a contract based solution to work around the problem. It would be better to solve it in a simpler, cheaper and safer manner, removing the potential risk of misuse present in EIP-1344. Furthermore EIP-1344 can't protect replay properly for minority-led hardfork as the caching system cannot guarantee accuracy of the blockNumber at which the new chainID has been introduced.</p> <p><a href="https://wg-eips.ritovision.com/1959/">EIP-1959</a> solves the issue of EIP-1344 but does not attempt to protect from minority-led hardfork as mentioned in the rationale. We consider this a mistake, since it removes some freedom to fork. We consider that all fork should be given equal opportunities. And while there will always be issues we can't solve for the majority that ignore a particular fork, <strong>users that decide to use both the minority-fork and the majority-chain should be protected from replay without having to wait for the majority chain to update its chainID.</strong></p> <h2 id="specification">Specification</h2> <p>Adds a new precompile which uses 2 arguments : a 32 bytes value that represents the chainID to test and a 32 bytes value representing the blockNumber at which the chainID is tested. It returns 0x1 if the chainID is valid at the specific blockNumber, 0x0 otherwise. Note that chainID are considered valid up to the blockNumber at which they are replaced. So they are valid for every blockNumber past their replacement.</p> <p>The operation will costs no more than <code>G_blockhash</code> + <code>G_verylow</code> to execute. This could be lower as chainID are only introduced during hardfork.</p> <p>The cost of the operation might need to be adjusted later as the number of chainID in the history of the chain grows.</p> <p>Note though that the alternative to keep track of old chainID is to implement a smart contract based caching solution as EIP-1344 proposes comes with an overall higher gas cost and exhibit issues for minority-led hardfork (see Rationale section below). As such the gas cost is simply a necessary cost for the feature.</p> <h2 id="rationale">Rationale</h2> <p>The rationale at EIP-1959 applies here as well too :</p> <ul> <li>An opcode is better than a caching system for past chainID, It is cheaper, safer and does not include gaps.</li> <li>Direct access to the latest chainID is dangerous since it makes it easy for contracts to use it as a replay protection mechanism while preventing otherwise valid old messages to be valid after a fork that changes the chainID. This can have disastrous consequences on users.</li> <li>all off-chain messages signed before a fork should be valid across all side of the fork.</li> </ul> <p>The only difference is that this current proposal proposes a solution to protect hardfork led by a minority.</p> <p>To summarize there is 2 possible fork scenario :</p> <ol> <li> <p>The majority decide to make a hardfork but a minority disagree with it (ETC is such example). The fork is planned for block X. If the majority is not taking any action to automate the process of assigning a different chainID for both, the minority has plenty of time to plan for a chainID upgrade to happen at that same block X. Now if they do not do it, their users will face the problem that their messages will be replayable on the majority chain (Note that this is not true the other way around as we assume the majority decided to change the chainID). As such there is no reason that they will leave it that way.</p> </li> <li> <p>A minority decide to create a hardfork that the majority disagree with (or simply ignore). Now, the same as above can happen but since we are talking about a minority there is a chance that the majority does not care about the minority. In that case, there would be no incentive for the majority to upgrade the chainID. This means that users of both sides of the fork will have the messages meant for the majority chain replayable on the minority-chain (even if this one changed its chainID) unless extra precaution is taken.</p> </li> </ol> <p>The solution is to add the blockNumber representing the time at which the message was signed and use it as an argument to the opcode proposed here. This way, when the minority forks with a new chainID, the previous chainID become invalid from that time onward. So new messages destined to the majority chain can't be replayed on the minority fork.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>EIP-712 is still in draft but would need to be updated to include the blockNumber as part of the values that wallets need to verify for the protection of their users.</p> <p>Since chainID and blockNumber will vary, they should not be part of the domain separator (meant to be generated once) but another part of the message.</p> <p>While the pair could be optional for contract that do not care about replays or have other ways to prevent them, if chainID is present, the blockNumber must be present too. And if any of them is present, wallet need to ensure that the chainID is indeed the latest one of the chain being used, while the blockNumber is the latest one at the point of signing. During fork transition, the wallet can use the blockNumber to know which chainID to use.</p> <h2 id="references">References</h2> <p>This was previously suggested as part of <a rel="external" href="https://ethereum-magicians.org/t/eip-1959-valid-chainid-opcode/3170">EIP1959 discussion</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-04-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Johann Barbiehttps://github.com/johannbarbie Ben Bollenben@ost.com pinkiebellhttps://github.com/pinkiebell https://wg-eips.ritovision.com/1948/ <h2 id="simple-summary">Simple Summary</h2> <p>Some NFT use-cases require to have dynamic data associated with a non-fungible token that can change during its lifetime. Examples for dynamic data:</p> <ul> <li>cryptokitties that can change color</li> <li>intellectual property tokens that encode rights holders</li> <li>tokens that store data to transport them across chains</li> </ul> <p>The existing metadata standard does not suffice as data can only be set at minting time and not modified later.</p> <h2 id="abstract">Abstract</h2> <p>Non-fungible tokens (NFTs) are extended with the ability to store dynamic data. A 32 bytes data field is added and a read function allows to access it. The write function allows to update it, if the caller is the owner of the token. An event is emitted every time the data updates and the previous and new value is emitted in it.</p> <h2 id="motivation">Motivation</h2> <p>The proposal is made to standardize on tokens with dynamic data. Interactions with bridges for side-chains like xDAI or Plasma chains will profit from the ability to use such tokens. Protocols that build on data tokens like <a rel="external" href="https://ethresear.ch/t/a-distributed-breeding-function/5264">distributed breeding</a> will be enabled.</p> <h2 id="specification">Specification</h2> <p>An extension of <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> interface with the following functions and events is suggested:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.2</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Interface of the ERC1948 contract.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC1948</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Emitted when `oldData` is replaced with `newData` in storage of `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-keyword">Note</span><span class="z-comment"> that `oldData` or `newData` may be empty bytes.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> DataUpdated</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> tokenId</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> oldData</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> newData</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Reads the data of a specified token. Returns the current data in</span></span> <span class="giallo-l"><span class="z-comment"> * storage of `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The token to read the data off.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> bytes32 representing the current data stored in the token.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> readData</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Updates the data of a specified token. Writes `newData` into storage</span></span> <span class="giallo-l"><span class="z-comment"> * of `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> tokenId</span><span class="z-comment"> The token to write data to.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> newData</span><span class="z-comment"> The data to be written to the token.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Emits a `DataUpdated` event.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> writeData</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> newData</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The suggested data field in the NFT is used either for storing data directly, like a counter or address. If more data is required the implementer should fall back to authenticated data structures, like merkle- or patricia-trees.</p> <p>The proposal for this ERC stems from the <a rel="external" href="https://ethresear.ch/t/a-distributed-breeding-function/5264">distributed breeding proposal</a> to allow better integration of NFTs across side-chains. <a rel="external" href="https://ost.com/">ost.com</a>, <a rel="external" href="https://skalelabs.com/">Skale</a>, <a rel="external" href="https://poa.network/">POA</a>, and <a rel="external" href="https://leapdao.org/">LeapDAO</a> have been part of the discussion.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>🤷‍♂️ No related proposals are known to the author, hence no backwards compatibility to consider.</p> <h2 id="test-cases">Test Cases</h2> <p>Simple happy test:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> ERC1948</span><span class="z-keyword"> =</span><span class="z-variable z-other"> artifacts</span><span>.</span><span class="z-entity z-name">require</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">./ERC1948.sol</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">contract</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">ERC1948</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> (</span><span class="z-variable">accounts</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> firstTokenId</span><span class="z-keyword"> =</span><span class="z-constant"> 100</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> empty</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> data</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x0101010101010101010101010101010101010101010101010101010101010101</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> dataToken</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> beforeEach</span><span>(</span><span class="z-storage">async</span><span> (</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> dataToken</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other z-constant"> ERC1948</span><span>.</span><span class="z-entity z-name">new</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> dataToken</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span class="z-variable z-other">accounts</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other"> firstTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> it</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">should allow to write and read</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-storage"> async</span><span> (</span><span>)</span><span class="z-storage z-type"> =&gt;</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> rsp</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> dataToken</span><span>.</span><span class="z-entity z-name">readData</span><span>(</span><span class="z-variable z-other">firstTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> assert</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">rsp</span><span>,</span><span class="z-variable z-other"> empty</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> await</span><span class="z-variable z-other"> dataToken</span><span>.</span><span class="z-entity z-name">writeData</span><span>(</span><span class="z-variable z-other">firstTokenId</span><span>,</span><span class="z-variable z-other"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> rsp</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> dataToken</span><span>.</span><span class="z-entity z-name">readData</span><span>(</span><span class="z-variable z-other">firstTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> assert</span><span>.</span><span class="z-entity z-name">equal</span><span>(</span><span class="z-variable z-other">rsp</span><span>,</span><span class="z-variable z-other"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span><span>)</span><span>;</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>An example implementation of the interface in solidity would look like this:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Implementation of ERC721 token and the `IERC1948` interface.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * ERC1948 is a non-fungible token (NFT) extended with the ability to store</span></span> <span class="giallo-l"><span class="z-comment"> * dynamic data. The data is a bytes32 field for each tokenId. If 32 bytes</span></span> <span class="giallo-l"><span class="z-comment"> * do not suffice to store the data, an authenticated data structure (hash or</span></span> <span class="giallo-l"><span class="z-comment"> * merkle tree) shall be used.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC1948</span><span class="z-storage"> is</span><span class="z-entity z-name"> IERC1948</span><span>, </span><span class="z-entity z-name">ERC721</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bytes32</span><span>)</span><span> data</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See `IERC1948.readData`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `tokenId` needs to exist.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> readData</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">_exists</span><span>(</span><span>tokenId</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> data</span><span>[</span><span>tokenId</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See `IERC1948.writeData`.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Requirements:</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * - `msg.sender` needs to be owner of `tokenId`.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> writeData</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokenId</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> newData</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span class="z-entity z-name"> ownerOf</span><span>(</span><span>tokenId</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> DataUpdated</span><span>(</span><span>tokenId</span><span>,</span><span> data</span><span>[</span><span>tokenId</span><span>]</span><span>,</span><span> newData</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> data</span><span>[</span><span>tokenId</span><span>]</span><span class="z-keyword"> =</span><span> newData</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-04-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ronan Sandfordhttps://github.com/wighawag https://wg-eips.ritovision.com/1930/ <h2 id="simple-summary">Simple Summary</h2> <p>Add the ability for smart contract to execute calls with a specific amount of gas. If this is not possible the execution should revert.</p> <h2 id="abstract">Abstract</h2> <p>The current CALL, DELEGATE_CALL, STATIC_CALL opcode do not enforce the gas being sent, they simply consider the gas value as a maximum. This pose serious problem for applications that require the call to be executed with a precise amount of gas.</p> <p>This is for example the case for meta-transaction where the contract needs to ensure the call is executed exactly as the signing user intended.</p> <p>But this is also the case for common use cases, like checking "on-chain" if a smart contract support a specific interface (via <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> for example).</p> <p>The solution presented here is to add new call semantic that enforce the amount of gas specified : the call either proceed with the exact amount of gas or do not get executed and the current call revert.</p> <h3 id="specification">Specification</h3> <p>There are 2 possibilities</p> <p>a) one is to add opcode variant that have a stricter gas semantic</p> <p>b) The other is to consider a specific gas value range (one that have never been used before) to have strict gas semantic, while leaving other values as before</p> <p>Here are the details description</p> <h4 id="option-a">option a)</h4> <ul> <li>add a new variant of the CALL opcode where the gas specified is enforced so that if the gas left at the point of call is not enough to give the specified gas to the destination, the current call revert</li> <li>add a new variant of the DELEGATE_CALL opcode where the gas specified is enforced so that if the gas left at the point of call is not enough to give the specified gas to the destination, the current call revert</li> <li>add a new variant of the STATIC_CALL opcode where the gas specified is enforced so that if the gas left at the point of call is not enough to give the specified gas to the destination, the current call revert</li> </ul> <h5 id="rational-for-a">Rational for a)</h5> <p>This solution has the merit to avoid any possibility of old contract be affected by the change. On the other hand it introduce 3 new opcodes. With EIP-1702, we could render the old opcode obsolete though.</p> <h4 id="option-b">option b)</h4> <p>For all opcode that allow to pass gas to another contract, do the following:</p> <ul> <li>If the most significant bit is one, consider the 31 less significant bit as the amount of gas to be given to the receiving contract in the strict sense. SO like a) if the gas left at the point of call is not enough to give the specified gas to the destination, the current call revert.</li> <li>If the 2nd most significant bit is zero, consider the whole value to behave like before, that is, it act as a maximum value, and even if not enough gas is present, the gas that can be given is given to the receiving contract</li> </ul> <h5 id="rational-for-b">Rational for b)</h5> <p>This solution relies on the fact that no contract would have given any value bigger or equal to 0x8000000000000000000000000000000000000000000000000000000000000000</p> <p>Note that solidity for example do not use value like 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF as it is more expensive than passing the gasLeft.</p> <p>Its main benefit though is that it does not require extra opcodes.</p> <h4 id="strict-gas-semantic">strict gas semantic</h4> <p>To be precise, regarding the strict gas semantic, based on <a href="https://wg-eips.ritovision.com/150/">EIP-150</a>, the current call must revert unless G &gt;= I x 64/63 where G is gas left at the point of call (after deducing the cost of the call itself) and I is the gas specified.</p> <p>So instead of</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>availableGas = availableGas - base</span></span> <span class="giallo-l"><span>gas := availableGas - availableGas/64</span></span> <span class="giallo-l"><span>...</span></span> <span class="giallo-l"><span>if !callCost.IsUint64() || gas &lt; callCost.Uint64() {</span></span> <span class="giallo-l"><span> return gas, nil</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>see https://github.com/ethereum/go-ethereum/blob/7504dbd6eb3f62371f86b06b03ffd665690951f2/core/vm/gas.go#L41-L48</p> <p>we would have</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>availableGas = availableGas - base</span></span> <span class="giallo-l"><span>gas := availableGas - availableGas/64</span></span> <span class="giallo-l"><span>if !callCost.IsUint64() || gas &lt; callCost.Uint64() {</span></span> <span class="giallo-l"><span> return 0, errNotEnoughGas</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="rationale">Rationale</h3> <p>Currently the gas specified as part of these opcodes is simply a maximum value. And due to the behavior of <a href="https://wg-eips.ritovision.com/150/">EIP-150</a> it is possible for an external call to be given less gas than intended (less than the gas specified as part of the CALL) while the rest of the current call is given enough to continue and succeed. Indeed since with EIP-150, the external call is given at max <code>G - Math.floor(G/64)</code> where G is the gasleft() at the point of the CALL, the rest of the current call is given <code>Math.floor(G/64)</code> which can be plenty enough for the transaction to succeed. For example, when G = 6,400,000 the rest of the transaction will be given 100,000 gas plenty enough in many case to succeed.</p> <p>This is an issue for contracts that require external call to only fails if they would fails with enough gas. This requirement is present in smart contract wallet and meta transaction in general, where the one executing the transaction is not the signer of the execution data. Because in such case, the contract needs to ensure the call is executed exactly as the signing user intended.</p> <p>But this is also true for simple use case, like checking if a contract implement an interface via EIP-165. Indeed as specified by such EIP, the <code>supporstInterface</code> method is bounded to use 30,000 gas so that it is theoretically possible to ensure that the throw is not a result of a lack of gas. Unfortunately due to how the different CALL opcodes behave contracts can't simply rely on the gas value specified. They have to ensure by other means that there is enough gas for the call.</p> <p>Indeed, if the caller do not ensure that 30,000 gas or more is provided to the callee, the callee might throw because of a lack of gas (and not because it does not support the interface), and the parent call will be given up to 476 gas to continue. This would result in the caller interpreting wrongly that the callee is not implementing the interface in question.</p> <p>While such requirement can be enforced by checking the gas left according to EIP-150 and the precise gas required before the call (see solution presented in that <a rel="external" href="https://web.solidified.io/contract/5b4769b1e6c0d80014f3ea4e/bug/5c83d86ac2dd6600116381f9">bug report</a> or after the call (see the native meta transaction implementation <a rel="external" href="https://github.com/pixowl/thesandbox-contracts/blob/623f4d4ca10644dcee145bcbd9296579a1543d3d/src/Sand/erc20/ERC20MetaTxExtension.sol#L176">here</a>, it would be much better if the EVM allowed us to strictly specify how much gas is to be given to the CALL so contract implementations do not need to follow <a href="https://wg-eips.ritovision.com/150/">EIP-150</a> behavior and the current gas pricing so closely.</p> <p>This would also allow the behaviour of <a href="https://wg-eips.ritovision.com/150/">EIP-150</a> to be changed without having to affect contract that require this strict gas behaviour.</p> <p>As mentioned, such strict gas behaviour is important for smart contract wallet and meta transaction in general. The issue is actually already a problem in the wild as can be seen in the case of Gnosis safe which did not consider the behavior of EIP-150 and thus fails to check the gas properly, requiring the safe owners to add otherwise unnecessary extra gas to their signed message to avoid the possibility of losing funds. See https://github.com/gnosis/safe-contracts/issues/100</p> <p>As for EIP-165, the issue already exists in the example implementation presented in the EIP. Please see the details of the issue <a rel="external" href="https://github.com/ethereum/EIPs/pull/881#issuecomment-491677748">here</a></p> <p>The same issue exists also on OpenZeppelin implementation, a library used by many. It does not for perform any check on gas before calling <code>supportsInterface</code> with 30,000 gas (see <a rel="external" href="https://github.com/OpenZeppelin/openzeppelin-solidity/blob/fa004a7f5de572b3dbcde1a8a81f9a87e353e799/contracts/introspection/ERC165Checker.sol#L37">here</a> and is thus vulnerable to the issue mentioned.</p> <p>While such issue can be prevented today by checking the gas with EIP-150 in mind, a solution at the opcode level is more elegant.</p> <p>Indeed, the two possible ways to currently enforce that the correct amount of gas is sent are as follow :</p> <ol> <li>check done before the call</li> </ol> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>uint256 gasAvailable = gasleft() - E;</span></span> <span class="giallo-l"><span>require(gasAvailable - gasAvailable / 64 &gt;= `txGas`, &quot;not enough gas provided&quot;)</span></span> <span class="giallo-l"><span>to.call.gas(txGas)(data); // CALL</span></span></code></pre> <p>where E is the gas required for the operation between the call to <code>gasleft()</code> and the actual call PLUS the gas cost of the call itself. While it is possible to simply over estimate <code>E</code> to prevent call to be executed if not enough gas is provided to the current call it would be better to have the EVM do the precise work itself. As gas pricing continue to evolve, this is important to have a mechanism to ensure a specific amount of gas is passed to the call so such mechanism can be used without having to relies on a specific gas pricing.</p> <ol start="2"> <li>check done after the call:</li> </ol> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>to.call.gas(txGas)(data); // CALL</span></span> <span class="giallo-l"><span>require(gasleft() &gt; txGas / 63, &quot;not enough gas left&quot;);</span></span></code></pre> <p>This solution does not require to compute a <code>E</code> value and thus do not relies on a specific gas pricing (except for the behaviour of EIP-150) since if the call is given not enough gas and fails for that reason, the condition above will always fail, ensuring the current call will revert. But this check still pass if the gas given was less AND the external call reverted or succeeded EARLY (so that the gas left after the call &gt; txGas / 63). This can be an issue if the code executed as part of the CALL is reverting as a result of a check against the gas provided. Like a meta transaction in a meta transaction.</p> <p>Similarly to the previous solution, an EVM mechanism would be much better.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>for specification a) : Backwards compatible as it introduce new opcodes.</p> <p>for specification b) : Backwards compatible as it use value range outside of what is used by existing contract (to be verified)</p> <h2 id="test-cases">Test Cases</h2> <h2 id="implementation">Implementation</h2> <p>None fully implemented yet. But see Specifications for an example in geth.</p> <h2 id="references">References</h2> <ol> <li>EIP-150, ./00150.md</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-04-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Julio Faurajulio@adhara.io Fernando Parisfer@io.builders Daniel Lehrnerdaniel@io.builders https://wg-eips.ritovision.com/1996/ <h2 id="simple-summary">Simple Summary</h2> <p>An extension to the ERC-20 standard token that allows tokens to be put on hold. This guarantees a future transfer and makes the held tokens unavailable for transfer in the mean time. Holds are similar to escrows in that are firm and lead to final settlement.</p> <h2 id="actors">Actors</h2> <h4 id="operator">Operator</h4> <p>An account which has been approved by an account to create holds on its behalf.</p> <h4 id="hold-issuer">Hold issuer</h4> <p>The account, which creates a hold. This can be the account owner itself, or any account, which has been approved as an operator for the account.</p> <h4 id="notary">Notary</h4> <p>The account which decides if a hold should be executed.</p> <h2 id="abstract">Abstract</h2> <p>A hold specifies a payer, a payee, a maximum amount, a notary and an expiration time. When the hold is created, the specified token balance from the payer is put on hold. A held balance cannot be transferred until the hold is either executed or released. The hold can only be executed by the notary, which triggers the transfer of the tokens from the payer to the payee. If a hold is released, either by the notary at any time, or by anyone after the expiration, no transfer is carried out and the amount is available again for the payer.</p> <p>A hold can be partially executed, if the execution specifies an amount less than the maximum amount. In this case the specified amount is transferred to the payee and the remaining amount is available again to the payer.</p> <p>Holds can be specified to be perpetual. In this case, the hold cannot be released upon expiration, and thus can only be executed by the notary or released by the notary or payee.</p> <h2 id="motivation">Motivation</h2> <p>A hold has to be used in different scenarios where a immediate transfer between accounts is not possible or has to be guaranteed beforehand:</p> <ol> <li> <p>A regulated token may not allow to do a token transfer between accounts without verifying first, that it follows all the regulations. In this case a clearable transfer has to be used. During the clearing process a hold is created to ensure, that the transfer is successful after all checks have passed. If the transfer violates any of the regulations, it is cleared and not further processed.</p> </li> <li> <p>In certain business situations a payment has to be guaranteed before its services can be used. For example: When checking in a hotel, the hotel will put a hold on the guest's account to ensure that enough balance is available to pay for the room before handing over the keys.</p> </li> <li> <p>In other occasions a payment has to be guaranteed without knowing the exact amount beforehand. To stay with the hotel example: The hotel can put a hold on the guest's account as a guarantee for any possible extras, like room service. When the guest checks out the hold is partially executed and the remaining amount is available again on the guest's account.</p> </li> </ol> <p>The ERC-20 <code>approve</code> function provides some of the necessary functionality for the use cases above. The main difference to holds, is that <code>approve</code> does not ensure a payment, as the approved money is not blocked and can be transferred at any moment.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IHoldable</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC-20 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> HoldStatusCode</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Nonexistent</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Ordered</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Executed</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ReleasedByNotary</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ReleasedByPayee</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ReleasedOnExpiration</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hold</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> notary</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> timeToExpiration</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> holdFrom</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> notary</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> timeToExpiration</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> releaseHold</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> executeHold</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> renewHold</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> timeToExpiration</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> retrieveHoldData</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> operationId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> notary</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> expiration</span><span>,</span><span class="z-storage z-type"> HoldStatusCode</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOnHold</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> netBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupplyOnHold</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> authorizeHoldOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeHoldOperator</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isHoldOperatorFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> operator</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> from</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> HoldCreated</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> holdIssuer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> operationId</span><span>, </span><span class="z-support">address</span><span class="z-variable"> from</span><span>, </span><span class="z-support">address</span><span class="z-variable"> to</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> notary</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> expiration</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> HoldExecuted</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> holdIssuer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> operationId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> notary</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> heldValue</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> transferredValue</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> HoldReleased</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> holdIssuer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> operationId</span><span>, </span><span class="z-variable">HoldStatusCode</span><span class="z-variable"> status</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> HoldRenewed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> holdIssuer</span><span>, </span><span class="z-support">string</span><span class="z-variable"> operationId</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> oldExpiration</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> newExpiration</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AuthorizedHoldOperator</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> account</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RevokedHoldOperator</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> operator</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> account</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="functions">Functions</h3> <h4 id="hold">hold</h4> <p>Creates a hold on behalf of the msg.sender in favor of the payee. It specifies a notary who is responsible to either execute or release the hold. The function must revert if the operation ID has been used before.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be transferred if executed</td></tr> <tr><td>notary</td><td>The address of the notary who is going to determine whether the hold is to be executed or released</td></tr> <tr><td>value</td><td>The amount to be transferred. Must be less or equal than the balance of the payer.</td></tr> <tr><td>timeToExpiration</td><td>The duration until the hold is expired. If it is '0' the hold must be perpetual.</td></tr> </tbody></table> <h4 id="holdfrom">holdFrom</h4> <p>Creates a hold on behalf of the payer in favor of the payee. The <code>from</code> account has to approve beforehand, that another account can issue holds on its behalf by calling <code>approveToHold</code>. The function must revert if the operation ID has been used before.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be transferred if executed</td></tr> <tr><td>notary</td><td>The address of the notary who is going to determine whether the hold is to be executed or released</td></tr> <tr><td>value</td><td>The amount to be transferred. Must be less or equal than the balance of the payer.</td></tr> <tr><td>timeToExpiration</td><td>The duration until the hold is expired. If it is '0' the hold must be perpetual.</td></tr> </tbody></table> <h4 id="releasehold">releaseHold</h4> <p>Releases a hold. Release means that the transfer is not executed and the held amount is available again for the payer. Until a hold has expired it can only be released by the notary or the payee. After it has expired it can be released by anyone.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> </tbody></table> <h4 id="executehold">executeHold</h4> <p>Executes a hold. Execute means that the specified value is transferred from the payer to the payee. If the specified value is less than the hold value the remaining amount is available again to the payer. The implementation must verify that only the notary is able to successfully call the function.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> <tr><td>value</td><td>The amount to be transferred. This amount has to be less or equal than the hold value</td></tr> </tbody></table> <h4 id="renewhold">renewHold</h4> <p>Renews a hold. The new expiration time must be the block timestamp plus the given <code>timeToExpiration</code>, independently if the hold was perpetual or not before that. Furthermore a hold must be made perpetual if <code>timeToExpiration</code> is '0'. The implementation must verify that only the payer or operator are able to successfully call the function. Furthermore the only a hold, which has not yet expired can be successfully renewed.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> <tr><td>timeToExpiration</td><td>The new duration until the hold is expired.</td></tr> </tbody></table> <h4 id="retrieveholddata">retrieveHoldData</h4> <p>Retrieves all the information available for a particular hold.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> </tbody></table> <h4 id="balanceonhold">balanceOnHold</h4> <p>Retrieves how much of the balance is currently held and therefore not available for transfer.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>account</td><td>The address which held balance should be returned</td></tr> </tbody></table> <h4 id="netbalanceof">netBalanceOf</h4> <p>Retrieves the net balance, which is the sum of <code>balanceOf</code> and <code>balanceOnHold</code>.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>account</td><td>The address which net balance should be returned</td></tr> </tbody></table> <h4 id="totalsupplyonhold">totalSupplyOnHold</h4> <p>Retrieves the total sum of how many tokens are on hold.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>-</td><td>-</td></tr> </tbody></table> <h4 id="authorizeholdoperator">authorizeHoldOperator</h4> <p>Approves an operator to issue holds on behalf of msg.sender.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be approved as operator of holds</td></tr> </tbody></table> <h4 id="revokeholdoperator">revokeHoldOperator</h4> <p>Revokes the approval to issue holds on behalf of msg.sender.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be revoked as operator of holds</td></tr> </tbody></table> <h4 id="isholdoperatorfor">isHoldOperatorFor</h4> <p>Retrieves if an operator is approved to create holds on behalf of <code>from</code>.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be a operator of holds</td></tr> <tr><td>from</td><td>The address on which the holds would be created</td></tr> </tbody></table> <h4 id="balanceof">balanceOf</h4> <p>The standard implementation of ERC-20 has to be changed in order to deduct the held balance from the ERC-20 balance.</p> <h4 id="transfer">transfer</h4> <p>The standard implementation of ERC-20 has to be changed in order to deduct the held balance from the ERC-20 balance. Any amount that is held must not be transferred.</p> <h4 id="transferfrom">transferFrom</h4> <p>The standard implementation of ERC-20 has to be changed in order to deduct the held balance from the ERC-20 balance. Any amount that is held must not be transferred.</p> <h3 id="events">Events</h3> <h4 id="holdcreated">HoldCreated</h4> <p>Emitted when a hold has been created.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>holdIssuer</td><td>The address of the hold issuer of the hold</td></tr> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> <tr><td>from</td><td>The address of the payer, from whom the tokens are to be taken if executed</td></tr> <tr><td>to</td><td>The address of the payee, to whom the tokens are to be paid if executed</td></tr> <tr><td>notary</td><td>The address of the notary who is going to determine whether the hold is to be executed or released</td></tr> <tr><td>value</td><td>The amount to be transferred. Must be less or equal than the balance of the payer.</td></tr> <tr><td>expiration</td><td>The unix timestamp when the hold is expired</td></tr> </tbody></table> <h4 id="holdexecuted">HoldExecuted</h4> <p>Emitted when a hold has been executed.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>holdIssuer</td><td>The address of the hold issuer of the hold</td></tr> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> <tr><td>notary</td><td>The address of the notary who executed the hold</td></tr> <tr><td>heldValue</td><td>The amount which was put on hold during creation</td></tr> <tr><td>transferredValue</td><td>The amount which was used for the transfer</td></tr> </tbody></table> <h4 id="holdreleased">HoldReleased</h4> <p>Emitted when a hold has been released.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>holdIssuer</td><td>The address of the hold issuer of the hold</td></tr> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> <tr><td>status</td><td>Can be one of the following values: <code>ReleasedByNotary</code>, <code>ReleasedByPayee</code>, <code>ReleasedOnExpiration</code></td></tr> </tbody></table> <h4 id="holdrenewed">HoldRenewed</h4> <p>Emitted when a hold has been renewed.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>holdIssuer</td><td>The address of the hold issuer of the hold</td></tr> <tr><td>operationId</td><td>The unique ID to identify the hold</td></tr> <tr><td>oldExpiration</td><td>The expiration time before the renewal</td></tr> <tr><td>newExpiration</td><td>The expiration time after the renewal</td></tr> </tbody></table> <h4 id="authorizedholdoperator">AuthorizedHoldOperator</h4> <p>Emitted when an operator has been approved to create holds on behalf of another account.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be a operator of holds</td></tr> <tr><td>account</td><td>Address on which behalf holds will potentially be created</td></tr> </tbody></table> <h4 id="revokedholdoperator">RevokedHoldOperator</h4> <p>Emitted when an operator has been revoked from creating holds on behalf of another account.</p> <table><thead><tr><th>Parameter</th><th>Description</th></tr></thead><tbody> <tr><td>operator</td><td>The address to be a operator of holds</td></tr> <tr><td>account</td><td>Address on which behalf holds could potentially be created</td></tr> </tbody></table> <h2 id="rationale">Rationale</h2> <p>This standards provides a functionality, to guarantee future payments, which is needed for many business cases where transfers have to be guaranteed.</p> <p>It goes a step further than the ERC-20 <code>approve</code> function by ensuring that the held balance will be available when the transfer is done. Something that can not be done with <code>approve</code>, as the approved amount is only a maximum spending amount, but never guaranteed to be available.</p> <p>While not requiring it, the naming of the functions <code>authorizeHoldOperator</code>, <code>revokeHoldOperator</code> and <code>isHoldOperatorFor</code> follows the naming convention of <a href="https://wg-eips.ritovision.com/777/">ERC-777</a>.</p> <p>The <code>operationId</code> is a string and not something more gas efficient to allow easy traceability of the hold and allow human readable ids. It is up to the implementer if the string should be stored on-chain or only its hash, as it is enough to identify a hold.</p> <p>The <code>operationId</code> is a competitive resource. It is recommended, but nor required, that the hold issuers used a unique prefix to avoid collisions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible as its implementation extends the functionality of ERC-20.</p> <h2 id="implementation">Implementation</h2> <p>The GitHub repository <a rel="external" href="https://github.com/IoBuilders/holdable-token">IoBuilders/holdable-token</a> contains the reference implementation.</p> <h2 id="contributors">Contributors</h2> <p>This proposal has been collaboratively implemented by <a rel="external" href="https://adhara.io/">adhara.io</a> and <a rel="external" href="https://io.builders/">io.builders</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-04-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Loredana Cirsteahttps://github.com/loredanacirstea Christian Tzurcanuhttps://github.com/ctzurcanu https://wg-eips.ritovision.com/1921/ <h2 id="simple-summary">Simple Summary</h2> <p>In the context of dType, the Decentralized Type System described in <a href="https://wg-eips.ritovision.com/1900/">EIP-1900</a>, we are proposing to add support for registering functions (with a preference for <code>pure</code> and <code>view</code>) in the dType Registry.</p> <h2 id="abstract">Abstract</h2> <p>This proposal is part of a series of EIPs focused on expanding the concept of a Decentralized Type System, as explained in <a href="https://wg-eips.ritovision.com/1900/">EIP-1900</a>. The current EIP specifies the data definitions and interfaces needed to support registering individual smart contract functions, as entries in the dType Registry.</p> <h2 id="motivation">Motivation</h2> <p>In order to evolve the EVM into a Singleton Operating System, we need a way to register, find and address contract functions that we want to run in an automated way. This implies having access to all the data needed to run the function inside the EVM.</p> <p>Aside from the above motivation, there are also near future benefits for this proposal. Having a globally available, non-custodial functions registry, will democratize the development of tools, such as those targeting: blockchain data analysis (e.g. block explorers), smart contract IDEs, security analysis of smart contracts.</p> <p>Registering new smart contract functions can be done through the same consensus mechanism as <a href="https://wg-eips.ritovision.com/1900/">EIP-1900</a> mentions, in order to avoid burdening the chain state with redundant or improper records.</p> <h2 id="specification">Specification</h2> <p>This specification targets <code>pure</code> and <code>view</code> functions.</p> <p>For each function, we can store:</p> <ul> <li><code>name</code> - type <code>string</code> unique function name, as defined in EIP-1900; required</li> <li><code>types</code> - the type data and label of each input, as defined in EIP-1900; required</li> <li><code>outputs</code> - the type data and label of each output; required</li> <li><code>contractAddress</code> - type <code>address</code> - smart contract where the function resides, as defined in EIP-1900; optional for interfaces</li> <li><code>source</code> - type <code>bytes32</code> - reference to an external file containing the function source code, as defined in EIP-1900; optional</li> </ul> <p>Therefore, this proposal adds <code>outputs</code> to the EIP-1900 type registration definition.</p> <p>An example of a function registration object for the dType registry is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;setStaked&quot;,</span></span> <span class="giallo-l"><span> &quot;types&quot;: [</span></span> <span class="giallo-l"><span> {&quot;name&quot;: &quot;TypeA&quot;, &quot;label&quot;: &quot;typeA&quot;, &quot;relation&quot;:0, &quot;dimensions&quot;:[]}</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span> &quot;typeChoice&quot;: 4,</span></span> <span class="giallo-l"><span> &quot;contractAddress&quot;: &lt;address of the deployed smart contract where the function is defined&gt;,</span></span> <span class="giallo-l"><span> &quot;source&quot;: &lt;bytes32 hash for referencing source files&gt;,</span></span> <span class="giallo-l"><span> &quot;outputs&quot;: [</span></span> <span class="giallo-l"><span> {&quot;name&quot;: &quot;TypeB&quot;, &quot;label&quot;: &quot;typeB&quot;, &quot;relation&quot;:0, &quot;dimensions&quot;:[]}</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The above object will be passed to <code>&lt;dType registry&gt;.insert({...})</code></p> <p>An additional <code>setOutputs</code> function is proposed for the dType registry:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function setOutputs(</span></span> <span class="giallo-l"><span> bytes32 identifier,</span></span> <span class="giallo-l"><span> dTypes[] memory outputs</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span> public</span></span></code></pre> <ul> <li><code>identifier</code> - type <code>bytes32</code>, the type's identifier, as defined in EIP-1900</li> <li><code>outputs</code> - type <code>dTypes</code>, as defined in EIP-1900</li> </ul> <h3 id="implementation-suggestions">Implementation Suggestions</h3> <p>In the dType registry implementation, <code>outputs</code> can be stored in a <code>mapping</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>mapping(bytes32 =&gt; dTypes[]) public outputs;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The suggestion to treat each <code>pure</code> or <code>view</code> function as a separate entity instead of having a contract-based approach allows us to:</p> <ul> <li>have a global context of readily available functions</li> <li>scale designs through functional programming patterns rather than contract-encapsulated logic (which can be successfully used to scale development efforts independently)</li> <li>bidirectionally connect functions with the types they use, making automation easier</li> <li>cherry-pick functions from already deployed contracts if the other contract functions do not pass community consensus</li> <li>have scope-restricted improvements - instead of redeploying entire contracts, we can just redeploy the new function versions that we want to be added to the registry</li> <li>enable fine-grained auditing of individual functions, for the common good</li> <li>enable testing directly on a production chain, without state side-effects</li> </ul> <p>The proposal to store the minimum ABI information on-chain, for each function, allows us to:</p> <ul> <li>enable on-chain automation (e.g. function chaining and composition)</li> <li>be backward compatible in case the function signature format changes (e.g. from <code>bytes4</code> to <code>bytes32</code>): multiple signature calculation functions can be registered with dType. Examples:</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function getSignatureBytes4(bytes32 identifier)</span></span> <span class="giallo-l"><span> view</span></span> <span class="giallo-l"><span> public</span></span> <span class="giallo-l"><span> returns (bytes4 signature)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>function getSignatureBytes32(bytes32 identifier)</span></span> <span class="giallo-l"><span> view</span></span> <span class="giallo-l"><span> public</span></span> <span class="giallo-l"><span> returns (bytes32 signature)</span></span></code></pre> <ul> <li><code>identifier</code> - the type's identifier, as defined in EIP-1900</li> <li><code>signature</code> - the function's signature</li> </ul> <p>Concerns about this design might be:</p> <ul> <li>redundancy of storing <code>contractAddress</code> for each function that is part of the same contract</li> </ul> <p>We think that state/storage cost will be compensated through DRYness across the chain, due to reusing types and functions that have already been registered and are now easy to find. Other state/storage cost calculations will be added once the specification and implementation are closer to be finalized.</p> <p>Note that the input and output types are based on types that have already been registered. This lowers the amount of ABI information needed to be stored for each function and enables developers to aggregate and find functions that use the same types for their I/O. This can be a powerful tool for interoperability and smart contract composition.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal does not affect extant Ethereum standards or implementations. Registering functions for existing contract deployments should be fully supported.</p> <h2 id="test-cases">Test Cases</h2> <p>Will be added.</p> <h2 id="implementation">Implementation</h2> <p>In-work implementation examples can be found at https://github.com/pipeos-one/dType. This proposal will be updated with an appropriate implementation when consensus is reached on the specifications.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-04-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Lee Rajhttps://github.com/lerajk Qin Jianhttps://github.com/qinjian https://wg-eips.ritovision.com/1973/ <h2 id="simple-summary">Simple Summary</h2> <p>A mintable token rewards interface that mints 'n' tokens per block which are distributed equally among the 'm' participants in the DAPP's ecosystem.</p> <h2 id="abstract">Abstract</h2> <p>The mintable token rewards interface allows DApps to build a token economy where token rewards are distributed equally among the active participants. The tokens are minted based on per block basis that are configurable (E.g. 10.2356 tokens per block, 0.1 token per block, 1350 tokens per block) and the mint function can be initiated by any active participant. The token rewards distributed to each participant is dependent on the number of participants in the network. At the beginning, when the network has low volume, the tokens rewards per participant is high but as the network scales the token rewards decreases dynamically.</p> <h2 id="motivation">Motivation</h2> <p>Distributing tokens through a push system to a large amount of participants fails due to block gas limit. As the number of participants in the network grow to tens of thousands, keeping track of the iterable registry of participants and their corresponding rewards in a push system becomes unmanagable. E.g. Looping through 5000 addresses to distribute 0.0000001 reward tokens is highly inefficient. Furthermore, the gas fees in these transactions are high and needs to be undertaken by the DApp developer or the respective company, leading to centralization concerns.</p> <p>A pull system is required to keep the application completely decentralized and to avoid the block gas limit problem. However, no standard solution has been proposed to distribute scalable rewards to tens of thousands participants with a pull system. This is what we propose with this EIP through concepts like TPP, round mask, participant mask.</p> <h2 id="specification">Specification</h2> <h3 id="definitions">Definitions</h3> <p><code>token amount per participant in the ecosytem or TPP (token per participant)</code>: TPP = (token amount to mint / total active participants)</p> <p><code>roundMask</code>: the cumulative snapshot of TPP over time for the token contract. E.g. transactionOne = 10 tokens are minted with 100 available participants (TPP = 10 / 100) , transactionTwo = 12 tokens are minted with 95 participants (TPP = 12 / 95 )</p> <p>roundMask = (10/100) + (12/95)</p> <p><code>participantMask</code>: is used to keep track of a <code>msg.sender</code> (participant) rewards over time. When a <code>msg.sender</code> joins or leaves the ecosystem, the player mask is updated</p> <p>participantMask = previous roundMask OR (current roundMask - TPP)</p> <p><code>rewards for msg.sender</code>: roundMask - participantMask</p> <p>E.g. Let's assume a total of 6 transactions (smart contract triggers or functions calls) are in place with 10 existing participants (denominator) and 20 tokens (numerator) are minted per transaction. At 2nd transaction, the 11th participant joins the network and exits before 5th transaction, the 11th participant's balance is as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>t1 roundMask = (20/10)</span></span> <span class="giallo-l"><span>t2 roundMask = (20/10) + (20/11) </span></span> <span class="giallo-l"><span>t3 roundMask = (20/10) + (20/11) + (20/11)</span></span> <span class="giallo-l"><span>t4 roundMask = (20/10) + (20/11) + (20/11) + (20/11)</span></span> <span class="giallo-l"><span>t5 roundMask = (20/10) + (20/11) + (20/11) + (20/11)+ (20/10)</span></span> <span class="giallo-l"><span>t6 roundMask = (20/10) + (20/11) + (20/11) + (20/11)+ (20/10) + (20/10)</span></span></code></pre> <p>Total tokens released in 6 transactions = 60 tokens</p> <p>As the participant joins at t2 and leaves before t5, the participant deserves the rewards between t2 and t4. When the participant joins at t2, the 'participantMask = (20/10)', when the participant leaves before t5, the cumulative deserved reward tokens are :</p> <p>rewards for msg.sender: <code>[t4 roundMask = (20/10) + (20/11)+ (20/11) + (20/11)] - [participantMask = (20/10)] = [rewards = (20/11)+ (20/11) + (20/11)]</code></p> <p>When the same participant joins the ecosystem at a later point (t27 or t35), a new 'participantMask' is given that is used to calculate the new deserved reward tokens when the participant exits. This process continues dynamically for each participant.</p> <p><code>tokensPerBlock</code>: the amount of tokens that will be released per block</p> <p><code>blockFreezeInterval</code>: the number of blocks that need to pass until the next mint. E.g. if set to 50 and 'n' tokens were minted at block 'b', the next 'n' tokens won't be minted until 'b + 50' blocks have passed</p> <p><code>lastMintedBlockNumber</code>: the block number on which last 'n' tokens were minted</p> <p><code>totalParticipants</code> : the total number of participants in the DApp network</p> <p><code>tokencontractAddress</code> : the contract address to which tokens will be minted, default is address(this)</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.2</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;openzeppelin-solidity/contracts/token/ERC20/ERC20Mintable.sol&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;openzeppelin-solidity/contracts/token/ERC20/ERC20Detailed.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Rewards</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20Mintable</span><span>, </span><span class="z-entity z-name">ERC20Detailed</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">using</span><span class="z-entity z-name"> SafeMath</span><span class="z-keyword"> for</span><span class="z-entity z-name"> uint256</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> public</span><span> roundMask</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> public</span><span> lastMintedBlockNumber</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> public</span><span> totalParticipants </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> public</span><span> tokensPerBlock</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> public</span><span> blockFreezeInterval</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-support">address</span><span class="z-storage z-type"> public</span><span> tokencontractAddress </span><span class="z-keyword">=</span><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span class="z-storage z-type"> public</span><span> participantMask</span><span>;</span><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> constructor, initializes variables.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _tokensPerBlock</span><span class="z-comment"> The amount of token that will be released per block, entered in wei format (E.g. 1000000000000000000)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _blockFreezeInterval</span><span class="z-comment"> The amount of blocks that need to pass (E.g. 1, 10, 100) before more tokens are brought into the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokensPerBlock</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _blockFreezeInterval</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> ERC20Detailed</span><span>(</span><span>&quot;Simple Token&quot;, &quot;SIM&quot;, 18)</span><span>{</span><span> </span></span> <span class="giallo-l"><span>lastMintedBlockNumber </span><span class="z-keyword">=</span><span class="z-variable z-language"> block</span><span>.</span><span>number</span><span>;</span></span> <span class="giallo-l"><span>tokensPerBlock </span><span class="z-keyword">=</span><span> _tokensPerBlock</span><span>;</span></span> <span class="giallo-l"><span>blockFreezeInterval </span><span class="z-keyword">=</span><span> _blockFreezeInterval</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Modifier to check if msg.sender is whitelisted as a minter. </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">modifier</span><span class="z-entity z-name"> isAuthorized</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span class="z-entity z-name">isMinter</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-constant">_</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to add participants in the network. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _minter</span><span class="z-comment"> The address that will be able to mint tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addMinters</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _minter</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name">_addMinter</span><span>(</span><span>_minter</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>totalParticipants </span><span class="z-keyword">=</span><span> totalParticipants</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">updateParticipantMask</span><span>(</span><span>_minter</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to remove participants in the network. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _minter</span><span class="z-comment"> The address that will be unable to mint tokens.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeMinters</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _minter</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span>totalParticipants </span><span class="z-keyword">=</span><span> totalParticipants</span><span>.</span><span class="z-entity z-name">sub</span><span>(</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">_removeMinter</span><span>(</span><span>_minter</span><span>)</span><span>;</span><span> </span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to introduce new tokens in the network. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> trigger</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> isAuthorized</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support">bool</span><span> res </span><span class="z-keyword">=</span><span class="z-entity z-name"> readyToMint</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span>(</span><span>res </span><span class="z-keyword">==</span><span class="z-constant"> false</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span>}</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name">mintTokens</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to withdraw rewarded tokens by a participant. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> withdraw</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> isAuthorized</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> amount </span><span class="z-keyword">=</span><span class="z-entity z-name"> calculateRewards</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span>amount </span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">ERC20</span><span>(</span><span>tokencontractAddress</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to check if new tokens are ready to be minted. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> readyToMint</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> currentBlockNumber </span><span class="z-keyword">=</span><span class="z-variable z-language"> block</span><span>.</span><span>number</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> lastBlockNumber </span><span class="z-keyword">=</span><span> lastMintedBlockNumber</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">if</span><span>(</span><span>currentBlockNumber </span><span class="z-keyword">&gt;</span><span> lastBlockNumber </span><span class="z-keyword">+</span><span> blockFreezeInterval</span><span>)</span><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to calculate current rewards for a participant. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> uint that returns the calculated rewards amount.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> calculateRewards</span><span>(</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> playerMask </span><span class="z-keyword">=</span><span> participantMask</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> rewards </span><span class="z-keyword">=</span><span> roundMask</span><span>.</span><span class="z-entity z-name">sub</span><span>(</span><span>playerMask</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">updateParticipantMask</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">return</span><span> rewards</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to mint new tokens into the economy. </span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> mintTokens</span><span>(</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> currentBlockNumber </span><span class="z-keyword">=</span><span class="z-variable z-language"> block</span><span>.</span><span>number</span><span>;</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> tokenReleaseAmount </span><span class="z-keyword">=</span><span> (</span><span>currentBlockNumber</span><span>.</span><span class="z-entity z-name">sub</span><span>(</span><span>lastMintedBlockNumber</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">mul</span><span>(</span><span>tokensPerBlock</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>lastMintedBlockNumber </span><span class="z-keyword">=</span><span> currentBlockNumber</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">mint</span><span>(</span><span>tokencontractAddress</span><span>,</span><span> tokenReleaseAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">calculateTPP</span><span>(</span><span>tokenReleaseAmount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to calculate TPP (token amount per participant).</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> calculateTPP</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tokens</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> tpp </span><span class="z-keyword">=</span><span> tokens</span><span>.</span><span class="z-entity z-name">div</span><span>(</span><span>totalParticipants</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">updateRoundMask</span><span>(</span><span>tpp</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to update round mask. </span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> updateRoundMask</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> tpp</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span>roundMask </span><span class="z-keyword">=</span><span> roundMask</span><span>.</span><span class="z-entity z-name">add</span><span>(</span><span>tpp</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Function to update participant mask (store the previous round mask)</span></span> <span class="giallo-l"><span class="z-comment">* </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> A</span><span class="z-comment"> boolean that indicates if the operation was successful.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> updateParticipantMask</span><span>(</span><span class="z-support">address</span><span class="z-variable"> participant</span><span>)</span><span class="z-storage z-type"> private</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support">uint256</span><span> previousRoundMask </span><span class="z-keyword">=</span><span> roundMask</span><span>;</span></span> <span class="giallo-l"><span>participantMask</span><span>[</span><span>participant</span><span>]</span><span class="z-keyword"> =</span><span> previousRoundMask</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Currently, there is no standard for a scalable reward distribution mechanism. In order to create a sustainable cryptoeconomic environment within DAPPs, incentives play a large role. However, without a scalable way to distribute rewards to tens of thousands of participants, most DAPPs lack a good incentive structure. The ones with a sustainable cryptoeconomic environment depend heavily on centralized servers or a group of selective nodes to trigger the smart contracts. But, in order to keep an application truly decentralized, the reward distribution mechanism must depend on the active participants itself and scale as the number of participants grow. This is what this EIP intends to accomplish.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Not Applicable.</p> <h2 id="test-cases">Test Cases</h2> <p>WIP, will be added.</p> <h2 id="implementation">Implementation</h2> <p>WIP, a proper implementation will be added later.A sample example is below:</p> <p><code>etherscan rewards contract</code> : https://ropsten.etherscan.io/address/0x8b0abfc541ab7558857816a67e186221adf887bc#tokentxns</p> <p><code>Step 1</code> : deploy Rewards contract with the following parameters_tokensPerBlock = 1e18, _blockFreezeInterval = 1</p> <p><code>Step 2</code> : add Alice(0x123) and Bob(0x456) as minters, addMinters(address _minter)</p> <p><code>Step 3</code> : call trigger() from Alice / Bob's account. 65 blocks are passed, hence 65 SIM tokens are minted. The RM is 32500000000000000000</p> <p><code>Step 4</code> : Alice withdraws and receives 32.5 SIM tokens (65 tokens / 2 participants) and her PM = 32500000000000000000</p> <p><code>Step 5</code> : add Satoshi(0x321) and Vitalik(0x654) as minters, addMinters(address _minter)</p> <p><code>Step 6</code> : call trigger() from Alice / Bob's / Satoshi / Vitalik account. 101 blocks are passed, hence 101 SIM tokens are minted. The RM is 57750000000000000000</p> <p><code>Step 7</code> : Alice withdraws and receives 25.25 SIM tokens (101 tokens / 4 participants) and her PM = 57750000000000000000</p> <p><code>Step 8</code> : Bob withdraws and receives 57.75 SIM tokens ((65 tokens / 2 participants) + (101 tokens / 4 participants)). Bob's PM = 57750000000000000000</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> <h2 id="references">References</h2> <ol> <li> <p>Scalable Reward Distribution on the Ethereum Blockchain by Bogdan Batog, Lucian Boca and Nick Johnson</p> </li> <li> <p>Fomo3d DApp, https://fomo3d.hostedwiki.co/</p> </li> </ol> 2019-03-28T00:00:00+00:00 2026-02-11T14:48:25+00:00 Loredana Cirsteahttps://github.com/loredanacirstea Christian Tzurcanuhttps://github.com/ctzurcanu https://wg-eips.ritovision.com/1900/ <h2 id="simple-summary">Simple Summary</h2> <p>The EVM and related languages such as Solidity need consensus on an extensible Type System in order to further evolve into the Singleton Operating System (The World Computer).</p> <h2 id="abstract">Abstract</h2> <p>We are proposing a decentralized Type System for Ethereum, to introduce data definition (and therefore ABI) consistency. This ERC focuses on defining an on-chain Type Registry (named <code>dType</code>) and a common interface for creating types, based on <code>struct</code>s.</p> <h2 id="motivation">Motivation</h2> <p>In order to build a network of interoperable protocols on Ethereum, we need data standardization, to ensure a smooth flow of on-chain information. Off-chain, the Type Registry will allow a better analysis of blockchain data (e.g. for blockchain explorers) and creation of smart contract development tools for easily using existing types in a new smart contract.</p> <p>However, this is only the first phase. As defined in this document and in the future proposals that will be based on this one, we are proposing something more: a decentralized Type System with Data Storage - <a rel="external" href="https://github.com/ethereum/EIPs/pull/2158">ERC-2158</a>. In addition, developers can create libraries of <code>pure</code> functions that know how to interact and modify the data entries - <a rel="external" href="https://github.com/ethereum/EIPs/issues/1921">dType Functions Extension</a>. This will effectively create the base for a general functional programming system on Ethereum, where developers can use previously created building blocks.</p> <p>To summarize:</p> <ul> <li>We would like to have a good decentralized medium for integrating all Ethereum data, and relationships between the different types of data. Also, a way to address the behavior related to each data type.</li> <li>Functional programming becomes easier. Functions like <code>map</code>, <code>reduce</code>, <code>filter</code>, are implemented by each type library.</li> <li>Solidity development tools could be transparently extended to include the created types (For example in IDEs like Remix). At a later point, the EVM itself can have precompiled support for these types.</li> <li>The system can be easily extended to types pertaining to other languages. (With type definitions in the source (Swarm stored source code in the respective language))</li> <li>The dType database should be part of the System Registry for the Operating System of The World Computer</li> </ul> <h2 id="specification">Specification</h2> <p>The Type Registry can have a governance protocol for its CRUD operations. However, this, and other permission guards are not covered in this proposal.</p> <h3 id="type-definition-and-metadata">Type Definition and Metadata</h3> <p>The dType registry should support the registration of Solidity's elementary and complex types. In addition, it should also support contract events definitions. In this EIP, the focus will be on describing the minimal on-chain type definition and metadata needed for registering Solidity user-defined types.</p> <h4 id="type-definition-typelibrary">Type Definition: TypeLibrary</h4> <p>A type definition consists of a type library containing:</p> <ul> <li>the nominal <code>struct</code> used to define the type</li> <li>additional functions: <ul> <li><code>isInstanceOf</code>: checks whether a given variable is an instance of the defined type. Additional rules can be defined for each type fields, e.g. having a specific range for a <code>uint16 amount</code>.</li> <li>provide HOFs such as <code>map</code>, <code>filter</code>, <code>reduce</code></li> <li><code>structureBytes</code> and <code>destructureBytes</code>: provide type structuring and destructuring. This can be useful for low-level calls or assembly code, when importing contract interfaces is not an efficient option. It can also be used for type checking.</li> </ul> </li> </ul> <p>A simple example is:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> experimental</span><span class="z-constant"> ABIEncoderV2</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">library</span><span class="z-entity z-name"> myBalanceLib</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> myBalance</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> accountName</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> structureBytes</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-variable">myBalance</span><span class="z-storage z-type"> memory</span><span class="z-variable"> balance</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> destructureBytes</span><span>(</span><span class="z-entity z-name">myBalance</span><span class="z-storage z-type"> memory</span><span class="z-entity z-name"> balance</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable"> data</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> isInstanceOf</span><span>(</span><span class="z-entity z-name">myBalance</span><span class="z-storage z-type"> memory</span><span class="z-entity z-name"> balance</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> isInstance</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> map</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> address</span><span class="z-entity z-name"> callbackAddr</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> bytes4</span><span class="z-entity z-name"> callbackSig</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> myBalance</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-entity z-name"> balanceArr</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-storage z-type"> internal</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">myBalance</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> result</span><span>)</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Types can also use existing types in their composition. However, this will always result in a directed acyclic graph.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">library</span><span class="z-entity z-name"> myTokenLib</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> using</span><span class="z-entity z-name"> myBalanceLib</span><span class="z-keyword"> for</span><span class="z-entity z-name"> myBalanceLib</span><span>.</span><span>myBalance</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> myToken</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> token</span><span>;</span></span> <span class="giallo-l"><span> myBalanceLib</span><span>.</span><span>myBalance</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="type-metadata-dtype-registry">Type Metadata: dType Registry</h4> <p>Type metadata will be registered on-chain, in the dType registry contract. This consists of:</p> <ul> <li><code>name</code> - the type's name, as it would be used in Solidity; it can be stored as a <code>string</code> or encoded as <code>bytes</code>. The name can have a human-readable part and a version number.</li> <li><code>typeChoice</code> - used for storing additional ABI data that differentiate how types are handled on and off chain. It is defined as an <code>enum</code> with the following options: <code>BaseType</code>, <code>PayableFunction</code>, <code>StateFunction</code>, <code>ViewFunction</code>, <code>PureFunction</code>, <code>Event</code></li> <li><code>contractAddress</code> - the Ethereum <code>address</code> of the <code>TypeRootContract</code>. For this proposal, we can consider the Type Library address as the <code>TypeRootContract</code>. Future EIPs will make it more flexible and propose additional TypeStorage contracts that will modify the scope of <code>contractAddress</code> - <a rel="external" href="https://github.com/ethereum/EIPs/pull/2158">ERC-2158</a>.</li> <li><code>source</code> - a <code>bytes32</code> Swarm hash where the source code of the type library and contracts can be found; in future EIPs, where dType will be extended to support other languages (e.g. JavaScript, Rust), the file identified by the Swarm hash will contain the type definitions in that language.</li> <li><code>types</code> - metadata for subtypes: the first depth level internal components. This is an array of objects (<code>structs</code>), with the following fields: <ul> <li><code>name</code> - the subtype name, of type <code>string</code>, similar to the above <code>name</code> definition</li> <li><code>label</code> - the subtype label</li> <li><code>dimensions</code> - <code>string[]</code> used for storing array dimensions. E.g.: <ul> <li><code>[]</code> -&gt; <code>TypeA</code></li> <li><code>[""]</code> -&gt; <code>TypeA[]</code></li> <li><code>["2"]</code> -&gt; <code>TypeA[2]</code></li> <li><code>["",""]</code> -&gt; <code>TypeA[][]</code></li> <li><code>["2","3"]</code> -&gt; <code>TypeA[2][3]</code></li> </ul> </li> </ul> </li> </ul> <p>Examples of metadata, for simple, value types:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">contractAddress</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">typeChoice</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-constant">0</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">source</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">types</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">contractAddress</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">typeChoice</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-constant">0</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">source</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">types</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Composed types can be defined as:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">contractAddress</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x105631C6CdDBa84D12Fa916f0045B1F97eC9C268</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">typeChoice</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-constant">0</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">source</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> &lt;</span><span class="z-entity z-name z-tag">a</span><span class="z-entity"> SWARM</span><span class="z-entity"> hash</span><span class="z-entity"> for</span><span class="z-entity"> type</span><span class="z-entity"> source</span><span class="z-entity"> code</span><span class="z-entity"> files</span><span>&gt;</span><span>,</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;myBalance&quot;,</span></span> <span class="giallo-l"><span> &quot;types&quot;: [</span></span> <span class="giallo-l"><span> {</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">label</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">accountName</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> dimensions</span><span>:</span><span> [</span><span>]</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">label</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">amount</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> dimensions</span><span>:</span><span> [</span><span>]</span><span>}</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Composed types can be further composed:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">contractAddress</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x91E3737f15e9b182EdD44D45d943cF248b3a3BF9</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">typeChoice</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-constant">0</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">source</span><span class="z-punctuation z-definition z-string">&quot;</span><span>:</span><span> &lt;</span><span class="z-entity z-name z-tag">a</span><span class="z-entity"> SWARM</span><span class="z-entity"> hash</span><span class="z-entity"> for</span><span class="z-entity"> type</span><span class="z-entity"> source</span><span class="z-entity"> code</span><span class="z-entity"> files</span><span>&gt;</span><span>,</span></span> <span class="giallo-l"><span> &quot;name&quot;: &quot;myToken&quot;,</span></span> <span class="giallo-l"><span> &quot;types&quot;: [</span></span> <span class="giallo-l"><span> {</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">label</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">token</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> dimensions</span><span>:</span><span> [</span><span>]</span><span>}</span><span>,</span></span> <span class="giallo-l"><span> {</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">myBalance</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">label</span><span class="z-punctuation z-definition z-string">&quot;</span><span>: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">balance</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> dimensions</span><span>:</span><span> [</span><span>]</span><span>}</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>myToken</code> type will have the final data format: <code>(address,(string,uint256))</code> and a labeled format: <code>(address token, (string accountName, uint256 amount))</code>.</p> <h5 id="dtype-registry-data-structures-and-interface">dType Registry Data Structures and Interface</h5> <p>To store this metadata, the dType registry will have the following data structures:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">enum</span><span class="z-entity z-name"> TypeChoices</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> BaseType</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> PayableFunction</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> StateFunction</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ViewFunction</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> PureFunction</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Event</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> dTypes</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> label</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span>[</span><span>]</span><span> dimensions</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> dType</span><span> {</span></span> <span class="giallo-l"><span> TypeChoices typeChoice</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> contractAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> source</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"><span> dTypes</span><span>[</span><span>]</span><span> types</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre> <p>For storage, we propose a pattern which isolates the type metadata from additional storage-specific data and allows CRUD operations on records.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> key: identifier</span></span> <span class="giallo-l"><span class="z-storage z-type">mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword"> =&gt;</span><span> Type</span><span>)</span><span class="z-storage z-type"> public</span><span> typeStruct</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> array of identifiers</span></span> <span class="giallo-l"><span class="z-support">bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> public</span><span> typeIndex</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Type</span><span> {</span></span> <span class="giallo-l"><span> dType data</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> index</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Note that we are proposing to define the type's primary identifier, <code>identifier</code>, as <code>keccak256(abi.encodePacked(name))</code>. If the system is extended to other programming languages, we can define <code>identifier</code> as <code>keccak256(abi.encodePacked(language, name))</code>. Initially, single word English names can be disallowed, avoiding name squatting.</p> <p>The dType registry interface is:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;./dTypeLib.sol&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> dType</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LogNew</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identifier</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> index</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LogUpdate</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identifier</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> index</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LogRemove</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> identifier</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> index</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> insert</span><span>(</span><span class="z-variable">dTypeLib</span><span>.</span><span class="z-support z-variable">dType</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> remove</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> index</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> count</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> counter</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTypeIdentifier</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name</span><span>)</span><span class="z-storage z-type"> pure</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getByIdentifier</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-variable">dTypeLib</span><span>.</span><span class="z-support z-variable">dType</span><span class="z-storage z-type"> memory</span><span class="z-variable"> dtype</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> get</span><span>(</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span class="z-variable"> name</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-variable">dTypeLib</span><span>.</span><span class="z-support z-variable">dType</span><span class="z-storage z-type"> memory</span><span class="z-variable"> dtype</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isRegistered</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> identifier</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> registered</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><strong>Notes:</strong></p> <p>To ensure backward compatibility, we suggest that updating types should not be supported.</p> <p>The <code>remove</code> function can also be removed from the interface, to ensure immutability. One reason for keeping it would be clearing up storage for types that are not in use or have been made obsolete. However, this can have undesired effects and should be accompanied by a solid permissions system, testing and governance process. This part will be updated when enough feedback has been received.</p> <h2 id="rationale">Rationale</h2> <p>The Type Registry must store the minimum amount of information for rebuilding the type ABI definition. This allows us to:</p> <ul> <li>support on-chain interoperability</li> <li>decode blockchain side effects off-chain (useful for block explorers)</li> <li>allow off-chain tools to cache and search through the collection (e.g. editor plugin for writing typed smart contracts)</li> </ul> <p>There is one advantage that has become clear with the emergence of global operating systems, like Ethereum: we can have a global type system through which the system’s parts can interoperate. Projects should agree on standardizing types and a type registry, continuously working on improving them, instead of creating encapsulated projects, each with their own types.</p> <p>The effort of having consensus on new types being added or removing unused ones is left to the governance system.</p> <p>After the basis of such a system is specified, we can move forward to building a static type checking system at compile time, based on the type definitions and rules stored in the dType registry.</p> <p>The Type Library must express the behavior strictly pertinent to its defined type. Additional behavior, required by various project's business logic can be added later, through libraries containing functions that handle the respective type. These can also be registered in dType, but will be detailed in a future ERC.</p> <p>This is an approach that will separate definitions from stored data and behavior, allowing for easier and more secure fine-grained upgrades.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This proposal does not affect extant Ethereum standards or implementations. It uses the present experimental version of ABIEncoderV2.</p> <h2 id="test-cases">Test Cases</h2> <p>Will be added.</p> <h2 id="implementation">Implementation</h2> <p>An in-work implementation can be found at https://github.com/pipeos-one/dType/tree/master/contracts/contracts. This proposal will be updated with an appropriate implementation when consensus is reached on the specifications.</p> <p>A video demo of the current implementation (a more extended version of this proposal) can be seen at https://youtu.be/pcqi4yWBDuQ.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-03-15T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonhttps://github.com/arachnid https://wg-eips.ritovision.com/1844/ <h2 id="simple-summary">Simple Summary</h2> <p>Defines a method of associating contract interfaces with ENS names and addresses, and of discovering those interfaces.</p> <h2 id="abstract">Abstract</h2> <p>This EIP specifies a method for exposing interfaces associated with an ENS name or an address (typically a contract address) and allowing applications to discover those interfaces and interact with them. Interfaces can be implemented either by the target contract (if any) or by any other contract.</p> <h2 id="motivation">Motivation</h2> <p>EIP 165 supports interface discovery - determining if the contract at a given address supports a requested interface. However, in many cases it's useful to be able to discover functionality associated with a name or an address that is implemented by other contracts.</p> <p>For example, a token contract may not itself provide any kind of 'atomic swap' functionality, but there may be associated contracts that do. With ENS interface discovery, the token contract can expose this metadata, informing applications where they can find that functionality.</p> <h2 id="specification">Specification</h2> <p>A new profile for ENS resolvers is defined, consisting of the following method:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> interfaceImplementer</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span></code></pre> <p>The EIP-165 interface ID of this interface is <code>0xb8f2bbb4</code>.</p> <p>Given an ENS name hash <code>node</code> and an EIP-165 <code>interfaceID</code>, this function returns the address of an appropriate implementer of that interface. If there is no interface matching that interface ID for that node, 0 is returned.</p> <p>The address returned by <code>interfaceImplementer</code> MUST refer to a smart contract.</p> <p>The smart contract at the returned address SHOULD implement EIP-165.</p> <p>Resolvers implementing this interface MAY utilise a fallback strategy: If no matching interface was explicitly provided by the user, query the contract returned by <code>addr()</code>, returning its address if the requested interface is supported by that contract, and 0 otherwise. If they do this, they MUST ensure they return 0, rather than reverting, if the target contract reverts.</p> <p>This field may be used with both forward resolution and reverse resolution.</p> <h2 id="rationale">Rationale</h2> <p>A naive approach to this problem would involve adding this method directly to the target contract. However, doing this has several shortcomings:</p> <ol> <li>Each contract must maintain its own list of interface implementations.</li> <li>Modifying this list requires access controls, which the contract may not have previously required.</li> <li>Support for this must be designed in when the contract is written, and cannot be retrofitted afterwards.</li> <li>Only one canonical list of interfaces can be supported.</li> </ol> <p>Using ENS resolvers instead mitigates these shortcomings, making it possible for anyone to associate interfaces with a name, even for contracts not previously built with this in mind.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backwards compatibility issues.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>The PublicResolver in the <a rel="external" href="https://github.com/ensdomains/resolvers/">ensdomains/resolvers</a> repository implements this interface.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-03-06T00:00:00+00:00 2026-02-11T14:49:27+00:00 Remco BloemenRecmo@0x.org https://wg-eips.ritovision.com/1829/ <h1 id="precompile-for-elliptic-curve-linear-combinations">Precompile for Elliptic Curve Linear Combinations</h1> <h2 id="simple-summary">Simple Summary</h2> <p>Currently the EVM only supports <em>secp256k1</em> in a limited way through <code>ecrecover</code> and <em>altbn128</em> through two pre-compiles. There are draft proposals to add more curves. There are many more elliptic curves that have useful applications for integration with existing systems or newly developed curves for zero-knowledge proofs.</p> <p>This EIP adds a precompile that allows whole classes of curves to be used.</p> <h2 id="abstract">Abstract</h2> <p>A precompile that takes a curve and computes a linear combination of curve points.</p> <h2 id="motivation">Motivation</h2> <h2 id="specification">Specification</h2> <p>Given integers <code>m, α</code> and <code>β</code>, scalars <code>s_i</code>, and curve points <code>A_i</code> construct the elliptic curve</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>y² = x³ + α ⋅ x + β mod m</span></span></code></pre> <p>and compute the following</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>C = s₀ ⋅ A₀ + s₁ ⋅ A₁ + ⋯ + s_n ⋅ A_n</span></span></code></pre> <p>aka <em>linear combination</em>, <em>inner product</em>, <em>multi-multiplication</em> or even <em>multi-exponentiation</em>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>(Cx, Cy) := ecmul(m, α, β, s0, Ax0, As0, s1, Ax1, As1, ...)</span></span></code></pre><h3 id="gas-cost">Gas cost</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>BASE_GAS = ...</span></span> <span class="giallo-l"><span>ADD_GAS = ...</span></span> <span class="giallo-l"><span>MUL_GAS = ...</span></span></code></pre> <p>The total gas cost is <code>BASE_GAS</code> plus <code>ADD_GAS</code> for each <code>s_i</code> that is <code>1</code> and <code>MUL_GAS</code> for each <code>s_i &gt; 1</code> (<code>s_i = 0</code> is free).</p> <h3 id="encoding-of-points">Encoding of points</h3> <p>Encode as <code>(x, y')</code> where <code>s</code> indicates whether <code>y</code> or <code>-y</code> is to be taken. It follows SEC 1 v 1.9 2.3.4, except uncompressed points (<code>y' = 0x04</code>) are not supported.</p> <table><thead><tr><th><code>y'</code></th><th><code>(x, y)</code></th></tr></thead><tbody> <tr><td><code>0x00</code></td><td>Point at infinity</td></tr> <tr><td><code>0x02</code></td><td>Solution with <code>y</code> even</td></tr> <tr><td><code>0x03</code></td><td>Solution with <code>y</code> odd</td></tr> </tbody></table> <p>Conversion from affine coordinates to compressed coordinates is trivial: <code>y' = 0x02 | (y &amp; 0x01)</code>.</p> <h3 id="special-cases">Special cases</h3> <p><strong>Coordinate recovery.</strong> Set <code>s₀ = 1</code>. The output will be the recovered coordinates of <code>A₀</code>.</p> <p><strong>On-curve checking.</strong> Do coordinate recovery and compare <code>y</code> coordinate.</p> <p><strong>Addition.</strong> Set <code>s₀ = s₁ = 1</code>, the output will be <code>A₀ + A₁</code>.</p> <p><strong>Doubling.</strong> Set <code>s₀ = 2</code>. The output will be <code>2 ⋅ A₀</code>. (Note: under the current gas model, this may be more costly than self-addition!)</p> <p><strong>Scalar multiplication.</strong> Set only <code>s₀</code> and <code>A₀</code>.</p> <p><strong>Modular square root.</strong> Set <code>α = s₀ = A = 0</code> the output will have <code>Cy² = β mod m</code>.</p> <h3 id="edge-cases">Edge cases</h3> <ul> <li>Non-prime moduli or too small modulus</li> <li>Field elements larger than modulus</li> <li>Curve has singular points (<code>4 α³ + 27 β² = 0</code>)</li> <li>Invalid sign bytes</li> <li>x coordinate not on curve</li> <li>Returning the point at infinity</li> <li>(Please add if you spot more)</li> </ul> <h2 id="rationale">Rationale</h2> <p><strong>Generic Field and Curve.</strong> Many important optimizations are independent of the field and curve used. Some missed specific optimizations are:</p> <ul> <li>Reductions specific to the binary structure of the field prime.</li> <li>Precomputation of Montgomery factors.</li> <li>Precomputation of multiples of certain popular points like the generator.</li> <li>Special point addition/doubling <a rel="external" href="https://www.hyperelliptic.org/EFD/g1p/auto-shortw.html">formulas</a> for <code>α = -3</code>, <code>α = -1</code>, <code>α = 0</code>, <code>β = 0</code>.</li> </ul> <p>TODO: The special cases for <code>α</code> and <code>β</code> might be worth implementing and offering a gas discount.</p> <p><strong>Compressed Coordinates.</strong> Compressed coordinates allow contract to work with only <code>x</code> coordinates and sign bytes. It also prevents errors around points not being on-curve. Conversion to compressed coordinates is trivial.</p> <p><strong>Linear Combination.</strong> We could instead have a simple multiply <code>C = r ⋅ A</code>. In this case we would need a separate pre-compile for addition. In addition, a linear combination allows for optimizations that like Shamir's trick that are not available in a single scalar multiplication. ECDSA requires <code>s₀ ⋅ A₀ + s₁ ⋅ A₁</code> and would benefit from this.</p> <p>The BN254 (aka alt_bn8) multiplication operation introduced by the <a href="https://wg-eips.ritovision.com/196/">EIP-196</a> precompile only handles a single scalar multiplication. The missed performance is such that for two or more points it is cheaper to use EVM, as practically demonstrated by <a rel="external" href="https://medium.com/aztec-protocol/huffing-for-crypto-with-weierstrudel-9c9568c06901">Weierstrudel</a>.</p> <p><strong>Variable Time Math.</strong> When called during a transaction, there is no assumption of privacy and no mitigations for side-channel attacks are necessary.</p> <p><strong>Prime Fields.</strong> This EIP is for fields of large characteristic. It does not cover Binary fields and other fields of non-prime characteristic.</p> <p><strong>256-bit modulus.</strong> This EIP is for field moduli less than <code>2^{256}</code>. This covers many of the popular curves while still having all parameters fit in a single EVM word.</p> <p>TODO: Consider a double-word version. 512 bits would cover all known curves except E-521. In particular it will cover the NIST P-384 curve used by the Estonian e-Identity and the BLS12-381 curve used by <a rel="external" href="https://z.cash/blog/new-snark-curve/">ZCash Sappling</a>.</p> <p><strong>Short Weierstrass Curves.</strong> This EIP is for fields specified in short Weierstrass form. While any curve can be converted to short Weierstrass form through a <a rel="external" href="https://safecurves.cr.yp.to/equation.html">substitution of variables</a>, this misses out on the performance advantages of those specific forms.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h2 id="test-cases">Test Cases</h2> <h2 id="implementation">Implementation</h2> <p>There will be a reference implementation in Rust based on the existing libraries (in particular those by ZCash and The Matter Inc.).</p> <p>The reference implementation will be production grade and compile to a native library with a C api and a webassembly version. Node developers are encouraged to use the reference implementation and can use either the rust library, the native C bindings or the webassembly module. Node developers can of course always decide to implement their own.</p> <h2 id="references">References</h2> <p>This EIP overlaps in scope with</p> <ul> <li><a href="https://wg-eips.ritovision.com/196/">EIP-196</a>: ecadd, ecmul for altbn128</li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/603">EIP issue 603</a>: ecadd, ecmul for SECP256k1.</li> <li><a href="https://wg-eips.ritovision.com/665/">EIP-665</a>: ECDSA verify for ED25519.</li> <li><a href="https://wg-eips.ritovision.com/1108/">EIP-1108</a>: Optimize ecadd and ecmul for altbn128.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-03-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Gabriel Barrosgabriel@terminal.co Patrick Gallagherblockchainbuddha@gmail.com https://wg-eips.ritovision.com/1822/ <h2 id="simple-summary">Simple Summary</h2> <p>Standard upgradeable proxy contract.</p> <h2 id="abstract">Abstract</h2> <p>The following describes a standard for proxy contracts which is universally compatible with all contracts, and does not create incompatibility between the proxy and business-logic contracts. This is achieved by utilizing a unique storage position in the proxy contract to store the Logic Contract's address. A compatibility check ensures successful upgrades. Upgrading can be performed unlimited times, or as determined by custom logic. In addition, a method for selecting from multiple constructors is provided, which does not inhibit the ability to verify bytecode.</p> <h2 id="motivation">Motivation</h2> <ul> <li> <p>Improve upon existing proxy implementations to improve developer experience for deploying and maintaining Proxy and Logic Contracts.</p> </li> <li> <p>Standardize and improve the methods for verifying the bytecode used by the Proxy Contract.</p> </li> </ul> <h2 id="terminology">Terminology</h2> <ul> <li><code>delegatecall()</code> - Function in contract <strong>A</strong> which allows an external contract <strong>B</strong> (delegating) to modify <strong>A</strong>'s storage (see diagram below, <a rel="external" href="https://solidity.readthedocs.io/en/v0.5.3/introduction-to-smart-contracts.html#delegatecall-callcode-and-libraries">Solidity docs</a>)</li> <li><strong>Proxy Contract</strong> - The contract <strong>A</strong> which stores data, but uses the logic of external contract <strong>B</strong> by way of <code>delegatecall()</code>.</li> <li><strong>Logic Contract</strong> - The contract <strong>B</strong> which contains the logic used by Proxy Contract <strong>A</strong></li> <li><strong>Proxiable Contract</strong> - Inherited in Logic Contract <strong>B</strong> to provide the upgrade functionality</li> </ul> <p><img src="https://wg-eips.ritovision.com/1822/./assets/proxy-diagram.png" alt="" /></p> <h2 id="specification">Specification</h2> <p>The Proxy Contract proposed here should be deployed <em>as is</em>, and used as a drop-in replacement for any existing methods of lifecycle management of contracts. In addition to the Proxy Contract, we propose the Proxiable Contract interface/base which establishes a pattern for the upgrade which does not interfere with existing business rules. The logic for allowing upgrades can be implemented as needed.</p> <h3 id="proxy-contract">Proxy Contract</h3> <h4 id="functions">Functions</h4> <h5 id="fallback"><code>fallback</code></h5> <p>The proposed fallback function follows the common pattern seen in other Proxy Contract implementations such as <a rel="external" href="https://github.com/maraoz/solidity-proxy/blob/master/contracts/Dispatcher.sol">Zeppelin</a> or <a rel="external" href="https://blog.gnosis.pm/solidity-delegateproxy-contracts-e09957d0f201">Gnosis</a>.</p> <p>However, rather than forcing use of a variable, the address of the Logic Contract is stored at the defined storage position <code>keccak256("PROXIABLE")</code>. This eliminates the possibility of collision between variables in the Proxy and Logic Contracts, thus providing "universal" compatibility with any Logic Contract.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span>(</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> assembly</span><span> {</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> solium-disable-line</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> contractLogic</span><span class="z-keyword"> :</span><span>= </span><span class="z-entity z-name">sload</span><span>(</span><span class="z-constant">0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> calldatacopy</span><span>(</span><span class="z-constant">0x0</span><span>,</span><span class="z-constant"> 0x0</span><span>,</span><span class="z-variable z-other"> calldatasize</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> success</span><span class="z-keyword"> :</span><span>= </span><span class="z-entity z-name">delegatecall</span><span>(</span><span class="z-entity z-name">sub</span><span>(</span><span class="z-variable">gas</span><span>,</span><span> 10000</span><span>)</span><span>,</span><span class="z-entity z-name"> contractLogic</span><span>,</span><span class="z-constant"> 0x0</span><span>,</span><span class="z-entity z-name"> calldatasize</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> retSz</span><span class="z-keyword"> :</span><span>= </span><span class="z-entity z-name">returndatasize</span></span> <span class="giallo-l"><span class="z-entity z-name"> returndatacopy</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-variable z-other"> retSz</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> switch</span><span class="z-variable z-other"> success</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 0</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> revert</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other"> retSz</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> default</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other"> retSz</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="constructor"><code>constructor</code></h4> <p>The proposed constructor accepts any number of arguments of any type, and thus is compatible with any Logic Contract constructor function.</p> <p>In addition, the arbitrary nature of the Proxy Contract's constructor provides the ability to select from one or more constructor functions available in the Logic Contract source code (e.g., <code>constructor1</code>, <code>constructor2</code>, ... etc. ). Note that if multiple constructors are included in the Logic Contract, a check should be included to prohibit calling a constructor again post-initialization.</p> <p>It's worth noting that the added functionality of supporting multiple constructors does not inhibit verification of the Proxy Contract's bytecode, since the initialization tx call data (input) can be decoded by first using the Proxy Contract ABI, and then using the Logic Contract ABI.</p> <p>The contract below shows the proposed implementation of the Proxy Contract.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> Proxy</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Code position in storage is keccak256(&quot;PROXIABLE&quot;) = &quot;0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> constructor</span><span>(</span><span class="z-variable z-other">bytes</span><span class="z-variable z-other"> memory</span><span class="z-variable z-other"> constructData</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> contractLogic</span><span>)</span><span class="z-variable z-other"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> save the code address</span></span> <span class="giallo-l"><span class="z-variable z-other"> assembly</span><span> {</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> solium-disable-line</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span class="z-constant">0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>,</span><span class="z-variable z-other"> contractLogic</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> (</span><span class="z-variable z-other">bool</span><span class="z-variable z-other"> success</span><span>,</span><span class="z-variable z-other"> bytes</span><span class="z-variable z-other"> memory</span><span class="z-variable z-other"> _</span><span> )</span><span class="z-keyword"> =</span><span class="z-variable z-other"> contractLogic</span><span>.</span><span class="z-entity z-name">delegatecall</span><span>(</span><span class="z-variable z-other">constructData</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> solium-disable-line</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">success</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Construction failed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span>(</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> assembly</span><span> {</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> solium-disable-line</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> contractLogic</span><span class="z-keyword"> :</span><span>= </span><span class="z-entity z-name">sload</span><span>(</span><span class="z-constant">0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> calldatacopy</span><span>(</span><span class="z-constant">0x0</span><span>,</span><span class="z-constant"> 0x0</span><span>,</span><span class="z-variable z-other"> calldatasize</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> success</span><span class="z-keyword"> :</span><span>= </span><span class="z-entity z-name">delegatecall</span><span>(</span><span class="z-entity z-name">sub</span><span>(</span><span class="z-variable">gas</span><span>,</span><span> 10000</span><span>)</span><span>,</span><span class="z-entity z-name"> contractLogic</span><span>,</span><span class="z-constant"> 0x0</span><span>,</span><span class="z-entity z-name"> calldatasize</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> retSz</span><span class="z-keyword"> :</span><span>= </span><span class="z-entity z-name">returndatasize</span></span> <span class="giallo-l"><span class="z-entity z-name"> returndatacopy</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-variable z-other"> retSz</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> switch</span><span class="z-variable z-other"> success</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 0</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> revert</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other"> retSz</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> default</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other"> retSz</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="proxiable-contract">Proxiable Contract</h3> <p>The Proxiable Contract is included in the Logic Contract, and provides the functions needed to perform an upgrade. The compatibility check <code>proxiable</code> prevents irreparable updates during an upgrade.</p> <blockquote> <p>:warning: Warning: <code>updateCodeAddress</code> and <code>proxiable</code> must be present in the Logic Contract. Failure to include these may prevent upgrades, and could allow the Proxy Contract to become entirely unusable. See below <a href="https://wg-eips.ritovision.com/1822/#restricting-dangerous-functions">Restricting dangerous functions</a></p> </blockquote> <h4 id="functions-1">Functions</h4> <h5 id="proxiable"><code>proxiable</code></h5> <p>Compatibility check to ensure the new Logic Contract implements the Universal Upgradeable Proxy Standard. Note that in order to support future implementations, the <code>bytes32</code> comparison could be changed e.g., <code>keccak256("PROXIABLE-ERC1822-v1")</code>.</p> <h5 id="updatecodeaddress"><code>updateCodeAddress</code></h5> <p>Stores the Logic Contract's address at storage <code>keccak256("PROXIABLE")</code> in the Proxy Contract.</p> <p>The contract below shows the proposed implementation of the Proxiable Contract.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> Proxiable</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Code position in storage is keccak256(&quot;PROXIABLE&quot;) = &quot;0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateCodeAddress</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> newAddress</span><span>)</span><span class="z-entity z-name"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> bytes32</span><span>(</span><span class="z-constant">0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>)</span><span class="z-keyword"> ==</span><span class="z-entity z-name"> Proxiable</span><span>(</span><span class="z-variable z-other">newAddress</span><span>)</span><span>.</span><span class="z-entity z-name">proxiableUUID</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Not compatible</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> assembly</span><span> {</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> solium-disable-line</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span class="z-constant">0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>,</span><span class="z-variable z-other"> newAddress</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> proxiableUUID</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> pure</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="pitfalls-when-using-a-proxy">Pitfalls when using a proxy</h2> <p>The following common best practices should be employed for all Logic Contracts when using a proxy contract.</p> <h3 id="separating-variables-from-logic">Separating Variables from Logic</h3> <p>Careful consideration should be made when designing a new Logic Contract to prevent incompatibility with the existing storage of the Proxy Contract after an upgrade. Specifically, the order in which variables are instantiated in the new contract should not be modified, and any new variables should be added after all existing variables from the previous Logic Contract</p> <p>To facilitate this practice, we recommend utilizing a single "base" contract which holds all variables, and which is inherited in subsequent logic contract(s). This practice greatly reduces the chances of accidentally reordering variables or overwriting them in storage.</p> <h3 id="restricting-dangerous-functions">Restricting dangerous functions</h3> <p>The compatibility check in the Proxiable Contract is a safety mechanism to prevent upgrading to a Logic Contract which does not implement the Universal Upgradeable Proxy Standard. However, as occurred in the parity wallet hack, it is still possible to perform irreparable damage to the Logic Contract itself.</p> <p>In order to prevent damage to the Logic Contract, we recommend restricting permissions for any potentially damaging functions to <code>onlyOwner</code>, and giving away ownership of the Logic Contract immediately upon deployment to a null address (e.g., address(1)). Potentially damaging functions include native functions such as <code>SELFDESTRUCT</code>, as well functions whose code may originate externally such as <code>CALLCODE</code>, and <code>delegatecall()</code>. In the <a href="https://wg-eips.ritovision.com/1822/#erc-20-token">ERC-20 Token</a> example below, a <code>LibraryLock</code> contract is used to prevent destruction of the logic contract.</p> <h2 id="examples">Examples</h2> <h3 id="owned">Owned</h3> <p>In this example, we show the standard ownership example, and restrict the <code>updateCodeAddress</code> to only the owner.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> Owned</span><span class="z-variable z-other"> is</span><span class="z-variable z-other"> Proxiable</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ensures no one can manipulate this contract once it is deployed</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> public</span><span class="z-variable z-other"> owner</span><span class="z-keyword"> =</span><span class="z-entity z-name"> address</span><span>(</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> constructor1</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ensures this can be called only once per *proxy* contract deployed</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">owner</span><span class="z-keyword"> ==</span><span class="z-entity z-name"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> owner</span><span class="z-keyword"> =</span><span class="z-variable z-other"> msg</span><span>.</span><span class="z-variable z-other">sender</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateCode</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> newCode</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> updateCodeAddress</span><span>(</span><span class="z-variable z-other">newCode</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> modifier</span><span class="z-entity z-name"> onlyOwner</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span class="z-keyword"> ==</span><span class="z-variable z-other"> owner</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Only owner is allowed to perform this action</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="erc-20-token">ERC-20 Token</h3> <h4 id="proxy-contract-1">Proxy Contract</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">pragma</span><span class="z-variable z-other"> solidity</span><span class="z-keyword"> ^</span><span class="z-constant">0</span><span class="z-constant">.</span><span class="z-constant">5</span><span>.</span><span class="z-constant">1</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> Proxy</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Code position in storage is keccak256(&quot;PROXIABLE&quot;) = &quot;0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> constructor</span><span>(</span><span class="z-variable z-other">bytes</span><span class="z-variable z-other"> memory</span><span class="z-variable z-other"> constructData</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> contractLogic</span><span>)</span><span class="z-variable z-other"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> save the code address</span></span> <span class="giallo-l"><span class="z-variable z-other"> assembly</span><span> {</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> solium-disable-line</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span class="z-constant">0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>,</span><span class="z-variable z-other"> contractLogic</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> (</span><span class="z-variable z-other">bool</span><span class="z-variable z-other"> success</span><span>,</span><span class="z-variable z-other"> bytes</span><span class="z-variable z-other"> memory</span><span class="z-variable z-other"> _</span><span> )</span><span class="z-keyword"> =</span><span class="z-variable z-other"> contractLogic</span><span>.</span><span class="z-entity z-name">delegatecall</span><span>(</span><span class="z-variable z-other">constructData</span><span>)</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> solium-disable-line</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">success</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Construction failed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span>(</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> assembly</span><span> {</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> solium-disable-line</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> contractLogic</span><span class="z-keyword"> :</span><span>= </span><span class="z-entity z-name">sload</span><span>(</span><span class="z-constant">0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> calldatacopy</span><span>(</span><span class="z-constant">0x0</span><span>,</span><span class="z-constant"> 0x0</span><span>,</span><span class="z-variable z-other"> calldatasize</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> success</span><span class="z-keyword"> :</span><span>= </span><span class="z-entity z-name">delegatecall</span><span>(</span><span class="z-entity z-name">sub</span><span>(</span><span class="z-variable">gas</span><span>,</span><span> 10000</span><span>)</span><span>,</span><span class="z-entity z-name"> contractLogic</span><span>,</span><span class="z-constant"> 0x0</span><span>,</span><span class="z-entity z-name"> calldatasize</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> retSz</span><span class="z-keyword"> :</span><span>= </span><span class="z-entity z-name">returndatasize</span></span> <span class="giallo-l"><span class="z-entity z-name"> returndatacopy</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-variable z-other"> retSz</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> switch</span><span class="z-variable z-other"> success</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 0</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> revert</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other"> retSz</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> default</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other"> retSz</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="token-logic-contract">Token Logic Contract</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> Proxiable</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Code position in storage is keccak256(&quot;PROXIABLE&quot;) = &quot;0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateCodeAddress</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> newAddress</span><span>)</span><span class="z-entity z-name"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> bytes32</span><span>(</span><span class="z-constant">0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>)</span><span class="z-keyword"> ==</span><span class="z-entity z-name"> Proxiable</span><span>(</span><span class="z-variable z-other">newAddress</span><span>)</span><span>.</span><span class="z-entity z-name">proxiableUUID</span><span>(</span><span>)</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Not compatible</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> assembly</span><span> {</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> solium-disable-line</span></span> <span class="giallo-l"><span class="z-entity z-name"> sstore</span><span>(</span><span class="z-constant">0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>,</span><span class="z-variable z-other"> newAddress</span><span>)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> proxiableUUID</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> pure</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0xc5f16f0fcc639fa48a6947836d9850f504798523bf8c9a3a87d5876cf622bcf7</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> Owned</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> owner</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setOwner</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _owner</span><span>)</span><span class="z-entity z-name"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> owner</span><span class="z-keyword"> =</span><span class="z-variable z-other"> _owner</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> modifier</span><span class="z-entity z-name"> onlyOwner</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span class="z-keyword"> ==</span><span class="z-variable z-other"> owner</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Only owner is allowed to perform this action</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> LibraryLockDataLayout</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> bool</span><span class="z-variable z-other"> public</span><span class="z-variable z-other"> initialized</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> LibraryLock</span><span class="z-variable z-other"> is</span><span class="z-variable z-other"> LibraryLockDataLayout</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Ensures no one can manipulate the Logic Contract once it is deployed.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> PARITY WALLET HACK PREVENTION</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> modifier</span><span class="z-entity z-name"> delegatedOnly</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">initialized</span><span class="z-keyword"> ==</span><span class="z-constant"> true</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The library is locked. No direct &#39;call&#39; is allowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initialize</span><span>(</span><span>)</span><span class="z-entity z-name"> internal</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> initialized</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> ERC20DataLayout</span><span class="z-variable z-other"> is</span><span class="z-variable z-other"> LibraryLockDataLayout</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> public</span><span class="z-variable z-other"> totalSupply</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> mapping</span><span>(</span><span class="z-variable">address</span><span class="z-storage z-type">=&gt;</span><span class="z-variable z-other">uint256</span><span>)</span><span class="z-variable z-other"> public</span><span class="z-variable z-other"> tokens</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other z-constant"> ERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ...</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">tokens</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span class="z-keyword"> &gt;=</span><span class="z-variable z-other"> amount</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Not enough funds for transfer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> tokens</span><span>[</span><span class="z-variable z-other">to</span><span>]</span><span class="z-keyword"> +=</span><span class="z-variable z-other"> amount</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> tokens</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span class="z-keyword"> -=</span><span class="z-variable z-other"> amount</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> MyToken</span><span class="z-variable z-other"> is</span><span class="z-variable z-other"> ERC20DataLayout</span><span>,</span><span class="z-variable z-other z-constant"> ERC20</span><span>,</span><span class="z-variable z-other"> Owned</span><span>,</span><span class="z-variable z-other"> Proxiable</span><span>,</span><span class="z-variable z-other"> LibraryLock</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> constructor1</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _initialSupply</span><span>)</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> totalSupply</span><span class="z-keyword"> =</span><span class="z-variable z-other"> _initialSupply</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> tokens</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> _initialSupply</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> initialize</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> setOwner</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateCode</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> newCode</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> delegatedOnly</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> updateCodeAddress</span><span>(</span><span class="z-variable z-other">newCode</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> amount</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> delegatedOnly</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-constant"> ERC20</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span class="z-variable z-other">to</span><span>,</span><span class="z-variable z-other"> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="references">References</h2> <ul> <li><a rel="external" href="https://medium.com/terminaldotco/escape-hatch-proxy-efb681de108d">"Escape-hatch" proxy Medium Post</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-03-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Pelle Braendgaardhttps://github.com/pelle https://wg-eips.ritovision.com/1812/ <h1 id="ethereum-verifiable-claims">Ethereum Verifiable Claims</h1> <h2 id="simple-summary">Simple Summary</h2> <p>Reusable Verifiable Claims using <a href="https://wg-eips.ritovision.com/712/">EIP 712 Signed Typed Data</a>.</p> <h2 id="abstract">Abstract</h2> <p>A new method for Off-Chain Verifiable Claims built on <a href="https://wg-eips.ritovision.com/712/">EIP-712</a>. These Claims can be issued by any user with a EIP 712 compatible web3 provider. Claims can be stored off chain and verified on-chain by Solidity Smart Contracts, State Channel Implementations or off-chain libraries.</p> <h2 id="motivation">Motivation</h2> <p>Reusable Off-Chain Verifiable Claims provide an important piece of integrating smart contracts with real world organizational requirements such as meeting regulatory requirements such as KYC, GDPR, Accredited Investor rules etc.</p> <p><a rel="external" href="https://github.com/ethereum/EIPs/issues/735">ERC-735</a> and <a rel="external" href="https://github.com/ethereum/EIPs/issues/780">ERC-780</a> provide methods of making claims that live on chain. This is useful for some particular use cases, where some claim about an address must be verified on chain.</p> <p>In most cases though it is both dangerous and in some cases illegal (according to EU GDPR rules for example) to record Identity Claims containing Personal Identifying Information (PII) on an immutable public database such as the Ethereum blockchain.</p> <p>The W3C <a rel="external" href="https://www.w3.org/TR/verifiable-claims-data-model/">Verifiable Claims Data Model and Representations</a> as well as uPorts <a rel="external" href="https://developer.uport.me/messages/verification">Verification Message Spec</a> are proposed off-chain solutions.</p> <p>While built on industry standards such as <a rel="external" href="https://json-ld.org">JSON-LD</a> and <a rel="external" href="https://jwt.io">JWT</a> neither of them are easy to integrate with the Ethereum ecosystem.</p> <p><a href="https://wg-eips.ritovision.com/712/">EIP-712</a> introduces a new method of signing off chain Identity data. This provides both a data format based on Solidity ABI encoding that can easily be parsed on-chain an a new JSON-RPC call that is easily supported by existing Ethereum wallets and Web3 clients.</p> <p>This format allows reusable off-chain Verifiable Claims to be cheaply issued to users, who can present them when needed.</p> <h2 id="prior-art">Prior Art</h2> <p>Verified Identity Claims such as those proposed by <a rel="external" href="https://developer.uport.me/messages/verification">uPort</a> and <a rel="external" href="https://www.w3.org/2017/vc/WG/">W3C Verifiable Claims Working Group</a> form an important part of building up reusable identity claims.</p> <p><a rel="external" href="https://github.com/ethereum/EIPs/issues/735">ERC-735</a> and <a rel="external" href="https://github.com/ethereum/EIPs/issues/780">ERC-780</a> provide on-chain storage and lookups of Verifiable Claims.</p> <h2 id="specification">Specification</h2> <h3 id="claims">Claims</h3> <p>Claims can be generalized like this:</p> <blockquote> <p>Issuer makes the claim that Subject is something or has some attribute and value.</p> </blockquote> <p>Claims should be deterministic, in that the same claim signed multiple times by the same signer.</p> <h3 id="claims-data-structure">Claims data structure</h3> <p>Each claim should be typed based on its specific use case, which EIP 712 lets us do effortlessly. But there are 3 minimal attributes required of the claims structure.</p> <ul> <li><code>subject</code> the subject of the claim as an <code>address</code> (who the claim is about)</li> <li><code>validFrom</code> the time in seconds encoded as a <code>uint256</code> of start of validity of claim. In most cases this would be the time of issuance, but some claims may be valid in the future or past.</li> <li><code>validTo</code> the time in seconds encoded as a <code>uint256</code> of when the validity of the claim expires. If you intend for the claim not to expire use <code>0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff</code>.</li> </ul> <p>The basic minimal claim data structure as a Solidity struct:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span> [</span><span>CLAIM TYPE</span><span>]</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The CLAIM TYPE is the actual name of the claim. While not required, in most cases use the taxonomy developed by <a rel="external" href="https://schema.org/docs/full.html">schema.org</a> which is also commonly used in other Verifiable Claims formats.</p> <p>Example claim that issuer knows a subject:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Know</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="presenting-a-verifiable-claim">Presenting a Verifiable Claim</h3> <h4 id="verifying-contract">Verifying Contract</h4> <p>When defining Verifiable Claims formats a Verifying Contract should be created with a public <code>verify()</code> view function. This makes it very easy for other smart contracts to verify a claim correctly.</p> <p>It also provides a convenient interface for web3 and state channel apps to verify claims securely.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> verifyIssuer</span><span>(</span><span class="z-storage z-type">Know</span><span class="z-storage z-type"> memory</span><span class="z-variable"> claim</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> digest </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;\x19\x01&quot;</span><span>,</span></span> <span class="giallo-l"><span> DOMAIN_SEPARATOR</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> hash</span><span>(</span><span>claim</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> (</span><span>claim</span><span>.</span><span>validFrom </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span class="z-variable z-language"> block</span><span>.</span><span>timestamp</span><span>)</span><span class="z-keyword"> &amp;&amp;</span><span> (</span><span class="z-variable z-language">block</span><span>.</span><span>timestamp </span><span class="z-keyword">&lt;</span><span> claim</span><span>.</span><span>validTo</span><span>)</span></span> <span class="giallo-l"><span>,</span><span class="z-string"> &quot;invalid issuance timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> ecrecover</span><span>(</span><span>digest</span><span>,</span><span> v</span><span>,</span><span> r</span><span>,</span><span> s</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="calling-a-smartcontract-function">Calling a SmartContract function</h4> <p>Verifiable Claims can be presented to a solidity function call as it’s struct together with the <code>v</code>, <code>r</code> and <code>s</code> signature components.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> vouch</span><span>(</span><span class="z-storage z-type">Know</span><span class="z-storage z-type"> memory</span><span class="z-variable"> claim</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> issuer </span><span class="z-keyword">=</span><span> verifier</span><span>.</span><span class="z-entity z-name">verifyIssuer</span><span>(</span><span>claim</span><span>,</span><span> v</span><span>,</span><span> r</span><span>,</span><span> s</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>issuer </span><span class="z-keyword">!=</span><span class="z-keyword">=</span><span class="z-string"> &#39;0x0&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> knows</span><span>[</span><span>issuer</span><span>]</span><span>[</span><span>claim</span><span>.</span><span>subject</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> block</span><span>.</span><span>number</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="embedding-a-verifiable-claim-in-another-signed-typed-data-structure">Embedding a Verifiable Claim in another Signed Typed Data structure</h4> <p>The Claim struct should be embedded in another struct together with the <code>v</code>, <code>r</code> and <code>s</code> signature parameters.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Know</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> VerifiableReference</span><span> {</span></span> <span class="giallo-l"><span> Know delegate</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> v</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> r</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> s</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Introduction</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> recipient</span><span>;</span></span> <span class="giallo-l"><span> VerifiableReference issuer</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Each Verifiable Claim should be individually verified together with the parent Signed Typed Data structure.</p> <p>Verifiable Claims issued to different EIP 712 Domains can be embedded within each other.</p> <h4 id="state-channels">State Channels</h4> <p>This proposal will not show how to use Eth Verifiable Claims as part of a specific State Channel method.</p> <p>Any State Channel based on EIP712 should be able to include the embeddable Verifiable Claims as part of its protocol. This could be useful for exchanging private Identity Claims between the parties for regulatory reasons, while ultimately not posting them to the blockchain on conclusion of a channel.</p> <h3 id="key-delegation">Key Delegation</h3> <p>In most simple cases the issuer of a Claim is the signer of the data. There are cases however where signing should be delegated to an intermediary key.</p> <p>KeyDelegation can be used to implement off chain signing for smart contract based addresses, server side key rotation as well as employee permissions in complex business use cases.</p> <h4 id="erc1056-signing-delegation">ERC1056 Signing Delegation</h4> <p><a href="https://wg-eips.ritovision.com/1056/">ERC-1056</a> provides a method for addresses to assign delegate signers. One of the primary use cases for this is that a smart contract can allow a key pair to sign on its behalf for a certain period. It also allows server based issuance tools to institute key rotation.</p> <p>To support this an additional <code>issuer</code> attribute can be added to the Claim Type struct. In this case the verification code should lookup the EthereumDIDRegistry to see if the signer of the data is an allowed signing delegate for the <code>issuer</code></p> <p>The following is the minimal struct for a Claim containing an issuer:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span> [</span><span>CLAIM TYPE</span><span>]</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>If the <code>issuer</code> is specified in the struct In addition to performing the standard ERC712 verification the verification code MUST also verify that the signing address is a valid <code>veriKey</code> delegate for the address specified in the issuer.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>registry</span><span>.</span><span class="z-entity z-name">validDelegate</span><span>(</span><span>issuer</span><span>,</span><span class="z-string"> &#39;veriKey&#39;</span><span>,</span><span> recoveredAddress</span><span>)</span></span></code></pre><h4 id="embedded-delegation-proof">Embedded Delegation Proof</h4> <p>There may be applications, in particularly where organizations want to allow delegates to issue claims about specific domains and types.</p> <p>For this purpose instead of the <code>issuer</code> we allow a special claim to be embedded following this same format:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Delegate</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> VerifiableDelegate</span><span> {</span></span> <span class="giallo-l"><span> Delegate delegate</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> v</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> r</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> s</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">struct</span><span> [</span><span>CLAIM TYPE</span><span>]</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span> VerifiedDelegate issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Delegates should be created for specific EIP 712 Domains and not be reused across Domains.</p> <p>Implementers of new EIP 712 Domains can add further data to the <code>Delegate</code> struct to allow finer grained application specific rules to it.</p> <h3 id="claim-types">Claim Types</h3> <h4 id="binary-claims">Binary Claims</h4> <p>A Binary claim is something that doesn’t have a particular value. It either is issued or not.</p> <p>Examples:</p> <ul> <li>subject is a Person</li> <li>subject is my owner (eg. Linking an ethereum account to an owner identity)</li> </ul> <p>Example:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Person</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This is exactly the same as the minimal claim above with the CLAIM TYPE set to <a rel="external" href="https://schema.org/Person">Person</a>.</p> <h3 id="value-claims">Value Claims</h3> <p>Value claims can be used to make a claim about the subject containing a specific readable value.</p> <p><strong>WARNING</strong>: Be very careful about using Value Claims as part of Smart Contract transactions. Identity Claims containing values could be a GDPR violation for the business or developer encouraging a user to post it to a public blockchain.</p> <p>Examples:</p> <ul> <li>subject’s name is Alice</li> <li>subjects average account balance is 1234555</li> </ul> <p>Each value should use the <code>value</code> field to indicate the value.</p> <p>A Name Claim</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Name</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Average Balance</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> AverageBalance</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> value</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="hashed-claims">Hashed Claims</h3> <p>Hashed claims can be used to make a claim about the subject containing the hash of a claim value. Hashes should use ethereum standard <code>keccak256</code> hashing function.</p> <p><strong>WARNING</strong>: Be very careful about using Hashed Claims as part of Smart Contract transactions. Identity Claims containing hashes of known values could be a GDPR violation for the business or developer encouraging a user to post it to a public blockchain.</p> <p>Examples:</p> <ul> <li><input disabled="" type="checkbox"/> hash of subject’s name is <code>keccak256(“Alice Torres”)</code></li> <li><input disabled="" type="checkbox"/> hash of subject’s email is <code>keccak256(“alice@example.com”)</code></li> </ul> <p>Each value should use the <code>keccak256 </code> field to indicate the hashed value. Question. The choice of using this name is that we can easily add support for future algorithms as well as maybe zkSnark proofs.</p> <p>A Name Claim</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Name</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-support"> keccak256</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Email Claim</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Email</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> subject</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-support"> keccak256</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="eip-712-domain">EIP 712 Domain</h3> <p>The EIP 712 Domain specifies what kind of message that is to be signed and is used to differentiate between signed data types. The content MUST contain the following:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> name</span><span class="z-keyword">:</span><span class="z-string"> &quot;EIP1???Claim&quot;</span><span>,</span></span> <span class="giallo-l"><span> version</span><span class="z-keyword">:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span> chainId</span><span class="z-keyword">:</span><span class="z-constant"> 1</span><span>,</span><span class="z-comment"> //</span><span class="z-comment"> for mainnet</span></span> <span class="giallo-l"><span> verifyingContract</span><span class="z-keyword">:</span><span class="z-constant"> 0</span><span>x </span><span class="z-comment">//</span><span class="z-comment"> TBD</span></span> <span class="giallo-l"><span> salt</span><span class="z-keyword">:</span><span> .</span><span>.</span><span>.</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="full-combined-format-for-eip-712-signing">Full Combined format for EIP 712 signing:</h4> <p>Following the EIP 712 standard we can combine the Claim Type with the EIP 712 Domain and the claim itself (in the <code>message</code>) attribute.</p> <p>Eg:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;types&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;EIP712Domain&quot;</span><span class="z-keyword">:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;name&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;version&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;chainId&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;uint256&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;verifyingContract&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;address&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;Email&quot;</span><span class="z-keyword">:</span><span> [</span></span> <span class="giallo-l"><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;subject&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;address&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;keccak256&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;bytes32&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;validFrom&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;uint256&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;validTo&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;uint256&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;primaryType&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Email&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;domain&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;EIP1??? Claim&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;version&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;1&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;chainId&quot;</span><span class="z-keyword">:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;verifyingContract&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;message&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;subject&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;0x5792e817336f41de1d8f54feab4bc200624a1d9d&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;value&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;9c8465d9ae0b0bc167dee7f62880034f59313100a638dcc86a901956ea52e280&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;validFrom&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;0x0000000000000000000000000000000000000000000000000001644b74c2a0&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;validTo&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;0xfffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h3 id="revocation">Revocation</h3> <p>Both Issuers and Subjects should be allowed to revoke Verifiable Claims. Revocations can be handled through a simple on-chain registry.</p> <p>The ultimate rules of who should be able to revoke a claim is determined by the Verifying contract.</p> <p>The <code>digest</code> used for revocation is the EIP712 Signed Typed Data digest.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> RevocationRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span> (</span><span class="z-support">bytes32</span><span class="z-keyword"> =&gt;</span><span class="z-storage z-type"> mapping</span><span> (</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint</span><span>)</span><span>)</span><span class="z-storage z-type"> public</span><span> revocations</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revoke</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> digest</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> revocations</span><span>[</span><span>digest</span><span>]</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-language"> block</span><span>.</span><span>number</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revoked</span><span>(</span><span class="z-support">address</span><span class="z-variable"> party</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> digest</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> revocations</span><span>[</span><span>digest</span><span>]</span><span>[</span><span>party</span><span>]</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A verifying contract can query the Revocation Registry as such:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes32</span><span> digest </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span></span> <span class="giallo-l"><span class="z-string"> &quot;\x19\x01&quot;</span><span>,</span></span> <span class="giallo-l"><span> DOMAIN_SEPARATOR</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> hash</span><span>(</span><span>claim</span><span>)</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span class="z-entity z-name">valid</span><span>(</span><span>claim</span><span>.</span><span>validFrom</span><span>,</span><span> claim</span><span>.</span><span>validTo</span><span>)</span><span>,</span><span class="z-string"> &quot;invalid issuance timestamps&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support">address</span><span> issuer </span><span class="z-keyword">=</span><span class="z-support"> ecrecover</span><span>(</span><span>digest</span><span>,</span><span> v</span><span>,</span><span> r</span><span>,</span><span> s</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span class="z-keyword">!</span><span>revocations</span><span>.</span><span class="z-entity z-name">revoked</span><span>(</span><span>issuer</span><span>,</span><span> digest</span><span>)</span><span>,</span><span class="z-string"> &quot;claim was revoked by issuer&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">require</span><span>(</span><span class="z-keyword">!</span><span>revocations</span><span>.</span><span class="z-entity z-name">revoked</span><span>(</span><span>claim</span><span>.</span><span>subject</span><span>,</span><span> digest</span><span>)</span><span>,</span><span class="z-string"> &quot;claim was revoked by subject&quot;</span><span>)</span><span>;</span></span></code></pre><h3 id="creation-of-verifiable-claims-domains">Creation of Verifiable Claims Domains</h3> <p>Creating specific is Verifiable Claims Domains is out of the scope of this EIP. The Example Code has a few examples.</p> <p>EIP’s or another process could be used to standardize specific important Domains that are universally useful across the Ethereum world.</p> <h2 id="rationale">Rationale</h2> <p>Signed Typed Data provides a strong foundation for Verifiable Claims that can be used in many different kinds of applications built on both Layer 1 and Layer 2 of Ethereum.</p> <h3 id="rationale-for-using-not-using-a-single-eip-712-domain">Rationale for using not using a single EIP 712 Domain</h3> <p>EIP712 supports complex types and domains in itself, that we believe are perfect building blocks for building Verifiable Claims for specific purposes.</p> <p>The Type and Domain of a Claim is itself an important part of a claim and ensures that Verifiable Claims are used for the specific purposes required and not misused.</p> <p>EIP712 Domains also allow rapid experimentation, allowing taxonomies to be built up by the community.</p> <h2 id="test-cases">Test Cases</h2> <p>There is a repo with a few example verifiers and consuming smart contracts written in Solidity:</p> <p><strong>Example Verifiers</strong></p> <ul> <li><a rel="external" href="https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/IdentityClaimsVerifier.sol">Verifier for very simple IdVerification Verifiable Claims containing minimal Personal Data</a></li> <li><a rel="external" href="https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/OwnershipProofVerifier.sol">Verifier for OwnershipProofs signed by a users wallet</a></li> </ul> <p><strong>Example Smart Contracts</strong></p> <ul> <li><a rel="external" href="https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/KYCCoin.sol">KYCCoin.sol</a> - Example Token allows reusable IdVerification claims issued by trusted verifiers and users to whitelist their own addresses using OwnershipProofs</li> <li><a rel="external" href="https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/ConsortiumAgreements.sol">ConsortiumAgreement.sol</a> - Example Consortium Agreement smart contract. Consortium Members can issue Delegated Claims to employees or servers to interact on their behalf.</li> </ul> <p><strong>Shared Registries</strong></p> <ul> <li><a rel="external" href="https://github.com/uport-project/eip712-claims-experiments/blob/master/contracts/RevocationRegistry.sol">RevocationRegistry.sol</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-02-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Shane Jonashttps://github.com/shanejonas Zachary Belfordhttps://github.com/belfordz https://wg-eips.ritovision.com/1901/ <h2 id="abstract">Abstract</h2> <h3 id="what-is-this">What is this?</h3> <p>This is a proposal to add <a rel="external" href="https://github.com/open-rpc/spec">OpenRPC</a> support to existing and future JSON-RPC services by adding the method <a rel="external" href="https://github.com/open-rpc/spec#service-discovery-method"><code>rpc.discover</code></a> to the projects <a rel="external" href="https://www.jsonrpc.org/specification">JSON-RPC</a> APIs, enabling automation and tooling.</p> <p>The OpenRPC Document and generated Documentation that specifies all the methods an EVM-based blockchain should implement can be found <a rel="external" href="https://github.com/etclabscore/ethereum-json-rpc-specification">here</a>.</p> <p>This was first proposed <a rel="external" href="https://github.com/etclabscore/ECIPs/blob/master/ECIPs/../01053.md">here as an ECIP</a>, but the benefits of this kind of tooling is apparent across Bitcoin, Ethereum Classic, Ethereum and other JSON-RPC accessible blockchains.</p> <h2 id="motivation">Motivation</h2> <p>Although <a href="https://wg-eips.ritovision.com/1474/">EIP-1474</a> outlines a JSON-RPC specification. Ethereum still lacks a machine-readable JSON-RPC Specification that can be used as the industry standard for tooling. This proposal attempts to standardize such a specification in a way that is versionable, and both human and machine readable.</p> <p>Ethereum clients can expose RPC endpoints with different method signatures and cause compatibility issues between clients.</p> <p>Developers need a reliable developer experience, and an industry standard way to describe Ethereum JSON-RPC 2.0 APIs.</p> <h2 id="specification">Specification</h2> <h3 id="what-is-openrpc">What is OpenRPC?</h3> <p>The <a rel="external" href="https://github.com/open-rpc/spec">OpenRPC</a> Specification defines a standard, programming language-agnostic interface description for <a rel="external" href="https://www.jsonrpc.org/specification">JSON-RPC 2.0</a> APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenRPC, a consumer can understand and interact with the remote service with a minimal amount of implementation logic, and share these logic patterns across use cases. Similar to what interface descriptions have done for lower-level programming, the OpenRPC Specification removes guesswork in calling a service.</p> <h5 id="structure">Structure</h5> <p>This is the structure of an OpenRPC Document:</p> <p><img src="https://wg-eips.ritovision.com/1901/./assets/OpenRPC_structure.png" alt="openrpc-spec-structure" /></p> <p>JSON-RPC APIs can support the OpenRPC specification by implementing a service discovery method that will return the <a rel="external" href="https://github.com/open-rpc/spec#openrpc-document">OpenRPC document</a> for the JSON-RPC API. The method MUST be named <code>rpc.discover</code>. The <code>rpc.</code> prefix is a reserved method prefix for <a rel="external" href="https://www.jsonrpc.org/specification">JSON-RPC 2.0 Specification</a> system extensions.</p> <h3 id="use-case">Use Case</h3> <p>This is the vision for the use case of OpenRPC and how it would relate to a client implementation like multi-geth:</p> <p><img src="https://wg-eips.ritovision.com/1901/./assets/multi-geth-use-case.png" alt="MultGethRpc-usecase" /></p> <h2 id="rationale">Rationale</h2> <h3 id="why-would-we-do-this">Why would we do this?</h3> <p>Services need to figure out how to talk to each other. If we really want to build the next generation of automation, then having up to date libraries, documented APIs, and modern tools are going to provide easy discovery, on-boarding, and enable end user and developer interaction.</p> <p>Use cases for machine-readable <a rel="external" href="https://www.jsonrpc.org/specification">JSON-RPC 2.0</a> API definition documents include, but are not limited to:</p> <ul> <li>A common vocabulary and document will keep developers, testers, architects, and technical writers all in sync.</li> <li>Server stubs/skeletons generated in many languages</li> <li>Clients generated in many languages</li> <li>Mock Server generated in many languages</li> <li>Tests generated in many languages</li> <li>Documentation Generation</li> </ul> <h3 id="alternative">Alternative</h3> <p><a rel="external" href="https://github.com/open-rpc/spec">OpenRPC</a> documents just describe <a rel="external" href="https://www.jsonrpc.org/specification">JSON-RPC</a> APIs services, and are represented in JSON format. These documents may be produced and served statically OR generated dynamically from an application and returned via the <a rel="external" href="https://github.com/open-rpc/spec#service-discovery-method"><code>rpc.discover</code></a> method. This gives projects and communities the opportunity to adopt tools, documentation, and clients outlined in the <a href="https://wg-eips.ritovision.com/1474/">etclabscore/ethereum-json-rpc-specification</a> before the <a rel="external" href="https://github.com/open-rpc/spec#service-discovery-method"><code>rpc.discover</code></a> method is implemented for a particular client.</p> <h2 id="implementation">Implementation</h2> <ul> <li><a rel="external" href="https://github.com/multi-geth/multi-geth#openrpc-discovery">Multi-Geth OpenRPC Discovery</a></li> </ul> <h3 id="tooling">Tooling</h3> <h4 id="interactive-documentation-playground">Interactive Documentation Playground</h4> <p>You can view the interactive documentation <a rel="external" href="https://playground.open-rpc.org/?schemaUrl=https://raw.githubusercontent.com/etclabscore/ethereum-json-rpc-specification/master/openrpc.json">here</a>.</p> <p><strong>OR</strong></p> <p>Using <code>rpc.discover</code> via multi-geth, the playground can discover and display the documentation for the Ethereum JSON-RPC API:</p> <p><img src="https://wg-eips.ritovision.com/1901/./assets/eth-playground-openrpc.gif" alt="eth-playground-openrpc" /></p> <h4 id="generated-client">Generated Client</h4> <p>The <a rel="external" href="https://github.com/etclabscore/ethereum-json-rpc-specification#clients">clients</a> are generated from the OpenRPC Document openrpc.json outlined in this EIP, and can be used as an alternative to web3.js or ethers.js but for various languages:</p> <p><img src="https://wg-eips.ritovision.com/1901/./assets/eth-generated-client-openrpc.gif" alt="eth-generated-client-openrpc" /></p> <h4 id="mock-server">Mock Server</h4> <p>The <a rel="external" href="https://github.com/open-rpc/mock-server">OpenRPC mock server</a> provides a mock server for any given OpenRPC Document which allows testing without booting up a real network.</p> <p><img src="https://wg-eips.ritovision.com/1901/./assets/inspector-mock-server-openrpc.png" alt="inspector-mock-server-openrpc" /></p> <h2 id="resources">Resources</h2> <ul> <li><a rel="external" href="https://github.com/multi-geth/multi-geth#openrpc-discovery">Multi-Geth OpenRPC Discovery</a></li> <li><a rel="external" href="https://www.youtube.com/watch?v=UgSPMZ9FQ4Q">EDCON 2019 talk on OpenRPC and The Future of JSON-RPC Tooling</a></li> <li><a rel="external" href="https://github.com/etclabscore/ethereum-json-rpc-specification">etclabscore/ethereum-json-rpc-specification</a></li> <li><a rel="external" href="https://open-rpc.org">open-rpc.org</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-02-20T00:00:00+00:00 2026-02-11T14:48:25+00:00 Vincent Elihttps://github.com/Bunjin Dan Finlayhttps://github.com/DanFinlay https://wg-eips.ritovision.com/1775/ <h2 id="simple-summary">Simple Summary</h2> <p>Among others cryptographic applications, scalability and privacy solutions for ethereum blockchain require that an user performs a significant amount of signing operations. It may also require her to watch some state and be ready to sign data automatically (e.g. sign a state or contest a withdraw). The way wallets currently implement accounts poses several obstacles to the development of a complete web3.0 experience both in terms of UX, security and privacy.</p> <p>This proposal describes a standard and api for a new type of wallet accounts that are derived specifically for a each given application. We propose to call them <code>app keys</code>. They allow to isolate the accounts used for each application, thus potentially increasing privacy. They also allow to give more control to the applications developers over account management and signing delegation. For these app keys, wallets can have a more permissive level of security (e.g. not requesting user's confirmation) while keeping main accounts secure. Finally wallets can also implement a different behavior such as allowing to sign transactions without broadcasting them.</p> <p>This new accounts type can allow to significantly improve UX and permit new designs for applications of the crypto permissionned web.</p> <h2 id="abstract">Abstract</h2> <p>In a wallet, an user often holds most of her funds in her main accounts. These accounts require a significant level of security and should not be delegated in any way, this significantly impacts the design of cryptographic applications if a user has to manually confirm every action. Also often an user uses the same accounts across apps, which is a privacy and potentially also a security issue.</p> <p>We introduce here a new account type, app keys, which permits signing delegation and accounts isolation across applications for privacy and security.</p> <p>In this EIP, we provide a proposal on how to uniquely identify and authenticate each application, how to derive a master account (or app key) unique for the domain from an user private key (her root private key or any other private key of an account derived or not from her root one). This EIP aims at becoming a standard on how to derive keys specific to each application that can be regenerated from scratch without further input from the user if she restores her wallet and uses again the application for which this key was derived. These app keys can then be endowed a different set of permissions (through the requestPermission model introduced in <a href="https://wg-eips.ritovision.com/2255/">EIP-2255</a>). This will potentially allow an user to partly trust some apps to perform some crypto operations on their behalf without compromising any security with respect to her main accounts.</p> <h2 id="motivation">Motivation</h2> <p>Wallets developers have agreed on an HD derivation path for ethereum accounts using BIP32, BIP44, SLIP44, <a rel="external" href="https://github.com/ethereum/EIPs/issues/84">(see the discussion here)</a>. Web3 wallets have implemented in a roughly similar way the rpc eth api. <a href="https://wg-eips.ritovision.com/1102/">EIP-1102</a> introduced privacy through non automatic opt-in of a wallet account into an app increasing privacy.</p> <p>However several limitations remain in order to allow for proper design and UX for crypto permissioned apps.</p> <p>Most of GUI based current wallets don't allow to:</p> <ul> <li>being able to automatically and effortlessly use different keys / accounts for each apps,</li> <li>being able to sign some app's action without prompting the user with the same level of security as sending funds from their main accounts,</li> <li>being able to use throwable keys to improve anonymity,</li> <li>effortlessly signing transactions for an app without broadcasting these while still being able to perform other transaction signing as usual from their main accounts,</li> <li>All this while being fully restorable using the user's mnemonic or hardware wallet and the HD Path determined uniquely by the app's ens name.</li> </ul> <p>We try to overcome these limitations by introducing a new account's type, app keys, made to be used along side the existing main accounts.</p> <p>These new app keys can permit to give more power and flexibility to the crypto apps developers. This can allow to improve a lot the UX of crypto dapps and to create new designs that were not possible before leveraging the ability to create and handle many accounts, to presign messages and broadcast them later. These features were not compatible with the level of security we were requesting for main accounts that hold most of an user's funds.</p> <h2 id="specification">Specification</h2> <h3 id="applications">Applications</h3> <p>An app is a website (or other) that would like to request from a wallet to access a cryptographic key specifically derived for this usage. It can be any form of cryptography/identity relying application, Ethereum based but not only.</p> <p>Once connected to a wallet, an application can request to access an account derived exclusively for that application using the following algorithm.</p> <h3 id="private-app-key-generation-algorithm">Private App Key generation algorithm</h3> <p>We now propose an algorithm to generate application keys that:</p> <ul> <li>are uniquely defined, with respect to the account that the user selected to generate these keys,</li> <li>and thus can be isolated when changing the user account, allowing persona management (see next section),</li> <li>are specific to each application,</li> <li>can be fully restored from the user master seed mnemonic and the applications' names.</li> </ul> <h4 id="using-different-accounts-as-personas">Using different accounts as personas</h4> <p>We allow the user to span a different set of application keys by changing the account selected to generate each key. Thus from the same master seed mnemonic, an user can use each of her account index to generate an alternative set of application keys. One can describe this as using different personas. This would allow potentially an user to fully isolate her interaction with a given app across personas. One can use this for instance to create a personal and business profile for a given's domain both backup up from the same mnemonic, using 2 different accounts to generate these. The app or domain, will not be aware that it is the same person and mnemonic behind both. If an application interacts with several main accounts of an user, one of these accounts, a master account can be used as persona and the others as auxiliary accounts.</p> <p>This EIP is agnostic about the way one generates the private keys used to span different app keys spaces. However for compatibility purposes and for clean disambiguation between personas and cryptocurrency accounts, a new EIP, distinct from this one but to be used alongside, will be proposed soon introducing clean persona generation and management.</p> <h4 id="applications-unique-identifiers">Applications' Unique Identifiers</h4> <p>Each application is uniquely defined and authenticated by its origin, a domain string. It can be a Domain Name Service (DNS) name or, in the future, an Ethereum Name Service (ENS) name or IPFS hash.</p> <p>For Ipfs or swam origins, but we could probably use the ipfs or swarm addresses as origin or we could require those to be pointed at through an ENS entry and use the ENS address as origin, although this would mean that the content it refers to could change. It would thus allow for different security and updatibility models.</p> <p>We will probably require for protocol prefixes when using an ENS domain to point to an IPFS address: <code>ens://ipfs.snap.eth</code></p> <h4 id="private-app-key-generation-algorithm-1">Private App Key generation algorithm</h4> <p>Using the domain name of an application, we generate a private key for each application (and per main account) :</p> <p><code>const appKeyPrivKey = keccak256(privKey + originString)</code></p> <p>where <code>+</code> is concatenation, <code>privKey</code> is the private key of the user's account selected to span the application key and <code>originString</code> represents the origin url from which the permission call to access the application key is originated from.</p> <p>This is exposed as an RPC method to allow any domain to request its own app key associated with the current requested account (if available):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>const appKey = await provider.send({</span></span> <span class="giallo-l"><span> method: &#39;wallet_getAppKeyForAccount&#39;,</span></span> <span class="giallo-l"><span> params: [address1]</span></span> <span class="giallo-l"><span>});</span></span></code></pre> <p>See here for an implementation: https://github.com/MetaMask/eth-simple-keyring/blob/master/index.js#L169</p> <h4 id="app-keys-and-hierarchical-deterministic-keys">App keys and Hierarchical Deterministic keys</h4> <p>The app keys generated using the algorithm described in the previous section will not be BIP32 compliant. Therefore apps will not be able to create several app keys or use non-hardening and extended public keys techniques directly. They get a single private key (per origin, per persona). Yet they can use this as initial entropy to span a new HD tree and generate addresses that can be either hardened or not. Thus we should not be losing use cases.</p> <h2 id="rationale">Rationale</h2> <h3 id="sharing-application-keys-across-domains">Sharing application keys across domains:</h3> <p>While this does not explicit cover cases of sharing these app keys between pages on its own, this need can be met by composition:</p> <p>Since a domain would get a unique key per persona, and because domains can intercommunicate, one domain (app) could request another domain (signer) to perform its cryptographic operation on some data, with its appKey as a seed, potentially allowing new signing strategies to be added as easily as new websites.</p> <p>This could also pass it to domains that are loading specific signing strategies. This may sound dangerous at first, but if a domain represents a static hash of a trusted cryptographic function implementation, it could be as safe as calling any audited internal dependency.</p> <h3 id="privacy-and-the-funding-trail">Privacy and the funding trail</h3> <p>If all an application needs to do with its keys is to sign messages and it does not require funding, then this EIP allows for privacy through the use of distinct keys for each application with a simple deterministic standard compatible across wallets.</p> <p>However if these application keys require funding, there can be trail and the use of app keys would not fully solve the privacy problem there.</p> <p>Mixers or anonymous ways of funding an ethereum address (ring signatures) along with this proposal would guarantee privacy.</p> <p>Even if privacy is not solved fully without this anonymous funding method, we still need a way to easily create and restore different accounts/addresses for each application</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>From a wallet point of view, there does not seem to be compatibility issues since these are separate accounts from those that were used previously by wallets and they are supposed to be used along-side in synergy.</p> <p>However, for applications that associated in some way their users to their main accounts may want to reflect on if and how they would like to leverage the power offered by <code>app keys</code> to migrate to them and leverage on the new app designs they permit.</p> <h2 id="implementation">Implementation</h2> <p>Here is an early implementation of app keys for standard (non HW) MetaMask accounts. https://github.com/MetaMask/eth-simple-keyring/blob/6d12bd9d73adcccbe0b0c7e32a99d279085e2934/index.js#L139-L152</p> <p>See here for a fork of MetaMask that implements app keys along side plugins: https://github.com/MetaMask/metamask-snaps-beta https://github.com/MetaMask/metamask-snaps-beta/wiki/Plugin-API</p> <h2 id="example-use-cases">Example use cases</h2> <ul> <li> <p>signing transactions without broadcasting them https://github.com/MetaMask/metamask-extension/issues/3475</p> </li> <li> <p>token contract https://github.com/ethereum/EIPs/issues/85</p> </li> <li> <p>default account for dapps https://ethereum-magicians.org/t/default-accounts-for-dapps/904</p> </li> <li> <p>non wallet/crypto accounts <a href="https://wg-eips.ritovision.com/1581/">EIP1581: Non-wallet usage of keys derived from BIP32 trees</a></p> </li> <li> <p>state channel application</p> </li> <li> <p>privacy solution</p> </li> <li> <p>non custodian cross cryptocurrency exchange...</p> </li> </ul> <h2 id="acknowledgements">Acknowledgements</h2> <p>MetaMask team, Christian Lundkvist, Counterfactual team, Liam Horne, Erik Bryn, Richard Moore, Jeff Coleman.</p> <h2 id="references">References</h2> <h3 id="hd-and-mnemonics">HD and mnemonics</h3> <h4 id="bips">BIPs</h4> <ul> <li> <p><a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki">BIP32: Hierarchical Deterministic Wallets:</a></p> </li> <li> <p><a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki">BIP39: Mnemonic code for generating deterministic keys:</a></p> </li> <li> <p><a rel="external" href="https://github.com/satoshilabs/slips/blob/master/./00044.md">SLIP44: Registered coin types for BIP44</a></p> </li> </ul> <h4 id="derivation-path-for-eth">Derivation path for eth</h4> <ul> <li> <p><a rel="external" href="https://github.com/ethereum/EIPs/issues/84">Issue 84</a></p> </li> <li> <p><a rel="external" href="https://github.com/ethereum/EIPs/issues/85">Issue 85</a></p> </li> <li> <p><a href="https://wg-eips.ritovision.com/600/">EIP600 Ethereum purpose allocation for Deterministic Wallets</a></p> </li> <li> <p><a href="https://wg-eips.ritovision.com/601/">EIP601 Ethereum hierarchy for deterministic wallets</a></p> </li> </ul> <h3 id="previous-proposals-and-discussions-related-to-app-keys">Previous proposals and discussions related to app keys</h3> <ul> <li> <p><a rel="external" href="https://ethereum-magicians.org/t/meta-we-should-value-privacy-more/2475">Meta: we should value privacy more</a></p> </li> <li> <p><a href="https://wg-eips.ritovision.com/1102/">EIP1102: Opt-in account exposure</a></p> </li> <li> <p><a href="https://wg-eips.ritovision.com/1581/">EIP1581: Non-wallet usage of keys derived from BIP-32 trees</a></p> </li> <li> <p><a rel="external" href="https://ethereum-magicians.org/t/non-wallet-usage-of-keys-derived-from-bip-32-trees/1817/4">EIP1581: discussion</a></p> </li> <li> <p><a rel="external" href="https://github.com/satoshilabs/slips/blob/master/./00013.md">SLIP13: Authentication using deterministic hierarchy</a></p> </li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-02-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Witek Radomskiwitek@enjin.io Andrew Cookeac0dem0nk3y@gmail.com James Therienjames@enjin.io Eric Bineteric@enjin.io https://wg-eips.ritovision.com/1761/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface to permit restricted approval in token contracts by defining "scopes" of one or more Token IDs.</p> <h2 id="abstract">Abstract</h2> <p>This interface is designed for use with token contracts that have an "ID" domain, such as ERC-1155 or ERC-721. This enables restricted approval of one or more Token IDs to a specific "scope". When considering a smart contract managing tokens from multiple different domains, it makes sense to limit approvals to those domains. Scoped approval is a generalization of this idea. Implementors can define scopes as needed.</p> <p>Sample use cases for scopes:</p> <ul> <li>A company may represent its fleet of vehicles on the blockchain and it could create a scope for each regional office.</li> <li>Game developers could share an <a href="https://wg-eips.ritovision.com/1155/">ERC-1155</a> contract where each developer manages tokens under a specified scope.</li> <li>Tokens of different value could be split into separate scopes. High-value tokens could be kept in smaller separate scopes while low-value tokens might be kept in a shared scope. Users would approve the entire low-value token scope to a third-party smart contract, exchange, or other application without concern about losing their high-value tokens in the event of a problem.</li> </ul> <h2 id="motivation">Motivation</h2> <p>It may be desired to restrict approval in some applications. Restricted approval can prevent losses in cases where users do not audit the contracts they're approving. No standard API is supplied to manage scopes as this is implementation specific. Some implementations may opt to offer a fixed number of scopes, or assign a specific set of scopes to certain types. Other implementations may open up scope configuration to its users and offer methods to create scopes and assign IDs to them.</p> <h1 id="specification">Specification</h1> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.2</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-keyword"> Note</span><span class="z-comment">: The ERC-165 identifier for this interface is 0x30168307.</span></span> <span class="giallo-l"><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ScopedApproval</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST emit when approval changes for scope.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ApprovalForScope</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _operator</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _scope</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> _approved</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST emit when the token IDs are added to the scope.</span></span> <span class="giallo-l"><span class="z-comment"> By default, IDs are in no scope.</span></span> <span class="giallo-l"><span class="z-comment"> The range is inclusive: _idStart, _idEnd, and all IDs in between have been added to the scope.</span></span> <span class="giallo-l"><span class="z-comment"> _idStart must be lower than or equal to _idEnd.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdsAddedToScope</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _idStart</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _idEnd</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _scope</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST emit when the token IDs are removed from the scope.</span></span> <span class="giallo-l"><span class="z-comment"> The range is inclusive: _idStart, _idEnd, and all IDs in between have been removed from the scope.</span></span> <span class="giallo-l"><span class="z-comment"> _idStart must be lower than or equal to _idEnd.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdsRemovedFromScope</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _idStart</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _idEnd</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _scope</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST emit when a scope URI is set or changes.</span></span> <span class="giallo-l"><span class="z-comment"> URIs are defined in RFC 3986.</span></span> <span class="giallo-l"><span class="z-comment"> The URI MUST point a JSON file that conforms to the &quot;Scope Metadata JSON Schema&quot;.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ScopeURI</span><span>(</span><span class="z-support">string</span><span class="z-variable"> _value</span><span>, </span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _scope</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the number of scopes that contain _id.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> The token ID</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> number of scopes containing the ID</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> scopeCountForId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns a scope that contains _id.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _id</span><span class="z-comment"> The token ID</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _scopeIndex</span><span class="z-comment"> The scope index to query (valid values are 0 to scopeCountForId(_id)-1)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> Nth scope containing the ID</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> scopeForId</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _id</span><span>,</span><span class="z-support"> uint32</span><span class="z-variable z-parameter z-function"> _scopeIndex</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns a URI that can be queried to get scope metadata. This URI should return a JSON document containing, at least the scope name and description. Although supplying a URI for every scope is recommended, returning an empty string &quot;&quot; is accepted for scopes without a URI.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _scope</span><span class="z-comment"> The queried scope</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> URI describing this scope.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> scopeUri</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _scope</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Enable or disable approval for a third party (&quot;operator&quot;) to manage the caller&#39;s tokens in the specified scope.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> MUST emit the ApprovalForScope event on success.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> Address to add to the set of authorized operators</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _scope</span><span class="z-comment"> Approval scope (can be identified by calling scopeForId)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _approved</span><span class="z-comment"> True if the operator is approved, false to revoke approval</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setApprovalForScope</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _operator</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _scope</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _approved</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Queries the approval status of an operator for a given owner, within the specified scope.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _owner</span><span class="z-comment"> The owner of the Tokens</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _operator</span><span class="z-comment"> Address of authorized operator</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _scope</span><span class="z-comment"> Scope to test for approval (can be identified by calling scopeForId)</span></span> <span class="giallo-l"><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if the operator is approved, false otherwise</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isApprovedForScope</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _operator</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _scope</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="scope-metadata-json-schema">Scope Metadata JSON Schema</h2> <p>This schema allows for localization. <code>{id}</code> and <code>{locale}</code> should be replaced with the appropriate values by clients.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Scope Metadata</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">name</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Identifies the scope in a human-readable way.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Describes the scope to allow users to make informed approval decisions.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">localization</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">required</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">uri</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">default</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">locales</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">uri</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The URI pattern to fetch localized data from. This URI should contain the substring `{locale}` which will be replaced with the appropriate locale value before sending the request.</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">default</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The locale of the default data within the base JSON</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">locales</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">array</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">The list of locales for which data is available. These locales should conform to those defined in the Unicode Common Locale Data Repository (http://cldr.unicode.org/).</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="localization">Localization</h3> <p>Metadata localization should be standardized to increase presentation uniformity across all languages. As such, a simple overlay method is proposed to enable localization. If the metadata JSON file contains a <code>localization</code> attribute, its content may be used to provide localized values for fields that need it. The <code>localization</code> attribute should be a sub-object with three attributes: <code>uri</code>, <code>default</code> and <code>locales</code>. If the string <code>{locale}</code> exists in any URI, it MUST be replaced with the chosen locale by all client software.</p> <h2 id="rationale">Rationale</h2> <p>The initial design was proposed as an extension to ERC-1155: <a rel="external" href="https://github.com/ethereum/EIPs/issues/1155#issuecomment-459505728">Discussion Thread - Comment 1</a>. After some discussion: <a rel="external" href="https://github.com/ethereum/EIPs/issues/1155#issuecomment-460603439">Comment 2</a> and suggestions by the community to implement this approval mechanism in an external contract <a rel="external" href="https://github.com/ethereum/EIPs/issues/1155#issuecomment-461758755">Comment 3</a>, it was decided that as an interface standard, this design would allow many different token standards such as ERC-721 and ERC-1155 to implement scoped approvals without forcing the system into all implementations of the tokens.</p> <h3 id="metadata-json">Metadata JSON</h3> <p>The Scope Metadata JSON Schema was added in order to support human-readable scope names and descriptions in more than one language.</p> <h2 id="references">References</h2> <p><strong>Standards</strong></p> <ul> <li><a href="https://wg-eips.ritovision.com/1155/">ERC-1155 Multi Token Standard</a></li> <li><a href="https://wg-eips.ritovision.com/165/">ERC-165 Standard Interface Detection</a></li> <li><a rel="external" href="https://json-schema.org/">JSON Schema</a></li> </ul> <p><strong>Implementations</strong></p> <ul> <li><a rel="external" href="https://enjincoin.io">Enjin Coin</a> (<a rel="external" href="https://github.com/enjin">github</a>)</li> </ul> <p><strong>Articles &amp; Discussions</strong></p> <ul> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/1761">GitHub - Original Discussion Thread</a></li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/1155">GitHub - ERC-1155 Discussion Thread</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-02-14T00:00:00+00:00 2026-02-11T14:49:27+00:00 Nick Johnsonhttps://github.com/arachnid Raúl Kripalanihttps://github.com/raulk Kris Shinnhttps://github.com/kshinn https://wg-eips.ritovision.com/1767/ <h2 id="abstract">Abstract</h2> <p>This EIP specifies a GraphQL schema for accessing data stored on an Ethereum node. It aims to provide a complete replacement to the read-only information exposed via the present JSON-RPC interface, while improving on usability, consistency, efficiency, and future-proofing.</p> <h2 id="motivation">Motivation</h2> <p>The current JSON-RPC interface for Ethereum nodes has a number of shortcomings. It's informally and incompletely specified in areas, which has led to incompatibilities around issues such as representation of empty byte strings ("" vs "0x" vs "0x0"), and it has to make educated guesses about the data a user will request, which often leads to unnecessary work.</p> <p>For example, the <code>totalDifficulty</code> field is stored separately from the block header in common Ethereum node implementations, and many callers do not require this field. However, every call to <code>eth_getBlock</code> still retrieves this field, requiring a separate disk read, because the RPC server has no way of knowing if the user requires this field or not.</p> <p>Similarly, transaction receipts in go-ethereum are stored on disk as a single binary blob for each block. Fetching a receipt for a single transaction requires fetching and deserializing this blob, then finding the relevant entry and returning it; this is accomplished by the <code>eth_getTransactionReceipt</code> API call. A common task for API consumers is to fetch all the receipts in a block; as a result, node implementations end up fetching and deserializing the same data repeatedly, leading to <code>O(n^2)</code> effort to fetch all transaction receipts from a block instead of <code>O(n)</code>.</p> <p>Some of these issues could be fixed with changes to the existing JSON-RPC interface, at the cost of complicating the interface somewhat. Instead, we propose adopting a standard query language, GraphQL, which facilitates more efficient API implementations, while also increasing flexibility.</p> <h2 id="prior-art">Prior Art</h2> <p>Nick Johnson and <a rel="external" href="https://github.com/ConsenSys/ethql">EthQL</a> independently developed a GraphQL schema for node data. Once the parties were made aware of the shared effort, they made efforts to bring their schemas into alignment. The current schema proposed in this EIP is derived primarily from the EthQL schema.</p> <h2 id="specification">Specification</h2> <h3 id="node-api">Node API</h3> <p>Compatible nodes MUST provide a GraphQL endpoint available over HTTP. This SHOULD be offered on port 8547 by default. The path to the GraphQL endpoint SHOULD be '/graphql'.</p> <p>Compatible nodes MAY offer a GraphiQL interactive query explorer on the root path ('/').</p> <h3 id="schema">Schema</h3> <p>The GraphQL schema for this service is defined as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span># Bytes32 is a 32 byte binary string, represented as 0x-prefixed hexadecimal.</span></span> <span class="giallo-l"><span>scalar Bytes32</span></span> <span class="giallo-l"><span># Address is a 20 byte Ethereum address, represented as 0x-prefixed hexadecimal.</span></span> <span class="giallo-l"><span>scalar Address</span></span> <span class="giallo-l"><span># Bytes is an arbitrary length binary string, represented as 0x-prefixed hexadecimal.</span></span> <span class="giallo-l"><span># An empty byte string is represented as &#39;0x&#39;. Byte strings must have an even number of hexadecimal nybbles.</span></span> <span class="giallo-l"><span>scalar Bytes</span></span> <span class="giallo-l"><span># BigInt is a large integer. Input is accepted as either a JSON number or as a string.</span></span> <span class="giallo-l"><span># Strings may be either decimal or 0x-prefixed hexadecimal. Output values are all</span></span> <span class="giallo-l"><span># 0x-prefixed hexadecimal.</span></span> <span class="giallo-l"><span>scalar BigInt</span></span> <span class="giallo-l"><span># Long is a 64 bit unsigned integer.</span></span> <span class="giallo-l"><span>scalar Long</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>schema {</span></span> <span class="giallo-l"><span> query: Query</span></span> <span class="giallo-l"><span> mutation: Mutation</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Account is an Ethereum account at a particular block.</span></span> <span class="giallo-l"><span>type Account {</span></span> <span class="giallo-l"><span> # Address is the address owning the account.</span></span> <span class="giallo-l"><span> address: Address!</span></span> <span class="giallo-l"><span> # Balance is the balance of the account, in wei.</span></span> <span class="giallo-l"><span> balance: BigInt!</span></span> <span class="giallo-l"><span> # TransactionCount is the number of transactions sent from this account,</span></span> <span class="giallo-l"><span> # or in the case of a contract, the number of contracts created. Otherwise</span></span> <span class="giallo-l"><span> # known as the nonce.</span></span> <span class="giallo-l"><span> transactionCount: Long!</span></span> <span class="giallo-l"><span> # Code contains the smart contract code for this account, if the account</span></span> <span class="giallo-l"><span> # is a (non-self-destructed) contract.</span></span> <span class="giallo-l"><span> code: Bytes!</span></span> <span class="giallo-l"><span> # Storage provides access to the storage of a contract account, indexed</span></span> <span class="giallo-l"><span> # by its 32 byte slot identifier.</span></span> <span class="giallo-l"><span> storage(slot: Bytes32!): Bytes32!</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Log is an Ethereum event log.</span></span> <span class="giallo-l"><span>type Log {</span></span> <span class="giallo-l"><span> # Index is the index of this log in the block.</span></span> <span class="giallo-l"><span> index: Int!</span></span> <span class="giallo-l"><span> # Account is the account which generated this log - this will always</span></span> <span class="giallo-l"><span> # be a contract account.</span></span> <span class="giallo-l"><span> account(block: Long): Account!</span></span> <span class="giallo-l"><span> # Topics is a list of 0-4 indexed topics for the log.</span></span> <span class="giallo-l"><span> topics: [Bytes32!]!</span></span> <span class="giallo-l"><span> # Data is unindexed data for this log.</span></span> <span class="giallo-l"><span> data: Bytes!</span></span> <span class="giallo-l"><span> # Transaction is the transaction that generated this log entry.</span></span> <span class="giallo-l"><span> transaction: Transaction!</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Transaction is an Ethereum transaction.</span></span> <span class="giallo-l"><span>type Transaction {</span></span> <span class="giallo-l"><span> # Hash is the hash of this transaction.</span></span> <span class="giallo-l"><span> hash: Bytes32!</span></span> <span class="giallo-l"><span> # Nonce is the nonce of the account this transaction was generated with.</span></span> <span class="giallo-l"><span> nonce: Long!</span></span> <span class="giallo-l"><span> # Index is the index of this transaction in the parent block. This will</span></span> <span class="giallo-l"><span> # be null if the transaction has not yet been mined.</span></span> <span class="giallo-l"><span> index: Int</span></span> <span class="giallo-l"><span> # From is the account that sent this transaction - this will always be</span></span> <span class="giallo-l"><span> # an externally owned account.</span></span> <span class="giallo-l"><span> from(block: Long): Account!</span></span> <span class="giallo-l"><span> # To is the account the transaction was sent to. This is null for</span></span> <span class="giallo-l"><span> # contract-creating transactions.</span></span> <span class="giallo-l"><span> to(block: Long): Account</span></span> <span class="giallo-l"><span> # Value is the value, in wei, sent along with this transaction.</span></span> <span class="giallo-l"><span> value: BigInt!</span></span> <span class="giallo-l"><span> # GasPrice is the price offered to miners for gas, in wei per unit.</span></span> <span class="giallo-l"><span> gasPrice: BigInt!</span></span> <span class="giallo-l"><span> # Gas is the maximum amount of gas this transaction can consume.</span></span> <span class="giallo-l"><span> gas: Long!</span></span> <span class="giallo-l"><span> # InputData is the data supplied to the target of the transaction.</span></span> <span class="giallo-l"><span> inputData: Bytes!</span></span> <span class="giallo-l"><span> # Block is the block this transaction was mined in. This will be null if</span></span> <span class="giallo-l"><span> # the transaction has not yet been mined.</span></span> <span class="giallo-l"><span> block: Block</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> # Status is the return status of the transaction. This will be 1 if the</span></span> <span class="giallo-l"><span> # transaction succeeded, or 0 if it failed (due to a revert, or due to</span></span> <span class="giallo-l"><span> # running out of gas). If the transaction has not yet been mined, this</span></span> <span class="giallo-l"><span> # field will be null.</span></span> <span class="giallo-l"><span> status: Long</span></span> <span class="giallo-l"><span> # GasUsed is the amount of gas that was used processing this transaction.</span></span> <span class="giallo-l"><span> # If the transaction has not yet been mined, this field will be null.</span></span> <span class="giallo-l"><span> gasUsed: Long</span></span> <span class="giallo-l"><span> # CumulativeGasUsed is the total gas used in the block up to and including</span></span> <span class="giallo-l"><span> # this transaction. If the transaction has not yet been mined, this field</span></span> <span class="giallo-l"><span> # will be null.</span></span> <span class="giallo-l"><span> cumulativeGasUsed: Long</span></span> <span class="giallo-l"><span> # CreatedContract is the account that was created by a contract creation</span></span> <span class="giallo-l"><span> # transaction. If the transaction was not a contract creation transaction,</span></span> <span class="giallo-l"><span> # or it has not yet been mined, this field will be null.</span></span> <span class="giallo-l"><span> createdContract(block: Long): Account</span></span> <span class="giallo-l"><span> # Logs is a list of log entries emitted by this transaction. If the</span></span> <span class="giallo-l"><span> # transaction has not yet been mined, this field will be null.</span></span> <span class="giallo-l"><span> logs: [Log!]</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># BlockFilterCriteria encapsulates log filter criteria for a filter applied</span></span> <span class="giallo-l"><span># to a single block.</span></span> <span class="giallo-l"><span>input BlockFilterCriteria {</span></span> <span class="giallo-l"><span> # Addresses is list of addresses that are of interest. If this list is</span></span> <span class="giallo-l"><span> # empty, results will not be filtered by address.</span></span> <span class="giallo-l"><span> addresses: [Address!]</span></span> <span class="giallo-l"><span> # Topics list restricts matches to particular event topics. Each event has a list</span></span> <span class="giallo-l"><span> # of topics. Topics matches a prefix of that list. An empty element array matches any</span></span> <span class="giallo-l"><span> # topic. Non-empty elements represent an alternative that matches any of the</span></span> <span class="giallo-l"><span> # contained topics.</span></span> <span class="giallo-l"><span> #</span></span> <span class="giallo-l"><span> # Examples:</span></span> <span class="giallo-l"><span> # - [] or nil matches any topic list</span></span> <span class="giallo-l"><span> # - [[A]] matches topic A in first position</span></span> <span class="giallo-l"><span> # - [[], [B]] matches any topic in first position, B in second position</span></span> <span class="giallo-l"><span> # - [[A], [B]] matches topic A in first position, B in second position</span></span> <span class="giallo-l"><span> # - [[A, B]], [C, D]] matches topic (A OR B) in first position, (C OR D) in second position</span></span> <span class="giallo-l"><span> topics: [[Bytes32!]!]</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Block is an Ethereum block.</span></span> <span class="giallo-l"><span>type Block {</span></span> <span class="giallo-l"><span> # Number is the number of this block, starting at 0 for the genesis block.</span></span> <span class="giallo-l"><span> number: Long!</span></span> <span class="giallo-l"><span> # Hash is the block hash of this block.</span></span> <span class="giallo-l"><span> hash: Bytes32!</span></span> <span class="giallo-l"><span> # Parent is the parent block of this block.</span></span> <span class="giallo-l"><span> parent: Block</span></span> <span class="giallo-l"><span> # Nonce is the block nonce, an 8 byte sequence determined by the miner.</span></span> <span class="giallo-l"><span> nonce: Bytes!</span></span> <span class="giallo-l"><span> # TransactionsRoot is the keccak256 hash of the root of the trie of transactions in this block.</span></span> <span class="giallo-l"><span> transactionsRoot: Bytes32!</span></span> <span class="giallo-l"><span> # TransactionCount is the number of transactions in this block. if</span></span> <span class="giallo-l"><span> # transactions are not available for this block, this field will be null.</span></span> <span class="giallo-l"><span> transactionCount: Int</span></span> <span class="giallo-l"><span> # StateRoot is the keccak256 hash of the state trie after this block was processed.</span></span> <span class="giallo-l"><span> stateRoot: Bytes32!</span></span> <span class="giallo-l"><span> # ReceiptsRoot is the keccak256 hash of the trie of transaction receipts in this block.</span></span> <span class="giallo-l"><span> receiptsRoot: Bytes32!</span></span> <span class="giallo-l"><span> # Miner is the account that mined this block.</span></span> <span class="giallo-l"><span> miner(block: Long): Account!</span></span> <span class="giallo-l"><span> # ExtraData is an arbitrary data field supplied by the miner.</span></span> <span class="giallo-l"><span> extraData: Bytes!</span></span> <span class="giallo-l"><span> # GasLimit is the maximum amount of gas that was available to transactions in this block.</span></span> <span class="giallo-l"><span> gasLimit: Long!</span></span> <span class="giallo-l"><span> # GasUsed is the amount of gas that was used executing transactions in this block.</span></span> <span class="giallo-l"><span> gasUsed: Long!</span></span> <span class="giallo-l"><span> # Timestamp is the unix timestamp at which this block was mined.</span></span> <span class="giallo-l"><span> timestamp: BigInt!</span></span> <span class="giallo-l"><span> # LogsBloom is a bloom filter that can be used to check if a block may</span></span> <span class="giallo-l"><span> # contain log entries matching a filter.</span></span> <span class="giallo-l"><span> logsBloom: Bytes!</span></span> <span class="giallo-l"><span> # MixHash is the hash that was used as an input to the PoW process.</span></span> <span class="giallo-l"><span> mixHash: Bytes32!</span></span> <span class="giallo-l"><span> # Difficulty is a measure of the difficulty of mining this block.</span></span> <span class="giallo-l"><span> difficulty: BigInt!</span></span> <span class="giallo-l"><span> # TotalDifficulty is the sum of all difficulty values up to and including</span></span> <span class="giallo-l"><span> # this block.</span></span> <span class="giallo-l"><span> totalDifficulty: BigInt!</span></span> <span class="giallo-l"><span> # OmmerCount is the number of ommers (AKA uncles) associated with this</span></span> <span class="giallo-l"><span> # block. If ommers are unavailable, this field will be null.</span></span> <span class="giallo-l"><span> ommerCount: Int</span></span> <span class="giallo-l"><span> # Ommers is a list of ommer (AKA uncle) blocks associated with this block.</span></span> <span class="giallo-l"><span> # If ommers are unavailable, this field will be null. Depending on your</span></span> <span class="giallo-l"><span> # node, the transactions, transactionAt, transactionCount, ommers,</span></span> <span class="giallo-l"><span> # ommerCount and ommerAt fields may not be available on any ommer blocks.</span></span> <span class="giallo-l"><span> ommers: [Block]</span></span> <span class="giallo-l"><span> # OmmerAt returns the ommer (AKA uncle) at the specified index. If ommers</span></span> <span class="giallo-l"><span> # are unavailable, or the index is out of bounds, this field will be null.</span></span> <span class="giallo-l"><span> ommerAt(index: Int!): Block</span></span> <span class="giallo-l"><span> # OmmerHash is the keccak256 hash of all the ommers (AKA uncles)</span></span> <span class="giallo-l"><span> # associated with this block.</span></span> <span class="giallo-l"><span> ommerHash: Bytes32!</span></span> <span class="giallo-l"><span> # Transactions is a list of transactions associated with this block. If</span></span> <span class="giallo-l"><span> # transactions are unavailable for this block, this field will be null.</span></span> <span class="giallo-l"><span> transactions: [Transaction!]</span></span> <span class="giallo-l"><span> # TransactionAt returns the transaction at the specified index. If</span></span> <span class="giallo-l"><span> # transactions are unavailable for this block, or if the index is out of</span></span> <span class="giallo-l"><span> # bounds, this field will be null.</span></span> <span class="giallo-l"><span> transactionAt(index: Int!): Transaction</span></span> <span class="giallo-l"><span> # Logs returns a filtered set of logs from this block.</span></span> <span class="giallo-l"><span> logs(filter: BlockFilterCriteria!): [Log!]!</span></span> <span class="giallo-l"><span> # Account fetches an Ethereum account at the current block&#39;s state.</span></span> <span class="giallo-l"><span> account(address: Address!): Account</span></span> <span class="giallo-l"><span> # Call executes a local call operation at the current block&#39;s state.</span></span> <span class="giallo-l"><span> call(data: CallData!): CallResult</span></span> <span class="giallo-l"><span> # EstimateGas estimates the amount of gas that will be required for</span></span> <span class="giallo-l"><span> # successful execution of a transaction at the current block&#39;s state.</span></span> <span class="giallo-l"><span> estimateGas(data: CallData!): Long!</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># CallData represents the data associated with a local contract call.</span></span> <span class="giallo-l"><span># All fields are optional.</span></span> <span class="giallo-l"><span>input CallData {</span></span> <span class="giallo-l"><span> # From is the address making the call.</span></span> <span class="giallo-l"><span> from: Address</span></span> <span class="giallo-l"><span> # To is the address the call is sent to.</span></span> <span class="giallo-l"><span> to: Address</span></span> <span class="giallo-l"><span> # Gas is the amount of gas sent with the call.</span></span> <span class="giallo-l"><span> gas: Long</span></span> <span class="giallo-l"><span> # GasPrice is the price, in wei, offered for each unit of gas.</span></span> <span class="giallo-l"><span> gasPrice: BigInt</span></span> <span class="giallo-l"><span> # Value is the value, in wei, sent along with the call.</span></span> <span class="giallo-l"><span> value: BigInt</span></span> <span class="giallo-l"><span> # Data is the data sent to the callee.</span></span> <span class="giallo-l"><span> data: Bytes</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># CallResult is the result of a local call operation.</span></span> <span class="giallo-l"><span>type CallResult {</span></span> <span class="giallo-l"><span> # Data is the return data of the called contract.</span></span> <span class="giallo-l"><span> data: Bytes!</span></span> <span class="giallo-l"><span> # GasUsed is the amount of gas used by the call, after any refunds.</span></span> <span class="giallo-l"><span> gasUsed: Long!</span></span> <span class="giallo-l"><span> # Status is the result of the call - 1 for success or 0 for failure.</span></span> <span class="giallo-l"><span> status: Long!</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># FilterCriteria encapsulates log filter criteria for searching log entries.</span></span> <span class="giallo-l"><span>input FilterCriteria {</span></span> <span class="giallo-l"><span> # FromBlock is the block at which to start searching, inclusive. Defaults</span></span> <span class="giallo-l"><span> # to the latest block if not supplied.</span></span> <span class="giallo-l"><span> fromBlock: Long</span></span> <span class="giallo-l"><span> # ToBlock is the block at which to stop searching, inclusive. Defaults</span></span> <span class="giallo-l"><span> # to the latest block if not supplied.</span></span> <span class="giallo-l"><span> toBlock: Long</span></span> <span class="giallo-l"><span> # Addresses is a list of addresses that are of interest. If this list is</span></span> <span class="giallo-l"><span> # empty, results will not be filtered by address.</span></span> <span class="giallo-l"><span> addresses: [Address!]</span></span> <span class="giallo-l"><span> # Topics list restricts matches to particular event topics. Each event has a list</span></span> <span class="giallo-l"><span> # of topics. Topics matches a prefix of that list. An empty element array matches any</span></span> <span class="giallo-l"><span> # topic. Non-empty elements represent an alternative that matches any of the</span></span> <span class="giallo-l"><span> # contained topics.</span></span> <span class="giallo-l"><span> #</span></span> <span class="giallo-l"><span> # Examples:</span></span> <span class="giallo-l"><span> # - [] or nil matches any topic list</span></span> <span class="giallo-l"><span> # - [[A]] matches topic A in first position</span></span> <span class="giallo-l"><span> # - [[], [B]] matches any topic in first position, B in second position</span></span> <span class="giallo-l"><span> # - [[A], [B]] matches topic A in first position, B in second position</span></span> <span class="giallo-l"><span> # - [[A, B]], [C, D]] matches topic (A OR B) in first position, (C OR D) in second position</span></span> <span class="giallo-l"><span> topics: [[Bytes32!]!]</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># SyncState contains the current synchronisation state of the client.</span></span> <span class="giallo-l"><span>type SyncState{</span></span> <span class="giallo-l"><span> # StartingBlock is the block number at which synchronisation started.</span></span> <span class="giallo-l"><span> startingBlock: Long!</span></span> <span class="giallo-l"><span> # CurrentBlock is the point at which synchronisation has presently reached.</span></span> <span class="giallo-l"><span> currentBlock: Long!</span></span> <span class="giallo-l"><span> # HighestBlock is the latest known block number.</span></span> <span class="giallo-l"><span> highestBlock: Long!</span></span> <span class="giallo-l"><span> # PulledStates is the number of state entries fetched so far, or null</span></span> <span class="giallo-l"><span> # if this is not known or not relevant.</span></span> <span class="giallo-l"><span> pulledStates: Long</span></span> <span class="giallo-l"><span> # KnownStates is the number of states the node knows of so far, or null</span></span> <span class="giallo-l"><span> # if this is not known or not relevant.</span></span> <span class="giallo-l"><span> knownStates: Long</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span># Pending represents the current pending state.</span></span> <span class="giallo-l"><span>type Pending {</span></span> <span class="giallo-l"><span> # TransactionCount is the number of transactions in the pending state.</span></span> <span class="giallo-l"><span> transactionCount: Int!</span></span> <span class="giallo-l"><span> # Transactions is a list of transactions in the current pending state.</span></span> <span class="giallo-l"><span> transactions: [Transaction!]</span></span> <span class="giallo-l"><span> # Account fetches an Ethereum account for the pending state.</span></span> <span class="giallo-l"><span> account(address: Address!): Account</span></span> <span class="giallo-l"><span> # Call executes a local call operation for the pending state.</span></span> <span class="giallo-l"><span> call(data: CallData!): CallResult</span></span> <span class="giallo-l"><span> # EstimateGas estimates the amount of gas that will be required for</span></span> <span class="giallo-l"><span> # successful execution of a transaction for the pending state.</span></span> <span class="giallo-l"><span> estimateGas(data: CallData!): Long! </span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>type Query {</span></span> <span class="giallo-l"><span> # Block fetches an Ethereum block by number or by hash. If neither is</span></span> <span class="giallo-l"><span> # supplied, the most recent known block is returned.</span></span> <span class="giallo-l"><span> block(number: Long, hash: Bytes32): Block</span></span> <span class="giallo-l"><span> # Blocks returns all the blocks between two numbers, inclusive. If</span></span> <span class="giallo-l"><span> # to is not supplied, it defaults to the most recent known block.</span></span> <span class="giallo-l"><span> blocks(from: Long!, to: Long): [Block!]!</span></span> <span class="giallo-l"><span> # Pending returns the current pending state.</span></span> <span class="giallo-l"><span> pending: Pending!</span></span> <span class="giallo-l"><span> # Transaction returns a transaction specified by its hash.</span></span> <span class="giallo-l"><span> transaction(hash: Bytes32!): Transaction</span></span> <span class="giallo-l"><span> # Logs returns log entries matching the provided filter.</span></span> <span class="giallo-l"><span> logs(filter: FilterCriteria!): [Log!]!</span></span> <span class="giallo-l"><span> # GasPrice returns the node&#39;s estimate of a gas price sufficient to</span></span> <span class="giallo-l"><span> # ensure a transaction is mined in a timely fashion.</span></span> <span class="giallo-l"><span> gasPrice: BigInt!</span></span> <span class="giallo-l"><span> # ProtocolVersion returns the current wire protocol version number.</span></span> <span class="giallo-l"><span> protocolVersion: Int!</span></span> <span class="giallo-l"><span> # Syncing returns information on the current synchronisation state.</span></span> <span class="giallo-l"><span> syncing: SyncState</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>type Mutation {</span></span> <span class="giallo-l"><span> # SendRawTransaction sends an RLP-encoded transaction to the network.</span></span> <span class="giallo-l"><span> sendRawTransaction(data: Bytes!): Bytes32!</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Nodes MAY offer a superset of this schema, by adding new fields or types. Experimental or client-specific fields MUST be prefixed with '<em>client</em>' (eg, '<em>geth</em>' or '<em>parity</em>'). Unprefixed fields MUST be specified in a new EIP that extends this one.</p> <h2 id="rationale">Rationale</h2> <p>Ethereum nodes have been moving away from providing read-write functionality such as transaction and message signing, and from other services such as code compilation, in favor of a more 'unix-like' approach where each task is performed by a dedicated process. We have thus specified a core set of types and fields that reflects this trend, leaving out functionality that is presently, or intended to be, deprecated:</p> <ul> <li><code>eth_compile*</code> calls are deprecated, and hence not provided here.</li> <li><code>eth_accounts</code>, <code>eth_sign</code>, and <code>eth_sendTransaction</code> are considered by many to be deprecated, and are not provided here; callers should use local accounts or a separate signing daemon instead.</li> </ul> <p>Further, two areas of the current API interface have been omitted for simplicity in this initial standard, with the intention that they will be defined in a later EIP:</p> <ul> <li>Filters will require use of GraphQL subscriptions, and require careful consideration around the desire for nodes without local per-caller state.</li> <li>Mining functionality is less-used and benefits less from reimplementation in GraphQL, and should be specified in a separate EIP.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This schema implements the bulk of the current read-only functionality provided by the JSON-RPC node interface. Existing RPC calls can be mapped to GraphQL queries as follows:</p> <table><thead><tr><th>RPC</th><th>Status</th><th>Description</th></tr></thead><tbody> <tr><td>eth_blockNumber</td><td>IMPLEMENTED</td><td><code>{ block { number } }</code></td></tr> <tr><td>eth_call</td><td>IMPLEMENTED</td><td><code>{ call(data: { to: "0x...", data: "0x..." }) { data status gasUsed } }</code></td></tr> <tr><td>eth_estimateGas</td><td>IMPLEMENTED</td><td><code>{ estimateGas(data: { to: "0x...", data: "0x..." }) }</code></td></tr> <tr><td>eth_gasPrice</td><td>IMPLEMENTED</td><td><code>{ gasPrice }</code></td></tr> <tr><td>eth_getBalance</td><td>IMPLEMENTED</td><td><code>{ account(address: "0x...") { balance } }</code></td></tr> <tr><td>eth_getBlockByHash</td><td>IMPLEMENTED</td><td><code>{ block(hash: "0x...") { ... } }</code></td></tr> <tr><td>eth_getBlockByNumber</td><td>IMPLEMENTED</td><td><code>{ block(number: 123) { ... } }</code></td></tr> <tr><td>eth_getBlockTransactionCountByHash</td><td>IMPLEMENTED</td><td><code>{ block(hash: "0x...") { transactionCount } }</code></td></tr> <tr><td>eth_getBlockTransactionCountByNumber</td><td>IMPLEMENTED</td><td><code>{ block(number: x) { transactionCounnt } }</code></td></tr> <tr><td>eth_getCode</td><td>IMPLEMENTED</td><td><code>{ account(address: "0x...") { code } }</code></td></tr> <tr><td>eth_getLogs</td><td>IMPLEMENTED</td><td><code>{ logs(filter: { ... }) { ... } }</code> or <code>{ block(...) { logs(filter: { ... }) { ... } } }</code></td></tr> <tr><td>eth_getStorageAt</td><td>IMPLEMENTED</td><td><code>{ account(address: "0x...") { storage(slot: "0x...") } }</code></td></tr> <tr><td>eth_getTransactionByBlockHashAndIndex</td><td>IMPLEMENTED</td><td><code>{ block(hash: "0x...") { transactionAt(index: x) { ... } } }</code></td></tr> <tr><td>eth_getTransactionByBlockNumberAndIndex</td><td>IMPLEMENTED</td><td><code>{ block(number: n) { transactionAt(index: x) { ... } } }</code></td></tr> <tr><td>eth_getTransactionByHash</td><td>IMPLEMENTED</td><td><code>{ transaction(hash: "0x...") { ... } }</code></td></tr> <tr><td>eth_getTransactionCount</td><td>IMPLEMENTED</td><td><code>{ account(address: "0x...") { transactionCount } }</code></td></tr> <tr><td>eth_getTransactionReceipt</td><td>IMPLEMENTED</td><td><code>{ transaction(hash: "0x...") { ... } }</code></td></tr> <tr><td>eth_getUncleByBlockHashAndIndex</td><td>IMPLEMENTED</td><td><code>{ block(hash: "0x...") { ommerAt(index: x) { ... } } }</code></td></tr> <tr><td>eth_getUncleByBlockNumberAndIndex</td><td>IMPLEMENTED</td><td><code>{ block(number: n) { ommerAt(index: x) { ... } } }</code></td></tr> <tr><td>eth_getUncleCountByBlockHash</td><td>IMPLEMENTED</td><td><code>{ block(hash: "0x...") { ommerCount } }</code></td></tr> <tr><td>eth_getUncleCountByBlockNumber</td><td>IMPLEMENTED</td><td><code>{ block(number: x) { ommerCount } }</code></td></tr> <tr><td>eth_protocolVersion</td><td>IMPLEMENTED</td><td><code>{ protocolVersion }</code></td></tr> <tr><td>eth_sendRawTransaction</td><td>IMPLEMENTED</td><td><code>mutation { sendRawTransaction(data: data) }</code></td></tr> <tr><td>eth_syncing</td><td>IMPLEMENTED</td><td><code>{ syncing { ... } }</code></td></tr> <tr><td>eth_getCompilers</td><td>NOT IMPLEMENTED</td><td>Compiler functionality is deprecated in JSON-RPC.</td></tr> <tr><td>eth_compileLLL</td><td>NOT IMPLEMENTED</td><td>Compiler functionality is deprecated in JSON-RPC.</td></tr> <tr><td>eth_compileSolidity</td><td>NOT IMPLEMENTED</td><td>Compiler functionality is deprecated in JSON-RPC.</td></tr> <tr><td>eth_compileSerpent</td><td>NOT IMPLEMENTED</td><td>Compiler functionality is deprecated in JSON-RPC.</td></tr> <tr><td>eth_newFilter</td><td>NOT IMPLEMENTED</td><td>Filter functionality may be specified in a future EIP.</td></tr> <tr><td>eth_newBlockFilter</td><td>NOT IMPLEMENTED</td><td>Filter functionality may be specified in a future EIP.</td></tr> <tr><td>eth_newPendingTransactionFilter</td><td>NOT IMPLEMENTED</td><td>Filter functionality may be specified in a future EIP.</td></tr> <tr><td>eth_uninstallFilter</td><td>NOT IMPLEMENTED</td><td>Filter functionality may be specified in a future EIP.</td></tr> <tr><td>eth_getFilterChanges</td><td>NOT IMPLEMENTED</td><td>Filter functionality may be specified in a future EIP.</td></tr> <tr><td>eth_getFilterLogs</td><td>NOT IMPLEMENTED</td><td>Filter functionality may be specified in a future EIP.</td></tr> <tr><td>eth_accounts</td><td>NOT IMPLEMENTED</td><td>Accounts functionality is not part of the core node API.</td></tr> <tr><td>eth_sign</td><td>NOT IMPLEMENTED</td><td>Accounts functionality is not part of the core node API.</td></tr> <tr><td>eth_sendTransaction</td><td>NOT IMPLEMENTED</td><td>Accounts functionality is not part of the core node API.</td></tr> <tr><td>eth_coinbase</td><td>NOT IMPLEMENTED</td><td>Mining functionality to be defined separately.</td></tr> <tr><td>eth_getWork</td><td>NOT IMPLEMENTED</td><td>Mining functionality to be defined separately.</td></tr> <tr><td>eth_hashRate</td><td>NOT IMPLEMENTED</td><td>Mining functionality to be defined separately.</td></tr> <tr><td>eth_mining</td><td>NOT IMPLEMENTED</td><td>Mining functionality to be defined separately.</td></tr> <tr><td>eth_submitHashrate</td><td>NOT IMPLEMENTED</td><td>Mining functionality to be defined separately.</td></tr> <tr><td>eth_submitWork</td><td>NOT IMPLEMENTED</td><td>Mining functionality to be defined separately.</td></tr> </tbody></table> <p>For specific reasoning behind omitted functionality, see the Rationale section.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD.</p> <h2 id="implementation">Implementation</h2> <ul> <li>Implemented and released in <a rel="external" href="https://github.com/ethereum/go-ethereum/releases/tag/v1.9.0">Go-ethereum 1.9.0</a></li> <li>Implemented and released in <a rel="external" href="https://github.com/PegaSysEng/pantheon/blob/master/CHANGELOG.md#111">Pantheon 1.1.1</a></li> <li>Work in progress in <a rel="external" href="https://github.com/ethereum/trinity/issues/302">Trinity</a></li> <li>Work in progress in <a rel="external" href="https://github.com/paritytech/parity-ethereum/issues/10933">Parity</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-02-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Lucas Cullenhttps://github.com/BitcoinBrisbane Kai Yeunghttps://github.com/CivicKai Anna Crowleyannaelizabethcrowley@gmail.com Caroline Marshallcaroline.marshall888@gmail.com Katrina Donaghykatrina@civicledger.com https://wg-eips.ritovision.com/1753/ <h2 id="abstract">Abstract</h2> <p>This Ethereum Improvement Proposal (EIP) proposes an Ethereum standard for the issuance of licences, permits and grants (Licences).</p> <p>A Licence is a limited and temporary authority, granted to a natural (e.g. you) or legal person (e.g. a corporation), to do something that would otherwise be unlawful pursuant to a legal framework. A public Licence is granted by the government, directly (e.g. by the New South Wales Department of Primary Industries, Australia) or indirectly (e.g. by an agent operating under the government’s authority), and derives its authority from legislation, though this is often practically achieved via delegated legislation such as regulations. This can be contrasted to a private licence – for example, the licence you grant to a visitor who comes onto your property.</p> <p>A Licence has the following properties:</p> <ul> <li>granted personally to the licencee (Licencee), though it may be transferrable to another person or company;</li> <li>conferring a temporary right to the Licencee to own, use or do something that would otherwise be prohibited, without conferring any property interest in the underlying thing. For example, you may be granted a licence to visit a national park without acquiring any ownership in or over the park itself;</li> <li>allowing the government authority responsible for the Licence to amend, revoke, renew, suspend or deny the issuance of the Licence, or to impose conditions or penalties for non-compliance; and</li> <li>usually issued only after the payment of a fee or the meeting of some criteria.</li> </ul> <p>Additionally, a Licence may be granted in respect of certain information. For example, a Licence may be issued in respect of a vehicle registration number and attaching to that specific registered vehicle.</p> <h2 id="motivation">Motivation</h2> <p>Governments are responsible for the issuance and management of Licences. However, maintaining and sharing this data can be complicated and inefficient. The granting of Licences usually requires the filing of paper-based application forms, manual oversight of applicable legislation and data entry into registries, as well as the issuance of paper based Licences. If individuals wish to sight information on Licence registries, they often need to be present at the government office and complete further paper-based enquiry forms in order to access that data (if available publicly).</p> <p>This EIP seeks to define a standard that will allow for the granting and/or management of Licences via Ethereum smart contracts. The motivation is, in essence, to address the inefficiencies inherent in current licencing systems.</p> <h2 id="specification">Specification</h2> <h3 id="methods">Methods</h3> <p><strong>NOTES</strong>:</p> <ul> <li>The following specifications use syntax from Solidity <code>0.4.17</code> (or above)</li> <li>Callers MUST handle <code>false</code> from <code>returns (bool success)</code>. Callers MUST NOT assume that <code>false</code> is never returned!</li> </ul> <h4 id="name">name</h4> <p>Returns the name of the permit - e.g. <code>"MyPermit"</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> name</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">string</span><span>)</span><span>;</span></span></code></pre><h4 id="totalsupply">totalSupply</h4> <p>Returns the total permit supply.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span>)</span><span>;</span></span></code></pre><h4 id="grantauthority">grantAuthority</h4> <p>Adds an ethereum address to a white list of addresses that have authority to modify a permit.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> grantAuthority</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> who</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="revokeauthority">revokeAuthority</h4> <p>Removes an ethereum address from a white list of addresses that have authority to modify a permit.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revokeAuthority</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> who</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="hasauthority">hasAuthority</h4> <p>Checks to see if the address has authority to grant or revoke permits.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> hasAuthority</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> who</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> view</span><span>;</span></span></code></pre><h4 id="issue">issue</h4> <p>Issues an ethereum address a permit between the specified date range.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> issue</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> who</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> validFrom</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> validTo</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="revoke">revoke</h4> <p>Revokes a permit from an ethereum address.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revoke</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> who</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="hasvalid">hasValid</h4> <p>Checks to see if an ethereum address has a valid permit.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> hasValid</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> who</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="purchase">purchase</h4> <p>Allows a user to self procure a licence.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> purchase</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> validFrom</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> validTo</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> payable</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The use of smart contracts to apply for, renew, suspend and revoke Licences will free up much needed government resources and allow for the more efficient management of Licences. The EIP also seeks to improve the end user experience of the Licence system. In an era of open government, there is also an increased expectation that individuals will be able to easily access Licence registries, and that the process will be transparent and fair.</p> <p>By creating an EIP, we hope to increase the use of Ethereum based and issued Licences, which will address these issues.</p> <p>The Ethereum blockchain is adaptable to various Licences and government authorities. It will also be easily translatable into other languages and can be used by other governmental authorities across the world. Moreover, a blockchain will more effectively protect the privacy of Licence-holders’ data, particularly at a time of an ever-increasing volume of government data breaches.</p> <p>The EIP has been developed following the review of a number of licensing regulations at the national and state level in Australia. The review allowed the identification of the common licence requirements and criteria for incorporation into the EIP. We have included these in the proposed standard but seek feedback on whether these criteria are sufficient and universal.</p> <h2 id="test-cases">Test Cases</h2> <p>A real world example of a Licence is a permit required to camp in a national park in Australia (e.g. Kakadu national park in the Northern Territory of Australia) under the Environment Protection and Biodiversity Conservation Regulations 2000 (Cth) (EPBC Act) and the Environment Protection and Biodiversity Conservation Regulations 2000 (the Regulations). Pursuant to the EPBC Act and the Regulations, the Director of National Parks oversees a camping permit system, which is intended to help regulate certain activities in National Parks. Permits allowing access to National Parks can be issued to legal or natural persons if the applicant has met certain conditions.</p> <p>The current digital portal and application form to camp at Kakadu National Park (the Application) can be accessed at: https://www.environment.gov.au/system/files/resources/b3481ed3-164b-4e72-a9f8-91fc987d90e7/files/kakadu-camping-permit-form-19jan2015-pdf.pdf</p> <p>The user must provide the following details when making an Application:</p> <ul> <li> <p>The full name and contact details of each person to whom the permit is to be issued;</p> </li> <li> <p>If the applicant is a company or other incorporated body:</p> </li> </ul> <p>o the name, business address and postal address of the company or incorporated body;</p> <p>o if the applicant is a company—</p> <ul> <li> <p>the full name of each of the directors of the company;</p> </li> <li> <p>the full name and contact details of the person completing the application form;</p> </li> <li> <p>the ACN or ABN of the company or other incorporated body (if applicable);</p> </li> <li> <p>Details of the proposed camping purpose (e.g. private camping, school group, etc.);</p> </li> <li> <p>A start date and duration for the camping (up to the maximum duration allowed by law);</p> </li> <li> <p>Number of campers (up to the maximum allowed by law);</p> </li> <li> <p>All other required information not essential to the issuance of the Licence (e.g. any particular medical needs of the campers); and</p> </li> <li> <p>Fees payable depending on the site, duration and number of campers.</p> </li> </ul> <p>The Regulations also set out a number of conditions that must be met by licensees when the permit has been issued. The Regulations allow the Director of National Parks to cancel, renew or transfer the licence. The above workflow could be better performed by way of a smart contract.</p> <p>The key criteria required as part of this process form part of the proposed Ethereum standard. We have checked this approach by also considering the issuance of a Commercial Fishing Licence under Part 8 “Licensing and other commercial fisheries management” of the Fisheries Management (General) Regulation 2010 (NSW) (Fisheries Regulations) made pursuant to the Fisheries Management Act 1994 (NSW) (Fisheries Act).</p> <h2 id="implementation">Implementation</h2> <p>The issuance and ownership of a Licence can be digitally represented on the Ethereum blockchain.</p> <p>Smart contracts can be used to embed regulatory requirements with respect to the relevant Licence in the blockchain. The Licence would be available electronically in the form of a token. This might be practically represented by a QR code, for example, displaying the current Licence information. The digital representation of the Licence would be stored in a digital wallet, typically an application on a smartphone or tablet computer. The proposed standard allows issuing authorities or regulators to amend, revoke or deny Licences from time to time, with the result of their determinations reflected in the Licence token in near real-time. Licence holders will therefore be notified almost instantly of any amendments, revocations or issues involving their Licence.</p> <h2 id="interface">Interface</h2> <h3 id="solidity-example">Solidity Example</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EIP1753</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> grantAuthority</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeAuthority</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasAuthority</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> issue</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> to</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revoke</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasValid</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> purchase</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> validFrom</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> validTo</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.3</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> EIP</span><span class="z-storage"> is</span><span class="z-entity z-name"> EIP1753</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> public</span><span> name </span><span class="z-keyword">=</span><span class="z-string"> &quot;Kakadu National Park Camping Permit&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> public</span><span> totalSupply</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> private</span><span> _owner</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bool</span><span>)</span><span class="z-storage z-type"> private</span><span> _authorities</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span> Permit</span><span>)</span><span class="z-storage z-type"> private</span><span> _holders</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Permit</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> issuer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validFrom</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> validTo</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> _owner </span><span class="z-keyword">=</span><span class="z-variable z-language"> msg.sender</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> grantAuthority</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyOwner</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _authorities</span><span>[</span><span>who</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeAuthority</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyOwner</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _authorities</span><span>[</span><span>who</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasAuthority</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _authorities</span><span>[</span><span>who</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> issue</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> start</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> end</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyAuthority</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> _holders</span><span>[</span><span>who</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> Permit</span><span>(</span><span>_owner</span><span>,</span><span> start</span><span>,</span><span> end</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> totalSupply </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revoke</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyAuthority</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _holders</span><span>[</span><span>who</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasValid</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _holders</span><span>[</span><span>who</span><span>]</span><span>.</span><span>validFrom </span><span class="z-keyword">&gt;</span><span class="z-variable z-language"> now</span><span class="z-keyword"> &amp;&amp;</span><span> _holders</span><span>[</span><span>who</span><span>]</span><span>.</span><span>validTo </span><span class="z-keyword">&lt;</span><span class="z-variable z-language"> now</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> purchase</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> validFrom</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> validTo</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg</span><span>.</span><span>value </span><span class="z-keyword">==</span><span class="z-constant"> 1</span><span class="z-constant"> ether</span><span>,</span><span class="z-string"> &quot;Incorrect fee&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> issue</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> validFrom</span><span>,</span><span> validTo</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlyOwner</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> ==</span><span> _owner</span><span>,</span><span class="z-string"> &quot;Only owner can perform this function&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlyAuthority</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-entity z-name">hasAuthority</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>)</span><span>,</span><span class="z-string"> &quot;Only an authority can perform this function&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-constant"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-01-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bruno Barbierihttps://github.com/brunobar79 https://wg-eips.ritovision.com/1710/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard way of representing web3 browser URLs for decentralized applications.</p> <h2 id="abstract">Abstract</h2> <p>Since most normal web browsers (specifically on mobile devices) can not run decentralized applications correctly because of the lack of web3 support, it is necessary to differentiate them from normal urls, so they can be opened in web3 browsers if available.</p> <h2 id="motivation">Motivation</h2> <p>Lots of dApps that are trying to improve their mobile experience are currently (deep)linking to specific mobile web3 browsers which are currently using their own url scheme.</p> <p>In order to make the experience more seamless, dApps should still be able to recommend a specific mobile web3 browser via <a rel="external" href="https://en.wikipedia.org/wiki/Deferred_deep_linking">deferred deeplinking</a> but by having a standard url format, if the user already has a web3 browser installed that implements this standard, it will be automatically linked to it.</p> <p>There is also a compatibility problem with the current <code>ethereum:</code> url scheme described in <a href="https://wg-eips.ritovision.com/831/">EIP-831</a> where any ethereum related app (wallets, identity management, etc) already registered it and because of iOS unpredictable behavior for multiple apps handling a single url scheme, users can end up opening an <code>ethereum:</code> link in an app that doesn not include a web3 browser and will not be able to handle the deeplink correctly.</p> <h2 id="specification">Specification</h2> <h3 id="syntax">Syntax</h3> <p>Web3 browser URLs contain "dapp" in their schema (protocol) part and are constructed as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>request = &quot;dapp&quot; &quot;:&quot; [chain_id &quot;@&quot;] dapp_url</span></span> <span class="giallo-l"><span>chain_id = 1*DIGIT</span></span> <span class="giallo-l"><span>dapp_url = URI</span></span></code></pre><h3 id="semantics">Semantics</h3> <p><code>chain_id</code> is optional and it is a parameter for the browser to automatically select the corresponding chain ID as specified in <a href="https://wg-eips.ritovision.com/155/">EIP-155</a> before opening the dApp.</p> <p><code>dapp_url</code> is a valid <a rel="external" href="https://www.ietf.org/rfc/rfc3986.txt">RFC3986</a> URI</p> <p>This a complete example url:</p> <p><code>dapp:1@peepeth.com/brunobar79?utm_source=github</code></p> <p>which will open the web3 browser, select <code>mainnet</code> (chain_id = 1) and then navigate to:</p> <p><code>https://peepeth.com/brunobar79?utm_source=github</code></p> <h2 id="rationale">Rationale</h2> <p>The proposed format attempts to solve the problem of vendor specific protocols for web3 browsers, avoiding conflicts with the existing 'ethereum:' URL scheme while also adding an extra feature: <code>chain_id</code> which will help dApps to be accessed with the right network preselected, optionally extracting away that complexity from end users.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2019-01-08T00:00:00+00:00 2026-02-11T14:49:27+00:00 Martin Holst Swendehttps://github.com/holiman https://wg-eips.ritovision.com/1681/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP proposes adding a 'temporal' replay protection to transactions, in the form of a <code>valid-until</code> timestamp. This EIP is very similar to https://github.com/ethereum/EIPs/pull/599 by Nick Johnson and Konrad Feldmeier, the main difference being that this EIP is based on clock-time / walltime instead of block numbers.</p> <h2 id="motivation">Motivation</h2> <p>There are a couple of different motivators for introducing a timebased transaction validity.</p> <ul> <li>If any form of dust-account clearing is introduced, e.g. (https://github.com/ethereum/EIPs/issues/168), it will be necessary to introduce a replay protection, such as https://github.com/ethereum/EIPs/issues/169 . Having temporal replay protection removes the need to change nonce-behaviour in the state, since transactions would not be replayable at a later date than explicitly set by the user.</li> <li>In many cases, such as during ICOs, a lot of people want their transactions to either become included soon (within a couple of hours) or not at all. Currently, transactions are queued and may not execute for several days, at a cost for both the user (who ends up paying gas for a failing purchase) and the network, dealing with the large transaction queues.</li> <li>Node implementations have no commonly agreed metric for which transactions to keep, discard or propagate. Having a TTL on transactions would make it easier to remove stale transactions from the system.</li> </ul> <h2 id="specification">Specification</h2> <p>The roll-out would be performed in two phases, <code>X</code> (hardfork), and <code>Y</code> (softfork).</p> <p>At block <code>X</code>,</p> <ul> <li>Add an optional field <code>valid-until</code> to the RLP-encoded transaction, defined as a <code>uint64</code> (same as <code>nonce</code>).</li> <li>If the field is present in transaction <code>t</code>, then <ul> <li><code>t</code> is only eligible for inclusion in a block if <code>block.timestamp</code> &lt; <code>t.valid-until</code>.</li> </ul> </li> </ul> <p>At block <code>Y</code>,</p> <ul> <li>Make <code>valid-until</code> mandatory, and consider any transaction without <code>valid-until</code> to be invalid.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="rationale-for-this-eip">Rationale for this EIP</h3> <p>For the dust-account clearing usecase,</p> <ul> <li>This change is much less invasive in the consensus engine. <ul> <li>No need to maintain a consensus-field of 'highest-known-nonce' or cap the number of transactions from a sender in a block.</li> <li>Only touches the transaction validation part of the consensus engine</li> <li>Other schemas which uses the <code>nonce</code> can have unintended side-effects, <ul> <li>such as inability to create contracts at certain addresses.</li> <li>more difficult to integrate with offline signers, since more elaborate nonce-schemes requires state access to determine.</li> <li>More intricate schemes like <code>highest-nonce</code> are a lot more difficult, since highest-known-nonce will be a consensus-struct that is incremented and possibly reverted during transaction execution, requiring one more journalled field.</li> </ul> </li> </ul> </li> </ul> <h3 id="rationale-for-walltime">Rationale for walltime</h3> <p>Why use walltime instead of block numbers, as proposed in https://github.com/ethereum/EIPs/pull/599 ?</p> <ul> <li>The UTC time is generally available in most settings, even on a computer which is offline. This means that even a setup where blockchain information is unavailable, the party signing a transaction can generate a transaction with the desired properties.</li> <li>The correlation between time and block number is not fixed; even though a 14s blocktime is 'desired', this varies due to both network hashrate and difficulty bomb progression.</li> <li>The block number is even more unreliable as a timestamp for testnets and private networks.</li> <li>UTC time is more user-friendly, a user can more easily decide on reasonable end-date for a transaction, rather than a suitalbe number of valid blocks.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP means that all software/hardware that creates transactions need to add timestamps to the transactions, or will otherwise be incapable of signing transactions after block <code>Y</code>. Note: this EIP does not introduce any maximum <code>valid-until</code> date, so it would still be possible to create transactions with near infinite validity.</p> <h2 id="test-cases">Test Cases</h2> <p>todo</p> <h2 id="implementation">Implementation</h2> <p>None yet</p> <h2 id="security-considerations">Security considerations</h2> <p>The most notable security impact is that pre-signed transactions stored on paper backups, will become invalid as of block <code>Y</code>. There are a couple of cases where this might be used</p> <ul> <li>Pregenerated onetime 'bootstrap' transactions, e.g. to onboard a user into Ethereum. Instead of giving a user a giftcard with actual ether on it, someone may instead give the person a one-time pregenerated transaction that will only send those ether to the card once the user actively wants to start using it.</li> <li>If a user has an offline paper-wallet, he may have pregenerated transactions to send value to e.g. an exchange. This is sometimes done to be able to send ether to an exchange without having to go through all the hoops of bringing the paper wallet back to 'life'.</li> </ul> <p>Secondary security impacts are that the addition of a timestamp would make the transactions a little bit larger.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-12-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Michael Connormichael.connor@uk.ey.com Chaitanya Kondachaitanya.konda@uk.ey.com Duncan Westlandduncan.westland@uk.ey.com https://wg-eips.ritovision.com/1923/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for a "Verifier Registry"'" contract, through which all zk-SNARK verification activity can be registered.</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard contract API for the registration of zk-SNARKs ("Zero-Knowledge Succinct Non-Interactive Arguments of Knowledge"), also known as "proofs", "arguments", or "commitments".</p> <p>TODO: Which functionality is exposed in this standard interface?</p> <h2 id="motivation">Motivation</h2> <p>zk-SNARKs are a promising area of interest for the Ethereum community. Key applications of zk-SNARKs include:</p> <ul> <li>Private transactions</li> <li>Private computations</li> <li>Ethereum scaling through proofs of 'bundled' transactions</li> </ul> <p>A standard interface for registering all zk-SNARKs will allow applications to more easily implement private transactions, private contracts, and scaling solutions; and to extract and interpret the limited information which gets emitted during zk-SNARK verifications.</p> <p>:warning: TODO: Explain the motivation for standardizing a registry, other than simply standardizing the verifier interactions.</p> <p>⚠️ TODO: Explain the benefits to and perspective of a consumer of information. I.e. the thing that interfaces with the standard verifier registry.</p> <h2 id="specification">Specification</h2> <p>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> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.6</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-XXXX zk-SNARK Verifier Registry Standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See https://github.com/EYBlockchain/zksnark-verifier-standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0xXXXXXXXXX.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> ⚠️ </span><span class="z-keyword">TODO</span><span class="z-comment">: Set the interface identifier</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EIP</span><span class="z-keyword">-</span><span>XXXX </span><span class="z-comment">/*</span><span class="z-comment"> is ERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NewProofSubmitted</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _proofId</span><span>, </span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> _proof</span><span>, </span><span class="z-support">uint64</span><span>[</span><span>]</span><span class="z-variable"> _inputs</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NewVkRegistered</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _vkId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NewVerifierContractRegistered</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _contractAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> NewAttestation</span><span>(</span><span class="z-support">bytes32</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _proofId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _verifier</span><span>, </span><span class="z-support">bool</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _result</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getVk</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _vkId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerVerifierContract</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _verifierContract</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerVk</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _vk</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _verifierContracts</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> submitProof</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _proof</span><span>,</span><span class="z-support"> uint64</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _inputs</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _vkId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> submitProof</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _proof</span><span>,</span><span class="z-support"> uint64</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _inputs</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _vkId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _verifierContract</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> submitProofAndVerify</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _proof</span><span>,</span><span class="z-support"> uint64</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _inputs</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _vkId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _verifierContract</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> attestProof</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _proofId</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _vkId</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _result</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> attestProofs</span><span>(</span><span class="z-support">bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _proofIds</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _vkIds</span><span>,</span><span class="z-support"> bool</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _results</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> challengeAttestation</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _proofId</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _proof</span><span>,</span><span class="z-support"> uint64</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _inputs</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _verifierContract</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createNewVkId</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _vk</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createNewProofId</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _proof</span><span>,</span><span class="z-support"> uint64</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _inputs</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="interface">Interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Query if a contract implements an interface</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> interfaceID</span><span class="z-comment"> The interface identifier, as specified in ERC-165</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface identification is specified in ERC-165. This function</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> uses less than 30,000 gas.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-comment"> `true` if the contract implements `interfaceID` and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `interfaceID` is not 0xffffffff, `false` otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>⚠️ TODO: Add Rationale section.</p> <h3 id="backwards-compatibility">Backwards Compatibility</h3> <p>⚠️ TODO: Add Backwards Compatibility section.</p> <h3 id="test-cases">Test Cases</h3> <p>Truffle tests of example implementations are included in this Repo.</p> <p>⚠️ TODO: Reference specific test cases because there are many currently in the repository.</p> <h2 id="implementations">Implementations</h2> <p>Detailed example implementations and Truffle tests of these example implementations are included in this Repo.</p> <p>⚠️ TODO: Update referenced verifier registry implementations so that they are ready-to-deploy or reference deployed versions of those implementations. At current, the referenced code specifically states "DO NOT USE THIS IN PRODUCTION".</p> <p>⚠️ TODO: Provide reference to an implementation which interrogates a standard verifier registry contract that implements this standard.</p> <h2 id="references">References</h2> <p>⚠️ TODO: Update references and confirm that each reference is cited (parenthetical documentation not necessary) in the text.</p> <p><strong>Standards</strong></p> <ol> <li> <p>ERC-20 Token Standard. ./00020.md</p> </li> <li> <p>ERC-165 Standard Interface Detection. ./00165.md</p> </li> <li> <p>ERC-173 Contract Ownership Standard (DRAFT). ./00173.md</p> </li> <li> <p>ERC-196 Precompiled contracts for addition and scalar multiplication on the elliptic curve alt_bn128. ./00196.md</p> </li> <li> <p>ERC-197 Precompiled contracts for optimal ate pairing check on the elliptic curve alt_bn128. ./00197.md</p> </li> <li> <p>Ethereum Name Service (ENS). https://ens.domains</p> </li> <li> <p>RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. https://www.ietf.org/rfc/rfc2119.txt</p> </li> </ol> <h5 id="educational-material-zk-snarks">Educational material: zk-SNARKs</h5> <ol> <li>Zcash. What are zk-SNARKs? https://z.cash/technology/zksnarks.html</li> <li>Vitalik Buterin. zk-SNARKs: Under the Hood. https://medium.com/@VitalikButerin/zk-snarks-under-the-hood-b33151a013f6</li> <li>Christian Reitweissner. zk-SNARKs in a Nutshell. https://blog.ethereum.org/2016/12/05/zksnarks-in-a-nutshell/</li> <li>Ben-Sasson, Chiesa, Tromer, et. al. Succinct Non-Interactive Zero Knowledge for a von Neumann Architecture. https://eprint.iacr.org/2013/879.pdf</li> </ol> <h5 id="notable-applications-of-zk-snarks">Notable applications of zk-SNARKs</h5> <ol> <li>EY. Implementation of a business agreement through Token Commitment transactions on the Ethereum mainnet. https://github.com/EYBlockchain/ZKPChallenge</li> <li>Zcash. https://z.cash</li> <li>Zcash. How Transactions Between Shielded Addresses Work. https://blog.z.cash/zcash-private-transactions/</li> </ol> <h5 id="notable-projects-relating-to-zk-snarks">Notable projects relating to zk-SNARKs</h5> <ol> <li>libsnark: A C++ Library for zk-SNARKs ("project README)". https://github.com/scipr-lab/libsnark</li> <li>ZoKrates: Scalable Privacy-Preserving Off-Chain Computations. https://www.ise.tu-berlin.de/fileadmin/fg308/publications/2018/2018_eberhardt_ZoKrates.pdf</li> <li>ZoKrates Project Repository. https://github.com/JacobEberhardt/ZoKrates</li> <li>Joseph Stockermans. zkSNARKs: Driver's Ed. https://github.com/jstoxrocky/zksnarks_example</li> <li>Christian Reitweissner - snarktest.solidity. https://gist.github.com/chriseth/f9be9d9391efc5beb9704255a8e2989d</li> </ol> <h5 id="notable-alternatives-to-zk-snarks-areas-of-ongoing-zero-knowledge-proof-research">Notable 'alternatives' to zk-SNARKs - areas of ongoing zero-knowledge proof research</h5> <ol> <li>Vitalik Buterin. STARKs. https://web.archive.org/web/20230425101334/https://vitalik.ca/general/2017/11/09/starks_part_1.html</li> <li>Bu ̈nz, Bootle, Boneh, et. al. Bulletproofs. https://eprint.iacr.org/2017/1066.pdf</li> <li>Range Proofs. https://www.cosic.esat.kuleuven.be/ecrypt/provpriv2012/abstracts/canard.pdf</li> <li>Apple. Secure Enclaves. https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/storing_keys_in_the_secure_enclave</li> <li>Intel Software Guard Extensions. https://software.intel.com/en-us/sgx</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-11-24T00:00:00+00:00 2026-02-11T14:48:25+00:00 Paul Berghttps://github.com/PaulRBerg https://wg-eips.ritovision.com/1620/ <h2 id="simple-summary">Simple Summary</h2> <p>Money streaming represents the idea of continuous payments over a finite period of time. Block numbers are used as a proxy of time to continuously update balances.</p> <h2 id="abstract">Abstract</h2> <p>The following describes a standard whereby time is measured using block numbers and streams are mappings in a master contract.</p> <ol> <li>A provider sets up a money streaming contract.</li> <li>A prospective payer can interact with the contract and start the stream right away by depositing the funds required for the chosen period.</li> <li>The payee is able to withdraw money from the contract based on its ongoing solvency. That is: <code>payment rate * (current block height - starting block height)</code></li> <li>The stream terms (payment rate, length, metadata) can be updated at any time if both parties pledge their signatures.</li> <li>The stream can be stopped at any point in time by any party without on-chain consensus.</li> <li>If the stream period ended and it was not previously stopped by any party, the payee is entitled to withdraw all the deposited funds.</li> </ol> <h2 id="motivation">Motivation</h2> <p>This standardised interface aims to change the way we think about long-term financial commitments. Thanks to blockchains, payments need not be sent in chunks (e.g. monthly salaries), as there is much less overhead in paying-as-you-go. Money as a function of time would better align incentives in a host of scenarios.</p> <h3 id="use-cases">Use Cases</h3> <p>This is just a preliminary list of use cases. There are other spooky ideas interesting to explore, such as time-dependent disincetivisation, but, for brevity, we have not included them here.</p> <ul> <li>Salaries</li> <li>Subscriptions</li> <li>Consultancies</li> <li>CDPs</li> <li>Rent</li> <li>Parking</li> </ul> <h3 id="crowdsales">Crowdsales</h3> <p><a rel="external" href="https://github.com/lukso-network/rico">RICOs</a>, or Reversible ICOs, were introduced at Devcon4 by @frozeman. The idea is to endow investors with more power and safety guarantees by allowing them to "reverse" the investment based on the evolution of the project. We previously discussed a similar concept called SICOs, or Streamable ICOs, in this research <a rel="external" href="https://ethresear.ch/t/chronos-a-quirky-application-proposal-for-plasma/2928/14?u=paulrberg">thread</a>.</p> <p>Instead of investing a lump sum and giving the money away to the project developers, funds are held in a smart contract which allocates money based on the passage of time. Project developers can withdraw funds as the stream stays active, while investors have the power to get back a significant percentage of their initial commitment if the project halts.</p> <h2 id="specification">Specification</h2> <h3 id="structs">Structs</h3> <p>The structure of a <code>stream</code> should be as follows:</p> <ul> <li><code>stream</code> <ul> <li><code>sender</code>: the <code>address</code> of the entity funding the stream</li> <li><code>recipient</code>: the <code>address</code> where the money is being delivered to</li> <li><code>tokenAddress</code>: the <code>address</code> of the ERC20 token used as payment asset</li> <li><code>balance</code>: the total funds left in the stream</li> <li><code>timeframe</code>: as defined below</li> <li><code>rate</code>: as defined below</li> </ul> </li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Stream</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> sender</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> recipient</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> tokenAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> balance</span><span>;</span></span> <span class="giallo-l"><span> Timeframe timeframe</span><span>;</span></span> <span class="giallo-l"><span> Rate rate</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <ul> <li><code>timeframe</code> <ul> <li><code>start</code>: the starting block number of the stream</li> <li><code>stop</code>: the stopping block number of the stream</li> </ul> </li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Timeframe</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> start</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> stop</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li><code>rate</code> <ul> <li><code>payment</code>: how much money moves from <code>sender</code> to <code>recipient</code></li> <li><code>interval</code>: how often <code>payment</code> moves from <code>sender</code> to <code>recipient</code></li> </ul> </li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Rate</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> payment</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> interval</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h3 id="methods">Methods</h3> <h4 id="balanceof">balanceOf</h4> <p>Returns available funds for the given stream id and address.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _streamId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _addr</span><span>)</span></span></code></pre><h4 id="getstream">getStream</h4> <p>Returns the full stream data, if the id points to a valid stream.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getStream</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _streamId</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> sender</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> recipient</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> tokenAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> balance</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> startBlock</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> stopBlock</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> payment</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> interval</span><span>)</span></span></code></pre><h4 id="create">create</h4> <p>Creates a new stream between <code>msg.sender</code> and <code>_recipient</code>.</p> <p>MUST allow senders to create multiple streams in parallel. SHOULD not accept Ether and only use ERC20-compatible tokens.</p> <p><strong>Triggers Event</strong>: <a href="https://wg-eips.ritovision.com/1620/#logcreate">LogCreate</a></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> create</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _recipient</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _startBlock</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _stopBlock</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _payment</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _interval</span><span>)</span></span></code></pre><h4 id="withdraw">withdraw</h4> <p>Withdraws all or a fraction of the available funds.</p> <p>MUST allow only the recipient to perform this action.</p> <p><strong>Triggers Event</strong>: <a href="https://wg-eips.ritovision.com/1620/#logwithdraw">LogWithdraw</a></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> withdraw</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _streamId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _funds</span><span>)</span></span></code></pre><h4 id="redeem">redeem</h4> <p>Redeems the stream by distributing the funds to the sender and the recipient.</p> <p>SHOULD allow any party to redeem the stream.</p> <p><strong>Triggers Event</strong>: <a href="https://wg-eips.ritovision.com/1620/#logredeem">LogRedeem</a></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> redeem</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _streamId</span><span>)</span></span></code></pre><h4 id="confirmupdate">confirmUpdate</h4> <p>Signals one party's willingness to update the stream</p> <p>SHOULD allow any party to do this but MUST NOT be executed without consent from all involved parties.</p> <p><strong>Triggers Event</strong>: <a href="https://wg-eips.ritovision.com/1620/#logconfirmupdate">LogConfirmUpdate</a></p> <p><strong>Triggers Event</strong>: <a href="https://wg-eips.ritovision.com/1620/#logexecuteupdate">LogExecuteUpdate</a> when the last involved party calls this function</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> update</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _streamId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _stopBlock</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _payment</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _interval</span><span>)</span></span></code></pre><h4 id="revokeupdate">revokeUpdate</h4> <p>Revokes an update proposed by one of the involved parties.</p> <p>MUST allow any party to do this.</p> <p><strong>Triggers Event</strong>: <a href="https://wg-eips.ritovision.com/1620/#logrevokeupdate">LogRevokeUpdate</a></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> confirmUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _streamId</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _tokenAddress</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _stopBlock</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _payment</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _interval</span><span>)</span></span></code></pre> <hr /> <h3 id="events">Events</h3> <h4 id="logcreate">LogCreate</h4> <p>MUST be triggered when <code>create</code> is successfully called.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> LogCreate</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _streamId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _sender</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _recipient</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _tokenAddress</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _startBlock</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _stopBlock</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _payment</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _interval</span><span>)</span></span></code></pre><h4 id="logwithdraw">LogWithdraw</h4> <p>MUST be triggered when <code>withdraw</code> is successfully called.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> LogWithdraw</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _streamId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _recipient</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _funds</span><span>)</span></span></code></pre><h4 id="logredeem">LogRedeem</h4> <p>MUST be triggered when <code>redeem</code> is successfully called.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> LogRedeem</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _streamId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _sender</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _recipient</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _senderBalance</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _recipientBalance</span><span>)</span></span></code></pre><h4 id="logconfirmupdate">LogConfirmUpdate</h4> <p>MUST be triggered when <code>confirmUpdate</code> is successfully called.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> LogConfirmUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _streamId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _confirmer</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _newTokenAddress</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _newStopBlock</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _newPayment</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _newInterval</span><span>)</span><span>;</span></span></code></pre><h4 id="logrevokeupdate">LogRevokeUpdate</h4> <p>MUST be triggered when <code>revokeUpdate</code> is successfully called.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> LogRevokeUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _streamId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> revoker</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _newTokenAddress</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _newStopBlock</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _newPayment</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _newInterval</span><span>)</span></span></code></pre><h4 id="logexecuteupdate">LogExecuteUpdate</h4> <p>MUST be triggered when an update is approved by all involved parties.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> LogExecuteUpdate</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _newStreamId</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _sender</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _recipient</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _newTokenAddress</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _newStopBlock</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _newPayment</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _newInterval</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This specification was designed to serve as an entry point to the quirky concept of money as a function of time and it is definitely not set in stone. Several other designs, including payment channels and Plasma chains were also considered, but they were eventually deemed dense in assumptions unnecessary for an initial version.</p> <!-- - Block times and oracles for time calculation - GCD - Miners - Sidechain-compatible (and preferable) - The `update` function - Multi-hop streams --> <p>Block times are a reasonable, trustless proxy for time on the blockchain. Between 2016 and 2018, the Ethereum block time average value <a rel="external" href="https://etherscan.io/chart/blocktime">hovered</a> around 14 seconds, excluding the last two quarters of 2017. Mathematically speaking, it would be ideal to have a standard deviation as close to 0 as possible, but that is not how things work in the real world. This has huge implications on the feasibility of this ERC which we shall investigate below.</p> <h3 id="gcd">GCD</h3> <p>When setting up a stream, a payer and a payee may want to make the total streaming duration a multiple of the "greatest common denominator" (GCD) of the chain they operate on; that is, the average block time. This is not imperative in the smart contracts per se, but there needs to be an off-chain process to map streams to real world time units in order to create a sound and fair payment mechanism.</p> <h3 id="block-times">Block Times</h3> <p>Because there is uncertainty regarding block times, streams may not be settled on the blockchain as initially planned. Let <code>$d</code> be the total streaming duration measured in seconds, <code>$t</code> the average block time before the stream started and <code>$t'</code> the actual average block time over <code>$d</code> after the stream started. We distinguish two undesirable scenarios:</p> <ol> <li> <p><code>$t</code> &lt; <code>$t'</code>: the payee will get their funds <em>later</em> than expected</p> </li> <li> <p><code>$t</code> &gt; <code>$t'</code>: the payee will get their funds <em>sooner</em> than expected</p> </li> </ol> <p>If the combined error delta is smaller than the payment rate (fifth parameter of the <code>create</code> method, measured in wei), there is no problem at all. Conversely, we stumble upon trust issues because real-world time frames do not correspond to the stream terms. For instance, if an employee is normally entitled to withdraw all the funds from the stream at the end of the month, but block times cause case 1 from above to occur, the employee is in a financial disadvantage because their continuous effort is not compensated as promised.</p> <p>Limiting the problem scope only to Ethereum, we propose two remedies:</p> <ol> <li> <p>Consensus on calling the <code>update</code> function to correct the stream terms. This might sound preposterous, but in most cases the stakes are low and stream participants are involved in long-term financial commitments. There is a high disincentive to refuse to cooperate.</p> </li> <li> <p>Autonomously fix significant error deltas. In theory, we could achieve this using previous blocks' timestamps, "checkpointing" the stream once in a predefined number of blocks. This is still an area of active research because of potentially high overheads in gas costs.</p> </li> </ol> <p>Nonetheless, it is important to note that this is still a major improvement on the traditional model where absolute trust is required.</p> <h3 id="sidechains">Sidechains</h3> <p>It could be more efficient to implement this standard on independent sidechains like <a rel="external" href="https://poa.network">POA Network</a> or <a rel="external" href="https://medium.com/poa-network/poa-network-partners-with-makerdao-on-xdai-chain-the-first-ever-usd-stable-blockchain-65a078c41e6a">xDai</a> - thanks to their rather predictable nature. Admittedly, security is traded for scalability, but proper cryptoeconomic stakes could alleviate potential problems.</p> <p>Furthermore, it is intriguing to explore the prospect of stream-specific sidechains.</p> <h3 id="oracles">Oracles</h3> <p>The proposed specification uses block numbers to proxy time, but this need not be the only method. Albeit it would imply different trust assumptions, oracles could be used to provide a feed of timestamps. Coupled with the aforementioned idea of stream-specific sidechains, oracles could efficiently solve the problems outlined in <a href="https://wg-eips.ritovision.com/1620/#block-times">Block Times</a>.</p> <h3 id="multi-hop-streams">Multi-Hop Streams</h3> <p>Future or upgraded versions of this standard may describe "multi-hop" streams. If:</p> <ol> <li>There is a stream between A and B</li> <li>There is another stream between B and C</li> </ol> <p>There could be a way to avoid running two different streams in parallel. That is, a fraction or all of the funds being streamed from A to B could be automatically wired to C. An interesting use case for this is taxes. Instead of manually moving money around, proactively calculating how much you owe and then transfer it, a stream could atomically perform those operations for you.</p> <h2 id="implementation">Implementation</h2> <ul> <li><a rel="external" href="https://github.com/ChronosProtocol/monorepo">ChronosProtocol WIP implementation</a></li> </ul> <h2 id="additional-references">Additional References</h2> <ul> <li><a rel="external" href="https://ethresear.ch/t/chronos-a-quirky-application-proposal-for-plasma/2928?u=paulrberg">Chronos Protocol Ethresear.ch Plasma Proposal</a></li> <li><a rel="external" href="http://chronosprotocol.org/chronos-white-paper.pdf">Chronos Protocol White Paper</a></li> <li><a rel="external" href="https://devpost.com/software/flipper-3gvl4b">Flipper: Streaming Salaries @ CryptoLife Hackathon</a></li> <li><a rel="external" href="https://ethresear.ch/t/chronos-a-quirky-application-proposal-for-plasma/2928/14?u=paulrberg">SICOs or Streamed ICOs</a></li> <li><a rel="external" href="https://twitter.com/feindura/status/1058057076306518017">RICOs or Reversible ICOs</a></li> <li><a rel="external" href="https://www.youtube.com/watch?v=gF_ZQ_eijPs">Andreas Antonopoulos' Keynote on Bitcoin, Lightning and Money Streaming</a></li> </ul> <h2 id="final-notes">Final Notes</h2> <p>Many thanks to @mmilton41 for countless brainstorming sessions. We have been doing research on the topic of money streaming for quite a while within the context of @ChronosProtocol. In August this year, we published the first version of our white paper describing a Plasma approach. However, in the meantime, we realised that it would be much more <a rel="external" href="https://twitter.com/PaulRBerg/status/1056595919116910592">fun</a> and easier to start small on Ethereum itself and sidechains like <a rel="external" href="https://blockscout.com/poa/dai">xDai</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-11-23T00:00:00+00:00 2026-02-11T14:48:25+00:00 0agehttps://github.com/0age Santiago Palladinohttps://github.com/spalladino Leo Ariashttps://github.com/elopio Alejo Salleshttps://github.com/fiiiu Stephane Gosselinhttps://github.com/thegostep https://wg-eips.ritovision.com/1616/ <h2 id="simple-summary">Simple Summary</h2> <p>EIP-1616 provides a basic interface for querying a registry for attribute metadata assigned to Ethereum accounts.</p> <h2 id="abstract">Abstract</h2> <p>This EIP contains the following core ideas:</p> <ol> <li>Instead of relying directly on the reputation of a claims issuer to assess the veracity of a given claim, trust can be brought up to the level of a registry curator. This registry which we call an "<strong>Attribute Registry</strong>" allows for reduced complexity in implementation since a party needing to verify an attribute can now work with a trusted claims aggregator instead of relying on individual claim providers.</li> <li>Claims are abstracted as standard "attributes" which represent metadata assigned to an account, with claims decoupled from the issuing party. Attributes are registered as a flat <code>uint256 -&gt; uint256</code> key-value pair on each account, with the important property that <strong>each attribute type has one canonical value per address</strong>. This property allows for composability of attribute registries and advanced attribute formation.</li> <li>There is a generic method for determining the set of attribute keys or IDs made available by the registry. The standard does not specify requirements or recommendations for how attributes and their values are managed, or what additional metadata may be associated with attributes. It is likely that a standard set of attribute names and metadata schema could be proposed in a separate EIP.</li> </ol> <p>Potential advanced uses of attribute registries include:</p> <ul> <li>Encoding complex boolean expressions which combine multiple attributes into a single uint256 key, which is then parsed and evaluated by the registry logic.</li> <li>Using values associated with an attribute to query additional on-chain or off-chain metadata.</li> <li>Resolving attribute values by calling into separate attribute registries or other contracts, delegating authority without changing the interface of the registry.</li> </ul> <h2 id="motivation">Motivation</h2> <p>This EIP is motivated by the need for contracts and external accounts to be able to verify information about a given address from a single trusted source <strong>without concerning themselves with the particular details of how the information was obtained</strong>, and to do so in as simple a manner as possible. It is also motivated by the desire to promote broad <strong>cross-compatibility and composability</strong> between attribute registries, a property which is amplified by both the simplicity of the interface as well as by the guarantees on uniqueness provided by the proposed standard.</p> <p>Existing EIPs for assigning metadata to an account include EIP-735 and EIP-780, which both allow for multiple claims to be issued on the same address for any given claim topic. This forces verifiers of said metadata to assess the veracity of each claim, taking into account the relative reputation of each claim issuer. It also prescribes a methodology for adding and removing claims, which may not be appropriate for all use cases.</p> <p>This EIP proposes a light-weight abstraction layer for a standard account metadata registry interface. This abstraction layer can sit on top of claims registries like EIP-735 and EIP-780 or others as the attribute registry curator selects trusted data sources.</p> <h2 id="specification">Specification</h2> <p>The Attribute Registry interface contains four functions, outlined as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> EIP-1616 Attribute Registry Standard interface. EIP-165 ID: 0x5f46473f</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> AttributeRegistryInterface</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasAttribute</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> attributeTypeID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributeValue</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> attributeTypeID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> countAttributeTypes</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributeTypeID</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> index</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Contracts that comply with the Attribute Registry EIP MUST implement the above interface.</p> <p>As an additional requirement, the ERC-165 interface MUST be included:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> EIP-165 interface. EIP-165 ID: 0x01ffc9a7</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EIP</span><span class="z-keyword">-</span><span class="z-constant">165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> EIP-165 support. Attribute Registry interface ID is 0x5f46473f.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _interfaceID</span><span class="z-comment"> The interface identifier, as specified in EIP-165</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> True</span><span class="z-comment"> for 0x01ffc9a7 &amp; 0x5f46473f, false for unsupported interfaces.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable z-parameter z-function"> _interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The implementation MUST follow the specifications described below.</p> <h3 id="view-functions">View Functions</h3> <p>The view functions detailed below MUST be implemented.</p> <h4 id="hasattribute-function"><code>hasAttribute</code> function</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> hasAttribute</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> attributeTypeID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span></code></pre> <p>Check if an attribute has been assigned to a given account on the registry and is currently valid.</p> <p><em><strong>NOTE</strong></em>: This function MUST return either true or false - i.e. calling this function MUST NOT cause the caller to revert. Implementations that wish to call into another contract during execution of this function MUST catch any <code>revert</code> and instead return <code>false</code>.</p> <p><em><strong>NOTE</strong></em>: This function MUST return two equal values when performing two directly consecutive function calls with identical <code>account</code> and <code>attributeTypeID</code> parameters, regardless of differences in the caller's address, the transaction origin, or other out-of-band information.</p> <h4 id="getattributevalue-function"><code>getAttributeValue</code> function</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getAttributeValue</span><span>(</span><span class="z-support">address</span><span class="z-variable"> account</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> attributeTypeID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span></span></code></pre> <p>Retrieve the <code>uint256</code> value of an attribute on a given account on the registry, assuming the attribute is currently valid.</p> <p><em><strong>NOTE</strong></em>: This function MUST revert if a directly preceding or subsequent function call to <code>hasAttribute</code> with identical <code>account</code> and <code>attributeTypeID</code> parameters would return false.</p> <p><em><strong>NOTE</strong></em>: This function MUST return two equal values when performing two directly consecutive function calls with identical <code>account</code> and <code>attributeTypeID</code> parameters, regardless of differences in the caller's address, the transaction origin, or other out-of-band information.</p> <h4 id="countattributetypes-function"><code>countAttributeTypes</code> function</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> countAttributeTypes</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span></span></code></pre> <p>Retrieve the total number of valid attribute types defined on the registry. Used alongside <code>getAttributeTypeID</code> to determine all of the attribute types that are available on the registry.</p> <p><em><strong>NOTE</strong></em>: This function MUST return a positive integer value - i.e. calling this function MUST NOT cause the caller to revert.</p> <p><em><strong>NOTE</strong></em>: This function MUST return a value that encompasses all indexes of attribute type IDs whereby a call to <code>hasAttribute</code> on some address with an attribute type ID at the given index would return <code>true</code>.</p> <h4 id="getattributetypeid-function"><code>getAttributeTypeID</code> function</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getAttributeTypeID</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> index</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span></span></code></pre> <p>Retrieve an ID of an attribute type defined on the registry by index. Used alongside <code>countAttributeTypes</code> to determine all of the attribute types that are available on the registry.</p> <p><em><strong>NOTE</strong></em>: This function MUST revert if the provided <code>index</code> value falls outside of the range of the value returned from a directly preceding or subsequent function call to <code>countAttributeTypes</code>. It MUST NOT revert if the provided <code>index</code> value falls inside said range.</p> <p><em><strong>NOTE</strong></em>: This function MUST return an <code>attributeTypeID</code> value on <em>some</em> index if the same <code>attributeTypeID</code> value would cause a given call to <code>hasAttribute</code> to return <code>true</code> when passed as a parameter.</p> <h2 id="rationale">Rationale</h2> <p>This standard extends the applicability of metadata assignment to those use cases that are not adequately represented by EIP-735, EIP-780, or similar proposals. Namely, it enforces the constraint of one attribute value per attribute ID per address, as opposed to one value per ID per address <em>per issuer</em>.</p> <p>Aside from the prescribed attribute value, attribute properties are deliberately omitted from the standard. While many attribute registries will require additional metadata on attributes at both the instance and the class level, reliable and flexible interoperability between highly variable registry extensions is facilitated more effectively by enforcing a widely-applicable base layer for attributes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backwards compatibility concerns.</p> <h2 id="test-cases">Test Cases</h2> <p>Targeted test cases with 100% code coverage can be found at <a rel="external" href="https://github.com/0age/AttributeRegistry">this repository</a>. See <a rel="external" href="https://github.com/TPL-protocol/tpl-contracts">here</a> for tests on a more complex contract that implements the application registry interface.</p> <h2 id="implementation">Implementation</h2> <p>The basic implementation that follows can be found at <a rel="external" href="https://github.com/0age/AttributeRegistry">this repository</a> (see <a rel="external" href="https://github.com/TPL-protocol/tpl-contracts/blob/master/contracts/BasicJurisdiction.sol#L399">here</a> for an example of a more complex implementing contract):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.25</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> Attribute Registry interface. EIP-165 ID: 0x5f46473f</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> AttributeRegistryInterface</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Check if an attribute of the type with ID `attributeTypeID` has</span></span> <span class="giallo-l"><span class="z-comment"> * been assigned to the account at `account` and is currently valid.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> account</span><span class="z-comment"> address The account to check for a valid attribute.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> attributeTypeID</span><span class="z-comment"> uint256 The ID of the attribute type to check for.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if the attribute is assigned and valid, false otherwise.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This function MUST return either true or false - i.e. calling this</span></span> <span class="giallo-l"><span class="z-comment"> * function MUST NOT cause the caller to revert.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> attributeTypeID</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Retrieve the value of the attribute of the type with ID</span></span> <span class="giallo-l"><span class="z-comment"> * `attributeTypeID` on the account at `account`, assuming it is valid.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> account</span><span class="z-comment"> address The account to check for the given attribute value.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> attributeTypeID</span><span class="z-comment"> uint256 The ID of the attribute type to check for.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> The</span><span class="z-comment"> attribute value if the attribute is valid, reverts otherwise.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This function MUST revert if a directly preceding or subsequent</span></span> <span class="giallo-l"><span class="z-comment"> * function call to `hasAttribute` with identical `account` and</span></span> <span class="giallo-l"><span class="z-comment"> * `attributeTypeID` parameters would return false.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributeValue</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> attributeTypeID</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Count the number of attribute types defined by the registry.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> The</span><span class="z-comment"> number of available attribute types.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This function MUST return a positive integer value - i.e. calling</span></span> <span class="giallo-l"><span class="z-comment"> * this function MUST NOT cause the caller to revert.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> countAttributeTypes</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the ID of the attribute type at index `index`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> index</span><span class="z-comment"> uint256 The index of the attribute type in </span><span class="z-keyword">question</span><span class="z-comment">.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> The</span><span class="z-comment"> ID of the attribute type.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This function MUST revert if the provided `index` value falls outside</span></span> <span class="giallo-l"><span class="z-comment"> * of the range of the value returned from a directly preceding or subsequent</span></span> <span class="giallo-l"><span class="z-comment"> * function call to `countAttributeTypes`. It MUST NOT revert if the provided</span></span> <span class="giallo-l"><span class="z-comment"> * `index` value falls inside said range.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributeTypeID</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> index</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> A simple example of an Attribute Registry implementation.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> AttributeRegistry</span><span class="z-storage"> is</span><span class="z-entity z-name"> AttributeRegistryInterface</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> This particular implementation just defines two attribute types.</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> Affiliation</span><span> {</span><span class="z-variable z-other z-enummember"> Whitehat</span><span>,</span><span class="z-variable z-other z-enummember"> Blackhat</span><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Top-level information about attribute types held in a static array.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-storage z-type"> private</span><span> _attributeTypeIDs</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> The number of attributes currently issued tracked in a static array.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-storage z-type"> private</span><span> _issuedAttributeCounters</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Issued attributes held in a nested mapping by account &amp; attribute type.</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bool</span><span>)</span><span>)</span><span class="z-storage z-type"> private</span><span> _issuedAttributes</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Issued attribute values held in a nested mapping by account &amp; type.</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">uint256</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint256</span><span>)</span><span>)</span><span class="z-storage z-type"> private</span><span> _issuedAttributeValues</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> The constructor function, defines the two attribute types available</span></span> <span class="giallo-l"><span class="z-comment"> * on this particular registry.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Set the attribute type IDs for whitehats (8008) and blackhats (1337).</span></span> <span class="giallo-l"><span> _attributeTypeIDs </span><span class="z-keyword">=</span><span> [</span><span class="z-constant">8008</span><span>,</span><span class="z-constant"> 1337</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Assign a &quot;whitehat&quot; attribute type to `msg.sender`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The function may not be called by accounts with a &quot;blackhat&quot; attribute</span></span> <span class="giallo-l"><span class="z-comment"> * type already assigned. This function is arbitrary and not part of the</span></span> <span class="giallo-l"><span class="z-comment"> * Attribute Registry specification.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> joinWhitehats</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Get the index of the blackhat attribute type on the attribute registry.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> blackhatIndex </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span>Affiliation</span><span>.</span><span>Blackhat</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Get the attribute type ID of the blackhat attribute type.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> blackhatAttributeTypeID </span><span class="z-keyword">=</span><span> _attributeTypeIDs</span><span>[</span><span>blackhatIndex</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Do not allow the whitehat attribute to be set if blackhat is already set.</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span class="z-keyword"> !</span><span>_issuedAttributes</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>blackhatAttributeTypeID</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;no blackhats allowed!&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Get the index of the whitehat attribute type on the attribute registry.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> whitehatIndex </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span>Affiliation</span><span>.</span><span>Whitehat</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Get the attribute type ID of the whitehat attribute type.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> whitehatAttributeTypeID </span><span class="z-keyword">=</span><span> _attributeTypeIDs</span><span>[</span><span>whitehatIndex</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mark the attribute as issued on the given address.</span></span> <span class="giallo-l"><span> _issuedAttributes</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>whitehatAttributeTypeID</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Calculate the new number of total whitehat attributes.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> incrementCounter </span><span class="z-keyword">=</span><span> _issuedAttributeCounters</span><span>[</span><span>whitehatIndex</span><span>]</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Set the attribute value to the new total assigned whitehat attributes.</span></span> <span class="giallo-l"><span> _issuedAttributeValues</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>whitehatAttributeTypeID</span><span>]</span><span class="z-keyword"> =</span><span> incrementCounter</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Update the value of the counter for total whitehat attributes.</span></span> <span class="giallo-l"><span> _issuedAttributeCounters</span><span>[</span><span>whitehatIndex</span><span>]</span><span class="z-keyword"> =</span><span> incrementCounter</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Assign a &quot;blackhat&quot; attribute type to `msg.sender`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> The function may be called by any account, but assigned &quot;whitehat&quot;</span></span> <span class="giallo-l"><span class="z-comment"> * attributes will be removed. This function is arbitrary and not part of the</span></span> <span class="giallo-l"><span class="z-comment"> * Attribute Registry specification.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> joinBlackhats</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Get the index of the blackhat attribute type on the attribute registry.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> blackhatIndex </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span>Affiliation</span><span>.</span><span>Blackhat</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Get the attribute type ID of the blackhat attribute type.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> blackhatAttributeTypeID </span><span class="z-keyword">=</span><span> _attributeTypeIDs</span><span>[</span><span>blackhatIndex</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Mark the attribute as issued on the given address. </span></span> <span class="giallo-l"><span> _issuedAttributes</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>blackhatAttributeTypeID</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Calculate the new number of total blackhat attributes. </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> incrementCounter </span><span class="z-keyword">=</span><span> _issuedAttributeCounters</span><span>[</span><span>blackhatIndex</span><span>]</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Set the attribute value to the new total assigned blackhat attributes. </span></span> <span class="giallo-l"><span> _issuedAttributeValues</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>blackhatAttributeTypeID</span><span>]</span><span class="z-keyword"> =</span><span> incrementCounter</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Update the value of the counter for total blackhat attributes. </span></span> <span class="giallo-l"><span> _issuedAttributeCounters</span><span>[</span><span>blackhatIndex</span><span>]</span><span class="z-keyword"> =</span><span> incrementCounter</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Get the index of the whitehat attribute type on the attribute registry.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> whitehatIndex </span><span class="z-keyword">=</span><span class="z-support"> uint256</span><span>(</span><span>Affiliation</span><span>.</span><span>Whitehat</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Get the attribute type ID of the whitehat attribute type.</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> whitehatAttributeTypeID </span><span class="z-keyword">=</span><span> _attributeTypeIDs</span><span>[</span><span>whitehatIndex</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Determine if a whitehat attribute type has been assigned.</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>_issuedAttributes</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>whitehatAttributeTypeID</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> If so, delete the attribute.</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _issuedAttributes</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>whitehatAttributeTypeID</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Delete the attribute value as well.</span></span> <span class="giallo-l"><span class="z-keyword"> delete</span><span> _issuedAttributeValues</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>whitehatAttributeTypeID</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Set the attribute value to the new total assigned whitehat attributes. </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> decrementCounter </span><span class="z-keyword">=</span><span> _issuedAttributeCounters</span><span>[</span><span>whitehatIndex</span><span>]</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Update the value of the counter for total whitehat attributes.</span></span> <span class="giallo-l"><span> _issuedAttributeCounters</span><span>[</span><span>whitehatIndex</span><span>]</span><span class="z-keyword"> =</span><span> decrementCounter</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the total number of assigned whitehat and blackhat attributes.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> Array</span><span class="z-comment"> with counts of assigned whitehat and blackhat attributes.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This function is arbitrary and not part of the Attribute Registry</span></span> <span class="giallo-l"><span class="z-comment"> * specification.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalHats</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>[</span><span class="z-variable">2</span><span>]</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Return the array containing counter values.</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _issuedAttributeCounters</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Check if an attribute of the type with ID `attributeTypeID` has</span></span> <span class="giallo-l"><span class="z-comment"> * been assigned to the account at `account` and is currently valid.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> account</span><span class="z-comment"> address The account to check for a valid attribute.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> attributeTypeID</span><span class="z-comment"> uint256 The ID of the attribute type to check for.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> True</span><span class="z-comment"> if the attribute is assigned and valid, false otherwise.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This function MUST return either true or false - i.e. calling this</span></span> <span class="giallo-l"><span class="z-comment"> * function MUST NOT cause the caller to revert.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasAttribute</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> attributeTypeID</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Return assignment status of attribute by account and attribute type ID</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _issuedAttributes</span><span>[</span><span>account</span><span>]</span><span>[</span><span>attributeTypeID</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Retrieve the value of the attribute of the type with ID</span></span> <span class="giallo-l"><span class="z-comment"> * `attributeTypeID` on the account at `account`, assuming it is valid.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> account</span><span class="z-comment"> address The account to check for the given attribute value.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> attributeTypeID</span><span class="z-comment"> uint256 The ID of the attribute type to check for.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> The</span><span class="z-comment"> attribute value if the attribute is valid, reverts otherwise.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This function MUST revert if a directly preceding or subsequent</span></span> <span class="giallo-l"><span class="z-comment"> * function call to `hasAttribute` with identical `account` and</span></span> <span class="giallo-l"><span class="z-comment"> * `attributeTypeID` parameters would return false.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributeValue</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> account</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> attributeTypeID</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Revert if attribute with given account &amp; attribute type ID is unassigned</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> _issuedAttributes</span><span>[</span><span>account</span><span>]</span><span>[</span><span>attributeTypeID</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;could not find a value with the provided account and attribute type ID&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Return the attribute value.</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _issuedAttributeValues</span><span>[</span><span>account</span><span>]</span><span>[</span><span>attributeTypeID</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Count the number of attribute types defined by the registry.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> The</span><span class="z-comment"> number of available attribute types.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This function MUST return a positive integer value - i.e. calling</span></span> <span class="giallo-l"><span class="z-comment"> * this function MUST NOT cause the caller to revert.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> countAttributeTypes</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Return the length of the attribute type IDs array.</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _attributeTypeIDs</span><span>.</span><span>length</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Get the ID of the attribute type at index `index`.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> index</span><span class="z-comment"> uint256 The index of the attribute type in </span><span class="z-keyword">question</span><span class="z-comment">.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> The</span><span class="z-comment"> ID of the attribute type.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> This function MUST revert if the provided `index` value falls outside</span></span> <span class="giallo-l"><span class="z-comment"> * of the range of the value returned from a directly preceding or subsequent</span></span> <span class="giallo-l"><span class="z-comment"> * function call to `countAttributeTypes`. It MUST NOT revert if the provided</span></span> <span class="giallo-l"><span class="z-comment"> * `index` value falls inside said range.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributeTypeID</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> index</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Revert if the provided index is out of range.</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span></span> <span class="giallo-l"><span> index </span><span class="z-keyword">&lt;</span><span> _attributeTypeIDs</span><span>.</span><span>length</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;provided index is outside of the range of defined attribute type IDs&quot;</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Return the attribute type ID at the given index in the array.</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> _attributeTypeIDs</span><span>[</span><span>index</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-11-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Yoav Weissyoav@tabookey.com Dror Tiroshdror@tabookey.com Alex Forshtatalex@tabookey.com https://wg-eips.ritovision.com/1613/ <h2 id="simple-summary">Simple Summary</h2> <p>Make smart contracts (e.g. dapps) accessible to non-ether users by allowing contracts to accept "<a rel="external" href="https://en.wikipedia.org/wiki/Collect_call">collect-calls</a>", paying for incoming calls. Let contracts "listen" on publicly accessible channels (e.g. web URL or a whisper address). Incentivize nodes to run "gas stations" to facilitate this. Require no network changes, and minimal contract changes.</p> <h2 id="abstract">Abstract</h2> <p>Communicating with dapps currently requires paying ETH for gas, which limits dapp adoption to ether users. Therefore, contract owners may wish to pay for the gas to increase user acquisition, or let their users pay for gas with fiat money. Alternatively, a 3rd party may wish to subsidize the gas costs of certain contracts. Solutions such as described in <a href="https://wg-eips.ritovision.com/1077/">EIP-1077</a> could allow transactions from addresses that hold no ETH.</p> <p>The gas stations network is an <a href="https://wg-eips.ritovision.com/1077/">EIP-1077</a> compliant effort to solve the problem by creating an incentive for nodes to run gas stations, where gasless transactions can be "fueled up". It abstracts the implementation details from both the dapp maintainer and the user, making it easy to convert existing dapps to accept "collect-calls".</p> <p>The network consists of a single public contract trusted by all participating dapp contracts, and a decentralized network of relay nodes (gas stations) incentivized to listen on non-ether interfaces such as web or whisper, pay for transactions and get compensated by that contract. The trusted contract can be verified by anyone, and the system is otherwise trustless. Gas stations cannot censor transactions as long as there's at least one honest gas station. Attempts to undermine the system can be proven on-chain and offenders can be penalized.</p> <h2 id="motivation">Motivation</h2> <ul> <li>Increase user adoption of smart contracts by: <ul> <li>Removing the user hassle of acquiring ETH. Transactions are still paid by ETH but costs can be borne by the dapp or paid by the user through other means.</li> <li>Removing the need to interact directly with the blockchain, while maintaining decentralization and censorship-resistance. Contracts can "listen" on multiple public channels, and users can interact with the contracts through common protocols that are generally permitted even in restrictive environments.</li> </ul> </li> <li>Ethereum nodes get a revenue source without requiring mining equipment. The entire network benefits from having more nodes.</li> <li>No protocol changes required. The gas station network is self-organized via a smart contract, and dapps interact with the network by implementing an interface.</li> </ul> <h2 id="specification">Specification</h2> <p>The system consists of a <code>RelayHub</code> singleton contract, participating contracts inheriting the <code>RelayRecipient</code> contract, a decentralized network of <code>Relay</code> nodes, a.k.a. Gas Stations, and user applications (e.g. mobile or web) interacting with contracts via relays.</p> <p>Roles of the <code>RelayHub</code>:</p> <ul> <li>Maintain a list of active relays. Senders select a <code>Relay</code> from this list for each transaction. The selection process is discussed below.</li> <li>Mediate all communication between relays and contracts.</li> <li>Provide contracts with trusted versions of the real msg.sender and msg.data.</li> <li>Hold ETH stakes placed by relays. A minimum stake size is enforced. Stake can be withdrawn after a relay unregisters and waits for a cooldown period.</li> <li>Hold ETH prepayments made by contracts and use them to compensate relays.</li> <li>Penalize provably-offensive relays by giving their stakes to an address providing the proof, thus keeping relays honest.</li> <li>Provide a free way for relays to know whether they'll be compensated for a future transaction.</li> </ul> <p>Roles of a <code>Relay</code> node:</p> <ul> <li>Maintain a hot wallet with a small amount of ETH, to pay for gas.</li> <li>Provide a public interface for user apps to send gasless transactions via channels such as https or whisper.</li> <li>Publish it's public interfaces and its price (as a multiplier of the actual transaction gas cost) in <code>RelayHub</code>.</li> <li>Optionally monitor reverted transactions of other relays through RelayHub, catching offending relays and claiming their stakes. This can be done by anyone, not just a relay.</li> </ul> <p>Implementing a <code>RelayRecipient</code> contract:</p> <ul> <li> <p>Know the address of <code>RelayHub</code> and trust it to provide information about the transaction.</p> </li> <li> <p>Maintain a small balance of ETH gas prepayment deposit in <code>RelayHub</code>. Can be paid directly by the <code>RelayRecipient</code> contract, or by the dapp's owner on behalf of the <code>RelayRecipient</code> address. The dapp owner is responsible for ensuring sufficient balance for the next transactions, and can stop depositing if something goes wrong, thus limiting the potential for abuse of system bugs. In DAO usecases it will be up to the DAO logic to maintain a sufficient deposit.</p> </li> <li> <p>Use <code>getSender()</code> and <code>getMessageData()</code> instead of <code>msg.sender</code> and <code>msg.data</code>, everywhere. <code>RelayRecipient</code> provides these functions and gets the information from <code>RelayHub</code>.</p> </li> <li> <p>Implement a <code>acceptRelayedCall(address relay, address from, bytes memory encodedFunction, uint gasPrice, uint transactionFee, bytes memory approval)</code> view function that returns <strong>zero</strong> if and only if it is willing to accept a transaction and pay for it. <code>acceptRelayedCall</code> is called by <code>RelayHub</code> as a view function when a <code>Relay</code> inquires it, and also during the actual transaction. Transactions are reverted if <strong>non-zero</strong>, and <code>Relay</code> only gets compensated for transactions (whether successful or reverted) if <code>acceptRelayedCall</code> returns <strong>zero</strong>. Some examples of <code>acceptRelayedCall()</code> implementations:</p> <ul> <li>Whitelist of trusted dapp members.</li> <li>Balance sheet of registered users, maintained by the dapp owner. Users pay the dapp with a credit card or other non-ETH means, and are credited in the <code>RelayRecipient</code> balance sheet. Users can never cost the dapp more than they were credited for.</li> <li>A dapp can provide off-chain a signed message called <code>approval</code> to a transaction sender and validate it.</li> <li>Whitelist of known transactions used for onboarding new users. This allows certain anonymous calls and is subject to Sybil attacks. Therefore it should be combined with a restricted gasPrice, and a whitelist of trusted relays, to reduce the incentive for relays to create bogus transactions and rob the dapp's prepaid gas deposit. Dapps allowing anonymous onboarding transactions might benefit from registering their own <code>Relay</code> and accepting anonymous transactions only from that <code>Relay</code>, whereas other transactions can be accepted from any relay. Alternatively, dapps may use the balance sheet method for onboarding as well, by applying the methods suggested in the attacks/mitigations section below.</li> </ul> </li> <li> <p>Implement <code>preRelayedCall(address relay, address from, bytes memory encodedFunction, uint transactionFee) returns (bytes32)</code>. This method is called before a transaction is relayed. By default, it does nothing.</p> </li> <li> <p>Implement <code>postRelayedCall(ddress relay, address from, bytes memory encodedFunction, bool success, uint usedGas, uint transactionFee, bytes32 preRetVal)</code>. This method is called after a transaction is relayed. By default, it does nothing.</p> <p>These two methods can be used to charge the user in dapp-specific manner.</p> </li> </ul> <p>Glossary of terms used in the processes below:</p> <ul> <li><code>RelayHub</code> - the RelayHub singleton contract, used by everyone.</li> <li><code>Recipient</code> - a contract implementing <code>RelayRecipient</code>, accepting relayed transactions from the RelayHub contract and paying for the incoming transactions.</li> <li><code>Sender</code> - an external address with a valid key pair but no ETH to pay for gas.</li> <li><code>Relay</code> - a node holding ETH in an external address, listed in RelayHub and relaying transactions from Senders to RelayHub for a fee.</li> </ul> <p><img src="https://wg-eips.ritovision.com/1613/./assets/sequence.png" alt="Sequence Diagram" /></p> <p>The process of registering/refreshing a <code>Relay</code>:</p> <ul> <li>Relay starts listening as a web app (or on some other communication channel).</li> <li>If starting for the first time (no key yet), generate a key pair for Relay's address.</li> <li>If Relay's address doesn't hold sufficient funds for gas (e.g. because it was just generated), Relay stays inactive until its owner funds it.</li> <li>Relay's owner funds it.</li> <li>Relay's owner sends the required stake to <code>RelayHub</code> by calling <code>RelayHub.stake(address relay, uint unstakeDelay)</code>.</li> <li><code>RelayHub</code> puts the <code>owner</code> and <code>unstake delay</code> in the relays map, indexed by <code>relay</code> address.</li> <li>Relay calls <code>RelayHub.registerRelay(uint transactionFee, string memory url)</code> with the relay's <code>transaction fee</code> (as a multiplier on transaction gas cost), and a URL for incoming transactions.</li> <li><code>RelayHub</code> ensures that Relay has a sufficient stake.</li> <li><code>RelayHub</code> puts the <code>transaction fee</code> in the relays map.</li> <li><code>RelayHub</code> emits an event, <code>RelayAdded(Relay, owner, transactionFee, relayStake, unstakeDelay, url)</code>.</li> <li>Relay starts a timer to perform a <code>keepalive</code> transaction every 6000 blocks.</li> <li><code>Relay</code> goes to sleep and waits for signing requests.</li> </ul> <p>The process of sending a relayed transaction:</p> <ul> <li><code>Sender</code> selects a live <code>Relay</code> from RelayHub's list by looking at <code>RelayAdded</code> events from <code>RelayHub</code>, and sorting based on its own criteria. Selection may be based on a mix of: <ul> <li>Relay published transaction fees.</li> <li>Relay stake size and lock-up time.</li> <li>Recent relay transactions (visible through <code>TransactionRelayed</code> events from <code>RelayHub</code>).</li> <li>Optionally, reputation/blacklist/whitelist held by the sender app itself, or its backend, on per-app basis (not part of the gas stations network).</li> </ul> </li> <li>Sender prepares the transaction with Sender's address, the recipient address, the actual transaction data, Relay's transaction fee, gas price, gas limit, its current nonce from <code>RelayHub.nonces</code>, RelayHub's address, and Relay's address, and then signs it.</li> <li>Sender verifies that <code>RelayHub.balances[recipient]</code> holds enough ETH to pay Relay's fee.</li> <li>Sender verifies that <code>Relay.balance</code> has enough eth to send the transaction</li> <li>Sender reads the Relay's current <code>nonce</code> value and decides on the <code>max_nonce</code> parameter.</li> <li>Sender sends the signed transaction amd metadata to Relay's web interface.</li> <li><code>Relay</code> wraps the transaction with a transaction to <code>RelayHub</code>, with zero ETH value.</li> <li><code>Relay</code> signs the wrapper transaction with its key in order to pay for gas.</li> <li><code>Relay</code> verifies that: <ul> <li>The transaction's recipient contract will accept this transaction when submitted, by calling <code>RelayHub.canRelay()</code>, a view function, which checks the recipient's <code>acceptRelayedCall</code>, also a view function, stating whether it's willing to accept the charges).</li> <li>The transaction nonce matches <code>RelayHub.nonces[sender]</code>.</li> <li>The relay address in the transaction matches Relay's address.</li> <li>The transaction's recipient has enough ETH deposited in <code>RelayHub</code> to pay the transaction fee.</li> <li>Relay has enough ETH to pay for the gas required by the transaction.</li> <li>Value of <code>max_nonce</code> is higher than current Relay's <code>nonce</code></li> </ul> </li> <li>If any of Relay's checks fail, it returns an error to sender, and doesn't proceed.</li> <li>Relay submits the signed wrapped transaction to the blockchain.</li> <li>Relay immediately returns the signed wrapped transaction to the sender. This step is discussed below, in attacks/mitigations.</li> <li><code>Sender</code> receives the wrapped transaction and verifies that: <ul> <li>It's a valid relay call to <code>RelayHub</code>. from Relay's address.</li> <li>The transaction's ethereum nonce matches Relay's current nonce.</li> <li>The transaction's ethereum nonce is lower than or equal to <code>max_nonce</code>.</li> <li><code>Relay</code> is sufficiently funded to pay for it.</li> <li>The wrapped transaction is valid and signed by <code>sender</code>.</li> <li>Recipient contract has sufficient funds in <code>RelayHub.balances</code> to pay for Relay's fee as stated in the transaction.</li> </ul> </li> <li>If any of sender's checks fails, it goes back to selecting a new Relay. Sender may also file a report on the unresponsive relay to its backend or save it locally, to down-sort this relay in future transactions.</li> <li><code>Sender</code> may also submit the raw wrapped transaction to the blockchain without paying for gas, through any Ethereum node. This submission is likely ignored because an identical transaction is already in the network's pending transactions, but no harm in putting it twice, to ensure that it happens. This step is not strictly necessary, for reasons discussed below in attacks/mitigations, but may speed things up.</li> <li><code>Sender</code> monitors the blockchain, waiting for the transaction to be mined. The transaction was verified, with Relay's current nonce, so mining must be successful unless Relay submitted another (different) transaction with the same nonce. If mining fails due to such attack, sender may call <code>RelayHub.penalizeRepeatedNonce</code> through another relay, to collect his reward and burn the remainder of the offending relay's stake, and then go back to selecting a new Relay for the transaction. See discussion in the attacks/mitigations section below.</li> <li><code>RelayHub</code> receives the transaction: <ul> <li>Records <code>gasleft()</code> as <code>initialGas</code> for later payment.</li> <li>Verifies the transaction is sent from a registered relay.</li> <li>Verifies that the signature of the internal transaction matches its stated origin (sender's key).</li> <li>Verifies that the relay address written in the transaction matches msg.sender.</li> <li>Verifies that the transaction's <code>nonce</code> matches the stated origin's nonce in <code>RelayHub.nonces</code>.</li> <li>Calls recipient's <code>acceptRelayedCall</code> function, asking whether it's going to accept the transaction. If not, the <code>TransactionRelayed</code> will be emitted with status <code>CanRelayFailed</code>, and <code>chargeOrCanRelayStatus</code> will contain the return value of <code>acceptRelayedCall</code>. In this case, Relay doesn't get paid, as it was its responsibility to check <code>RelayHub.canRelay</code> before releasing the transaction.</li> <li>Calls recipient's <code>preRelayedCall</code> function. If this call reverts the <code>TransactionRelayed</code> will be emitted with status <code>PreRelayedFailed</code>.</li> <li>Sends the transaction to the recipient. If this call reverts the <code>TransactionRelayed</code> will be emitted with status <code>RelayedCallFailed</code>. When passing gas to <code>call()</code>, enough gas is preserved by <code>RelayHub</code>, for post-call handling. Recipient may run out of gas, but <code>RelayHub</code> never does. <code>RelayHub</code> also sends sender's address at the end of <code>msg.data</code>, so <code>RelayRecipient.getSender()</code> will be able to extract the real sender, and trust it because the transaction came from the known <code>RelayHub</code> address.</li> </ul> </li> <li>Recipient contract handles the transaction.</li> <li><code>RelayHub</code> calls recipient's <code>postRelayedCall</code>.</li> <li><code>RelayHub</code> checks call's return value of call, and emits <code>TransactionRelayed(address relay, address from, address to, bytes4 selector, uint256 status, uint256 chargeOrCanRelayStatus)</code>.</li> <li><code>RelayHub</code> increases <code>RelayHub.nonces[sender]</code>.</li> <li><code>RelayHub</code> transfers ETH balance from recipient to <code>Relay.owner</code>, to pay the transaction fee, based on the measured transaction cost. Note on relay payment: The relay gets paid for actual gas used, regardless of whether the recipient reverted. The only case where the relay sustains a loss, is if <code>canRelay</code> returns non-zero, since the relay was responsible to verify this view function prior to submitting. Any other revert is caught and paid for. See attacks/mitigations below.</li> <li><code>Relay</code> keeps track of transactions it sent, and waits for <code>TransactionRelayed</code> events to see the charge. If a transaction reverts and goes unpaid, which means the recipient's <code>acceptRelayedCall()</code> function was inconsistent, <code>Relay</code> refuses service to that recipient for a while (or blacklists it indefinitely, if it happens often). See attacks/mitigations below.</li> </ul> <p>The process of winding a <code>Relay</code> down:</p> <ul> <li>Relay's owner (the address that initially funded it) calls <code>RelayHub.removeRelayByOwner(Relay)</code>.</li> <li><code>RelayHub</code> ensures that the sender is indeed Relay's owner, then removes <code>Relay</code>, and emits <code>RelayRemoved(Relay)</code>.</li> <li><code>RelayHub</code> starts the countdown towards releasing the owner's stake.</li> <li><code>Relay</code> receives its <code>RelayRemoved</code> event.</li> <li><code>Relay</code> sends all its remaining ETH to its owner.</li> <li><code>Relay</code> shuts down.</li> <li>Once the owner's unstake delay is over, owner calls <code>RelayHub.unstake()</code>, and withdraws the stake.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The rationale for the gas stations network design is a combination of two sets of requirements: Easy adoption, and robustness.</p> <p>For easy adoption, the design goals are:</p> <ul> <li>No network changes.</li> <li>Minimal changes to contracts, apps and frameworks.</li> </ul> <p>The robustness requirement translates to decentralization and attack resistance. The gas stations network is decentralized, and we have to assume that any entity may attack other entities in the system.</p> <p>Specifically we've considered the following types of attacks:</p> <ul> <li>Denial-of-service attacks against individual senders, i.e. transactions censorship.</li> <li>Denial-of-service and financial attacks against individual relays.</li> <li>Denial-of-service and financial attacks against individual contracts.</li> <li>Denial-of-service attacks against the entire network, either by attacking existing entities, or by introducing any number of malicious entities.</li> </ul> <h4 id="attacks-and-mitigations">Attacks and mitigations</h4> <h5 id="attack-relay-attempts-to-censor-a-transaction-by-not-signing-it-or-otherwise-ignoring-a-user-request">Attack: Relay attempts to censor a transaction by not signing it, or otherwise ignoring a user request.</h5> <p>Relay is expected to return the signed transaction to the sender, immediately. Sender doesn't need to wait for the transaction to be mined, and knows immediately whether it's request has been served. If a relay doesn't return a signed transaction within a couple of seconds, sender cancels the operation, drops the connection, and switches to another relay. It also marks Relay as unresponsive in its private storage to avoid using it in the near future.</p> <p>Therefore, the maximal damage a relay can cause with such attack, is a one-time delay of a couple of seconds. After a while, senders will avoid it altogether.</p> <h5 id="attack-relay-attempts-to-censor-a-transaction-by-signing-it-returning-it-to-the-sender-but-never-putting-it-on-the-blockchain">Attack: Relay attempts to censor a transaction by signing it, returning it to the sender, but never putting it on the blockchain.</h5> <p>This attack will backfire and not censor the transaction. The sender can submit the transaction signed by Relay to the blockchain as a raw transaction through any node, so the transaction does happen, but Relay may be unaware and therefore be stuck with a bad nonce which will break its next transaction.</p> <h5 id="attack-relay-attempts-to-censor-a-transaction-by-signing-it-but-publishing-a-different-transaction-with-the-same-nonce">Attack: Relay attempts to censor a transaction by signing it, but publishing a different transaction with the same nonce.</h5> <p>Reusing the nonce is the only DoS performed by a Relay, that cannot be detected within a couple of seconds during the http request. It will only be detected when the malicious transaction with the same nonce gets mined and triggers the <code>RelayHub.TransactionRelayed</code> event. However, the attack will backfire and cost Relay its entire stake.</p> <p>Sender has a signed transaction from Relay with nonce N, and also gets a mined transaction from the blockchain with nonce N, also signed by Relay. This proves that Relay performed a DoS attack against the sender. The sender calls <code>RelayHub.penalizeRepeatedNonce(bytes transaction1, bytes transaction2)</code>, which verifies the attack, confiscates Relay's stake, and sends half of it to the sender who delivered the <code>penalizeRepeatedNonce</code> call. The other half of the stake is burned by sending it to <code>address(0)</code>. Burning is done to prevent cheating relays from effectively penalizing themselves and getting away without any loss. The sender then proceeds to select a new relay and send the original transaction.</p> <p>The result of such attack is a delay of a few blocks in sending the transaction (until the attack is detected) but the relay gets removed and loses its entire stake. Scaling such attack would be prohibitively expensive, and actually quite profitable for senders and honest relays.</p> <h5 id="attack-relay-attempts-to-censor-a-transaction-by-signing-it-but-using-a-nonce-higher-than-it-s-current-nonce">Attack: Relay attempts to censor a transaction by signing it, but using a nonce higher than it's current nonce.</h5> <p>In this attack, the Relay did create and return a perfectly valid transaction, but it will not be mined until this Relay fills the gap in the nonce with 'missing' transactions. This may delay the relaying of some transactions indefinitely. In order to mitigate that, the sender includes a <code>max_nonce</code> parameter with it's signing request. It is suggested to be higher by 2-3 from current nonce, to allow the relay process several transactions.</p> <p>When the sender receives a transaction signed by a Relay he validates that the nonce used is valid, and if it is not, the client will ignore the given relay and use other relays to relay given transaction. Therefore, there will be no actual delay introduced by such attack.</p> <h5 id="attack-dapp-attempts-to-burn-relays-funds-by-implementing-an-inconsistent-acceptrelayedcall-and-using-multiple-sender-addresses-to-generate-expensive-transactions-thus-performing-a-dos-attack-on-relays-and-reducing-their-profitability">Attack: Dapp attempts to burn relays funds by implementing an inconsistent acceptRelayedCall() and using multiple sender addresses to generate expensive transactions, thus performing a DoS attack on relays and reducing their profitability.</h5> <p>In this attack, a contract sets an inconsistent acceptRelayedCall (e.g. return zero for even blocks, nonzero for odd blocks), and uses it to exhaust relay resources through unpaid transactions. Relays can easily detect it after the fact. If a transaction goes unpaid, the relay knows that the recipient contract's acceptRelayedCall has acted inconsistently, because the relay has verified its view function before sending the transaction. It might be the result of a rare race condition where the contract's state has changed between the view call and the transaction, but if it happens too frequently, relays will blacklist this contract and refuse to serve transactions to it. Each offending contract can only cause a small damage (e.g. the cost of 2-3 transactions) to a relay, before getting blacklisted.</p> <p>Relays may also look at recipients' history on the blockchain, looking for past unpaid transactions (reverted by RelayHub without pay), and denying service to contracts with a high failure rate. If a contract caused this minor loss to a few relays, all relays will stop serving it, so it can't cause further damage.</p> <p>This attack doesn't scale because the cost of creating a malicious contract is in the same order of magnitude as the damage it can cause to the network. Causing enough damage to exhaust the resources of all relays, would be prohibitively expensive.</p> <p>The attack can be made even more impractical by setting RelayHub to require a stake from dapps before they can be served, and enforcing an unstaking delay, so that attackers will have to raise a vast amount of ETH in order to simultaneously create enough malicious contracts and attack relays. This protection is probably an overkill, since the attack doesn't scale regardless.</p> <h5 id="attack-user-attempts-to-rob-dapps-by-registering-its-own-relay-and-sending-expensive-transactions-to-dapps">Attack: User attempts to rob dapps by registering its own relay and sending expensive transactions to dapps.</h5> <p>If a malicious sender repeatedly abuses a recipient by sending meaningless/reverted transactions and causing the recipient to pay a relay for nothing, it is the recipient's responsibility to blacklist that sender and have its acceptRelayedCall function return nonzero for that sender. Collect calls are generally not meant for anonymous senders unknown to the recipient. Dapps that utilize the gas station networks should have a way to blacklist malicious users in their system and prevent Sybil attacks.</p> <p>A simple method that mitigates such Sybil attack, is that the dapp lets users buy credit with a credit card, and credit their account in the dapp contract, so acceptRelayedCall() only returns zero for users that have enough credit, and deduct the amount paid to the relay from the user's balance, whenever a transaction is relayed for the user. With this method, the attacker can only burn its own resources, not the dapp's.</p> <p>A variation of this method, for free dapps (that don't charge the user, and prefer to pay for their users transactions) is to require a captcha during user creation in their web interface, or to login with a Google/Facebook account, which limits the rate of the attack to the attacker's ability to open many Google/Facebook accounts. Only a user that passed that process is given credit in RelayRecipient. The rate of such Sybil attack would be too low to cause any real damage.</p> <h5 id="attack-attacker-attempts-to-reduce-network-availability-by-registering-many-unreliable-relays">Attack: Attacker attempts to reduce network availability by registering many unreliable relays.</h5> <p>Registering a relay requires placing a stake in RelayHub, and the stake can only be withdrawn after the relay is unregistered and a long cooldown period has passed, e.g. a month.</p> <p>Each unreliable relay can only cause a couple of seconds delay to senders, once, and then it gets blacklisted by them, as described in the first attack above. After it caused this minor delay and got blacklisted, the attacker must wait a month before reusing the funds to launch another unreliable relay. Simultaneously bringing up a number of unreliable relays, large enough to cause a noticeable network delay, would be prohibitively expensive due to the required stake, and even then, all those relays will get blacklisted within a short time.</p> <h5 id="attack-attacker-attempts-to-replay-a-relayed-transaction">Attack: Attacker attempts to replay a relayed transaction.</h5> <p>Transactions include a nonce. RelayHub maintains a nonce (counter) for each sender. Transactions with bad nonces get reverted by RelayHub. Each transaction can only be relayed once.</p> <h5 id="attack-user-does-not-execute-the-raw-transaction-received-from-the-relayer-therefore-blocking-the-execution-of-all-further-transactions-signed-by-this-relayer">Attack: User does not execute the raw transaction received from the Relayer, therefore blocking the execution of all further transactions signed by this relayer</h5> <p>The user doesn't really have to execute the raw transaction. It's enough that the user can. The relationship between relay and sender is mutual distrust. The process described above incentivizes the relay to execute the transaction, so the user doesn't need to wait for actual mining to know that the transaction has been executed.</p> <p>Once relay returns the signed transaction, which should happen immediately, the relay is incentivized to also execute it on chain, so that it can advance its nonce and serve the next transaction. The user can (but doesn't have to) also execute the transaction. To understand why the attack isn't viable, consider the four possible scenarios after the signed transaction was returned to the sender:</p> <ol> <li>Relay executes the transaction, and the user doesn't. In this scenario the transaction is executed, so no problem. This is the case described in this attack.</li> <li>Relay doesn't execute the transaction, but the user does. Similarly to 1, the transaction is executed, so no problem.</li> <li>Both of them execute the transaction. The transactions are identical in the pending transactions pool, so the transaction gets executed once. No problem.</li> <li>None of them execute the transaction. In this case the transaction doesn't get executed, but the relay is stuck. It can't serve the next transaction with the next nonce, because its nonce hasn't been advanced on-chain. It also can't serve the next transaction with the current nonce, as this can be proven by the user, having two different transactions signed by the same relay, with the same nonce. The user could use this to take the relay's nonce. So the relay is stuck unless it executes the transaction.</li> </ol> <p>As this matrix shows, the relay is <strong>always</strong> incentivized to execute the transaction, once it returned it to the user, in order to end up in #1 or #3, and avoid the risk of #4. It's just a way to commit the relay to do its work, without requiring the user to wait for on-chain confirmation.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The gas stations network is implemented as smart contracts and external entities, and does not require any network changes.</p> <p>Dapps adding gas station network support remain backwards compatible with their existing apps/users. The added methods apply on top of the existing ones, so no changes are required for existing apps.</p> <h2 id="implementation">Implementation</h2> <p>A working implementation of the <a rel="external" href="https://github.com/tabookey-dev/tabookey-gasless"><strong>gas stations network</strong></a> is being developed by <strong>TabooKey</strong>. It consists of <code>RelayHub</code>, <code>RelayRecipient</code>, <code>web3 hooks</code>, an implementation of a gas station inside <code>geth</code>, and sample dapps using the gas stations network.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-11-18T00:00:00+00:00 2026-02-11T14:48:25+00:00 Billy Rennekamphttps://github.com/okwme Dan Longdan@artblx.com Kiryl Yermakoukiryl@artblx.com Nate van der Endenate@artblx.com https://wg-eips.ritovision.com/1633/ <h2 id="simple-summary">Simple Summary</h2> <p><a href="https://wg-eips.ritovision.com/20/">ERC-20</a> extension for proportional ownership of an <a href="https://wg-eips.ritovision.com/721/">ERC-721</a> token.</p> <h2 id="abstract">Abstract</h2> <p>The intention of this proposal, the Re-Fungible Token Standard, is to extend the ERC-20 Token Standard and utilize ERC-165 Standard Interface Detection in order to represent the shared ownership of an ERC-721 Non-Fungible Token. The ERC-20 Token Standard was modified as little as possible in order to allow this new class of token to operate in all of the ways and locations which are familiar to assets that follow the original ERC-20 specification. While there are many possible variations of this specification that would enable many different capabilities and scenarios for shared ownership, this proposal is focused on the minimal commonalities to enable as much flexibility as possible for various further extensions. This proposal makes it possible to verify, from the contract level or from an external query, whether a fungible token represents a form of shared ownership of a non-fungible token. The inclusion of ERC-165 makes it possible to verify, from the contract level or from an external query, whether a non-fungible token is owned by ERC-20 token representing shared ownership.</p> <h2 id="motivation">Motivation</h2> <p>Shared ownership occurs across many industries and for many reasons. As more assets are registered, regulated and/or represented by the ERC-721 Non-Fungible Token Standard there will be more instances where the need for shared ownership of these assets will arise. For example, ARTBLX Inc. is working towards facilitating a protocol for collective ownership of physical, digital and conceptual artworks. The fungible tokens created from this process will have a value attached to the non-fungible tokens which they represent. This will be useful for price discovery of the underlying asset, liquidity for shared owners and as a new class of asset which can be used as collateral for loans or other financial instruments like stable coins. Providing an interface to this special class of fungible tokens is necessary to allow third parties to recognize them as a special class of fungible token and to recognize when a non-fungible token is collectively owned. This might be useful in the case of a wallet who would want to utilize the metadata of the underlying NFT to show additional info next to an RFT, or on an exchange who might want to make that sort of info similarly available, or an NFT marketplace who may want to direct customers to a relevant exchange who wish to purchase shares in a NFT which is owned by an RFT. Anywhere an ERC-20 is applicable it would be useful for a user to know whether that token represents a shared NFT, and what attributes that NFT may have.</p> <h2 id="specification">Specification</h2> <p>At a minimum, third parties need two things: 1) to be able to distinguish re-fungible tokens from other token standards and 2) to determine when a non-fungible token is collectively owned. These two scenarios can be encountered from the perspective of initial contact with the non-fungible token or from the perspective of initial contact with the re-fungible token.</p> <h4 id="initial-contact-with-the-re-fungible-token">Initial Contact with the Re-Fungible Token</h4> <p>In order for a third party to confirm which non-fungible token is owned by the re-fungible token there needs to be a pointer from the RFT contract to the NFT contract and the relevant token id. This is possible with two public getters named <code>parentToken()</code> and <code>parentTokenId()</code>. The first getter returns a variable of type <code>address</code> and designates the contract address of the Non-Fungible Token contract. The second getter returns a variable of type <code>uint256</code> and designates the token ID of the Non-Fungible Token. With these getters, the identity of the Non-Fungible Token can be determined. Below is an example of the Re-Fungible Token Standard interface that includes these getter functions:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x5755c3f2.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> RFT</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC20, ERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> parentToken</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _parentToken</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> parentTokenId</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _parentTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The validity of this claim can be confirmed from another contract (on-chain) or from interacting with an RPC endpoint (off-chain). Below is an example of the on-chain scenario:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;./RFT.sol&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;./ERC721.sol&#39;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ConfirmRFT</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> confirmRFT</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _RFT</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _NFT </span><span class="z-keyword">=</span><span class="z-entity z-name"> RFT</span><span>(</span><span>_RFT</span><span>)</span><span>.</span><span class="z-entity z-name">parentToken</span><span>(</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> returns address of NFT contract</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span> _tokenId </span><span class="z-keyword">=</span><span class="z-entity z-name"> RFT</span><span>(</span><span>_RFT</span><span>)</span><span>.</span><span class="z-entity z-name">parentTokenId</span><span>(</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> returns id of ID of NFT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-entity z-name"> NFT</span><span>(</span><span>_NFT</span><span>)</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-constant">0x80ac58cd</span><span>)</span><span class="z-keyword"> &amp;&amp;</span><span class="z-comment"> //</span><span class="z-comment"> confirm it is ERC-721</span></span> <span class="giallo-l"><span class="z-entity z-name"> NFT</span><span>(</span><span>_NFT</span><span>)</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>_tokenId</span><span>)</span><span class="z-keyword"> ==</span><span> _RFT</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> confirm the owner of the NFT is the RFT contract address</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Below is an off-chain example using an instance of web3.js in javascript:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage">async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> confirmRFT</span><span>(</span><span class="z-variable">web3</span><span>)</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ERC721ABI</span><span class="z-keyword"> =</span><span> [</span><span class="z-keyword">...</span><span>]</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> abi for ERC721</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> RFTABI</span><span class="z-keyword"> =</span><span> [</span><span class="z-keyword">...</span><span>]</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> abi for RFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> RFTAddress</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x0123456789abcdef0123456789abcdef</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> address for the deployed RFT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> RFTContract</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-variable z-other"> web3</span><span>.</span><span class="z-variable z-other">eth</span><span>.</span><span class="z-entity z-name">Contract</span><span>(</span><span class="z-variable z-other z-constant">RFTABI</span><span>,</span><span class="z-variable z-other"> RFTAddress</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> deployed RFT contract instance</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ERC721Address</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> RFTcontract</span><span>.</span><span class="z-variable z-other">methods</span><span>.</span><span class="z-entity z-name">parentToken</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> returns address of NFT contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ERC721TokenId</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> RFTcontract</span><span>.</span><span class="z-variable z-other">methods</span><span>.</span><span class="z-entity z-name">parentTokenId</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> returns id of ID of NFT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ERC721Contract</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-variable z-other"> web3</span><span>.</span><span class="z-variable z-other">eth</span><span>.</span><span class="z-entity z-name">Contract</span><span>(</span><span class="z-variable z-other z-constant">ERC721ABI</span><span>,</span><span class="z-variable z-other"> ERC721Address</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> deployed ERC721 (as reported by RFT)</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> isERC721</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> ERC721Contract</span><span>.</span><span class="z-variable z-other">methods</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x80ac58cd</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> confirm it is ERC-721</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ownerOfAddress</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> ERC721Contract</span><span>.</span><span class="z-variable z-other">methods</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span class="z-variable z-other">ERC721TokenId</span><span>)</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> get the owner of the NFT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> ERC721Response</span><span>.</span><span class="z-entity z-name">toLowerCase</span><span>(</span><span>)</span><span class="z-keyword"> ===</span><span class="z-variable z-other"> RFTAddress</span><span>.</span><span class="z-entity z-name">toLowerCase</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> confirm the owner of the NFT is the RFT contract</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="initial-contact-with-the-non-fungible-token">Initial Contact with the Non-Fungible Token</h4> <p>When checking the owner of a specific non-fungible token it's important to be able to determine whether owner is in fact a re-fungible token contract. This is possible by utilizing ERC-165 Standard Interface Detection. In order to comply with that standard a contract must include the following getter function which returns <code>true</code> when passed the <code>bytes4</code> parameter <code>0x01ffc9a7</code>:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function supportsInterface(bytes4 interfaceID) external view returns (bool);</span></span></code></pre> <p>After establishing support for this interface it becomes useful in determining whether the contract adheres to the Re-Fungible Token Standard. To do so the <code>supportsInterface(bytes4 interfaceID)</code> getter function must return <code>true</code> when passed the <code>bytes4</code> parameter <code>0x5755c3f2</code> which is the result of <code>bytes4(keccak256('parentToken()')) ^ bytes4(keccak256('parentTokenId()'))</code> or <code>parentToken.selector ^ parentTokenId.selector</code>. This could be achieved with the following code:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;./ERC20.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x5755c3f2.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> RFT</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20</span><span> /*, </span><span class="z-entity z-name">ERC165</span><span> */ </span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span> interfaceID </span><span class="z-keyword">==</span><span class="z-variable z-language"> this</span><span>.</span><span>supportsInterface</span><span>.</span><span>selector </span><span class="z-keyword">||</span><span class="z-comment"> //</span><span class="z-comment"> ERC165</span></span> <span class="giallo-l"><span> interfaceID </span><span class="z-keyword">==</span><span class="z-variable z-language"> this</span><span>.</span><span>parentToken</span><span>.</span><span>selector </span><span class="z-keyword">||</span><span class="z-comment"> //</span><span class="z-comment"> parentToken()</span></span> <span class="giallo-l"><span> interfaceID </span><span class="z-keyword">==</span><span class="z-variable z-language"> this</span><span>.</span><span>parentTokenId</span><span>.</span><span>selector </span><span class="z-keyword">||</span><span class="z-comment"> //</span><span class="z-comment"> parentTokenId()</span></span> <span class="giallo-l"><span> interfaceID </span><span class="z-keyword">==</span><span class="z-variable z-language"> this</span><span>.</span><span>parentToken</span><span>.</span><span>selector </span><span class="z-keyword">^</span><span class="z-variable z-language"> this</span><span>.</span><span>parentTokenId</span><span>.</span><span>selector</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> RFT</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> parentToken</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _parentToken</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> parentTokenId</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _parentTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The flow of actually checking the status of a non-fungible token owner as a re-fungible token contract can be done from another contract (on-chain) as well as with an RPC endpoint (off-chain). Below is an example of the on-chain scenario:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;./RFT.sol&#39;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &#39;./ERC721.sol&#39;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ConfirmRFT</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> confirmRFT</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _NFT</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> _RFT </span><span class="z-keyword">=</span><span class="z-entity z-name"> ERC721</span><span>(</span><span>_NFT</span><span>)</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span>_tokenId</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> get the owner of the NFT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"><span class="z-entity z-name"> RFT</span><span>(</span><span>_RFT</span><span>)</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-constant">0x01ffc9a7</span><span>)</span><span class="z-keyword"> &amp;&amp;</span><span class="z-comment"> //</span><span class="z-comment"> confirm it supports ERC-165</span></span> <span class="giallo-l"><span class="z-entity z-name"> RFT</span><span>(</span><span>_RFT</span><span>)</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-constant">0x5755c3f2</span><span>)</span><span class="z-comment"> //</span><span class="z-comment"> confirm it is RFT</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Below is an off-chain example using web3.js in javascript:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage">async</span><span class="z-storage z-type"> function</span><span class="z-entity z-name"> confirmRFT</span><span>(</span><span class="z-variable">web3</span><span>)</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ERC721ABI</span><span class="z-keyword"> =</span><span> [</span><span class="z-keyword">...</span><span>]</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> abi for ERC721</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> RFTABI</span><span class="z-keyword"> =</span><span> [</span><span class="z-keyword">...</span><span>]</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> abi for RFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ERC721Address</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x0123456789abcdef0123456789abcdef</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> address for the deployed NFT</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ERC721TokenId</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">7</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> token Id of the NFT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> ERC721Contract</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-variable z-other"> web3</span><span>.</span><span class="z-variable z-other">eth</span><span>.</span><span class="z-entity z-name">Contract</span><span>(</span><span class="z-variable z-other z-constant">ERC721ABI</span><span>,</span><span class="z-variable z-other"> ERC721Address</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> deployed ERC721</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> RFTAddress</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> ERC721Contract</span><span>.</span><span class="z-variable z-other">methods</span><span>.</span><span class="z-entity z-name">ownerOf</span><span>(</span><span class="z-variable z-other">ERC721TokenId</span><span>)</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> owner address of the NFT</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> RFTContract</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-variable z-other"> web3</span><span>.</span><span class="z-variable z-other">eth</span><span>.</span><span class="z-entity z-name">Contract</span><span>(</span><span class="z-variable z-other z-constant">RFTABI</span><span>,</span><span class="z-variable z-other"> RFTAddress</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> deployed RFT contract instance</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> isERC165</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> RFTContract</span><span>.</span><span class="z-variable z-other">methods</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x01ffc9a7</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> confirm it is ERC-165</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> isERC165</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> await</span><span class="z-variable z-other"> RFTContract</span><span>.</span><span class="z-variable z-other">methods</span><span>.</span><span class="z-entity z-name">supportsInterface</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">0x5755c3f2</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span>)</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> confirm it is RFT</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Most of the decisions made around the design of this standard were done in the hopes of keeping it as flexible as possible for as many use cases as possible. This includes making the standard 100% backwards compatible with ERC-20 Token Standard and able to interact with any previously deployed or future ERC-721 non-fungible token. This allows for each project to determine their own system for minting, burning and governing their re-fungible tokens depending on their specific use case.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The Re-Fungible Token Standard is 100% backwards compatible with ERC-20 Token Standard. It is a small extension to the original specification and meant to be further extended for more specific use cases. Keeping the standard compatible with ERC-20 is important to allow for this token to benefit from the ecosystem that has grown around supporting the ubiquitous ERC-20 Token Standard.</p> <p>The Re-Fungible Token Standard is intended to interact with the ERC-721 Non-Fungible Token Standard. It is kept purposefully agnostic to extensions beyond the standard in order to allow specific projects to design their own token relationships such as governance over, rights to or permissions on each non-fungible token relative to the respective re-fungible token owners.</p> <h2 id="implementation">Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.20</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x5755c3f2.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> RFT</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC20, ERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> parentToken</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _parentToken</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> parentTokenId</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _parentTokenId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-11-16T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ikmyeong Nahttps://github.com/naikmyeong https://wg-eips.ritovision.com/1588/ <h2 id="abstract">Abstract</h2> <p>This meta-EIP specifies the changes included in the alternative Ethereum hardfork named Ethereum ProgPoW.</p> <h2 id="specification">Specification</h2> <ul> <li>Codename: Ethereum ProgPoW</li> <li>Aliases: N/A</li> <li>Activation: <ul> <li><code>Block &gt;= 7280000</code> on the Ethereum mainnet</li> </ul> </li> <li>Included EIPs: <ul> <li><a href="https://wg-eips.ritovision.com/1057/">EIP-1057</a>: ProgPoW, a Programmatic Proof-of-Work</li> </ul> </li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-11-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Dean Eigenmanndean@ens.domains Nick Johnsonnick@ens.domains https://wg-eips.ritovision.com/1577/ <h2 id="abstract">Abstract</h2> <p>This EIP introduces the new <code>contenthash</code> field for ENS resolvers, allowing for a better defined system of mapping names to network and content addresses. Additionally the <code>content</code> and <code>multihash</code> fields are deprecated.</p> <h2 id="motivation">Motivation</h2> <p>Multiple applications including <a rel="external" href="https://metamask.io/">Metamask</a> and mobile clients such as <a rel="external" href="https://status.im">Status</a> have begun resolving ENS names to content hosted on distributed systems such as <a rel="external" href="https://ipfs.io/">IPFS</a> and <a rel="external" href="https://swarm-guide.readthedocs.io">Swarm</a>. Due to the various ways content can be stored and addressed, a standard is required so these applications know how to resolve names and that domain owners know how their content will be resolved.</p> <p>The <code>contenthash</code> field allows for easy specification of network and content addresses in ENS.</p> <h2 id="specification">Specification</h2> <p>The field <code>contenthash</code> is introduced, which permits a wide range of protocols to be supported by ENS names. Resolvers supporting this field MUST return <code>true</code> when the <code>supportsInterface</code> function is called with argument <code>0xbc1c58d1</code>.</p> <p>The fields <code>content</code> and <code>multihash</code> are deprecated.</p> <p>The value returned by <code>contenthash</code> MUST be represented as a machine-readable <a rel="external" href="https://github.com/multiformats/multicodec">multicodec</a>. The format is specified as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&lt;protoCode uvarint&gt;&lt;value []byte&gt;</span></span></code></pre> <p>protoCodes and their meanings are specified in the <a rel="external" href="https://github.com/multiformats/multicodec">multiformats/multicodec</a> repository.</p> <p>The encoding of the value depends on the content type specified by the protoCode. Values with protocodes of 0xe3 and 0xe4 represent IPFS and Swarm content; these values are encoded as v1 <a rel="external" href="https://github.com/multiformats/cid">CIDs</a> without a base prefix, meaning their value is formatted as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>&lt;protoCode uvarint&gt;&lt;cid-version&gt;&lt;multicodec-content-type&gt;&lt;multihash-content-address&gt;</span></span></code></pre> <p>When resolving a <code>contenthash</code>, applications MUST use the protocol code to determine what type of address is encoded, and resolve the address appropriately for that protocol, if supported.</p> <h3 id="example">Example</h3> <h4 id="ipfs">IPFS</h4> <p>Input data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>storage system: IPFS (0xe3)</span></span> <span class="giallo-l"><span>CID version: 1 (0x01)</span></span> <span class="giallo-l"><span>content type: dag-pb (0x70)</span></span> <span class="giallo-l"><span>hash function: sha2-256 (0x12)</span></span> <span class="giallo-l"><span>hash length: 32 bytes (0x20)</span></span> <span class="giallo-l"><span>hash: 29f2d17be6139079dc48696d1f582a8530eb9805b561eda517e22a892c7e3f1f</span></span></code></pre> <p>Binary format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xe3010170122029f2d17be6139079dc48696d1f582a8530eb9805b561eda517e22a892c7e3f1f</span></span></code></pre> <p>Text format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>ipfs://QmRAQB6YaCyidP37UdDnjFY5vQuiBrcqdyoW1CuDgwxkD4</span></span></code></pre><h3 id="swarm">Swarm</h3> <p>Input data:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>storage system: Swarm (0xe4)</span></span> <span class="giallo-l"><span>CID version: 1 (0x01)</span></span> <span class="giallo-l"><span>content type: swarm-manifest (0xfa)</span></span> <span class="giallo-l"><span>hash function: keccak256 (0x1b)</span></span> <span class="giallo-l"><span>hash length: 32 bytes (0x20)</span></span> <span class="giallo-l"><span>hash: d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162</span></span></code></pre> <p>Binary format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xe40101fa011b20d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162</span></span></code></pre> <p>Text format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>bzz://d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162</span></span></code></pre> <p>Example usage with swarm hash:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>$ swarm hash ens contenthash d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162 </span></span> <span class="giallo-l"><span>&gt; e40101fa011b20d1de9994b4d039f6548d191eb26786769f580809256b4685ef316805265ea162</span></span></code></pre><h3 id="fallback">Fallback</h3> <p>In order to support names that have an IPFS or Swarm hash in their <code>content</code> field, a grace period MUST be implemented offering those name holders time to update their names. If a resolver does not support the <code>multihash</code> interface, it MUST be checked whether they support the <code>content</code> interface. If they do, the value of that field SHOULD be treated in a context dependent fashion and resolved. This condition MUST be enforced until at least March 31st, 2019.</p> <h3 id="implementation">Implementation</h3> <p>To support <code>contenthash</code>, a new resolver has been developed and can be found <a rel="external" href="https://github.com/ensdomains/resolvers/blob/master/contracts/PublicResolver.sol">here</a>, you can also find this smart contract deployed on:</p> <ul> <li>Mainnet : <a rel="external" href="https://etherscan.io/address/0xd3ddccdd3b25a8a7423b5bee360a42146eb4baf3">0xd3ddccdd3b25a8a7423b5bee360a42146eb4baf3</a></li> <li>Ropsten : <a rel="external" href="https://ropsten.etherscan.io/address/0xde469c7106a9fbc3fb98912bb00be983a89bddca">0xde469c7106a9fbc3fb98912bb00be983a89bddca</a></li> </ul> <p>There are also implementations in multiple languages to encode and decode <code>contenthash</code>:</p> <ul> <li><a rel="external" href="https://github.com/pldespaigne/content-hash">JavaScript</a></li> <li><a rel="external" href="https://github.com/filips123/ContentHashPy">Python</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-11-13T00:00:00+00:00 2026-02-11T14:48:25+00:00 Michele Balistrerihttps://github.com/bitgamma https://wg-eips.ritovision.com/1581/

A derivation path structure for BIP32 trees to generate key pairs not meant to hold crypto assets.

<h2 id="abstract">Abstract</h2> <p>BIP32 defines a way to generate hierarchical trees of keys which can be derived from a common master key. BIP32 and <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki">BIP44</a> defines the usage of these keys as wallets. In this EIP we describe the usage of such keys outside the scope of the blockchain defining a logical tree for key usage which can coexist (and thus share the same master) with existing BIP44 compatible wallets.</p> <h2 id="motivation">Motivation</h2> <p>Applications interacting with the blockchain often make use of additional, non-blockchain technologies to perform the task they are designed for. For privacy and security sensitive mechanisms, sets of keys are needed. Reusing keys used for wallets can prove to be insecure, while keeping completely independent keys make backup and migration of the full set of credentials more complex. Defining a separate (from BIP44 compliant wallets) derivation branch allows combining the security of independent keys with the convenience of having a single piece of information which needs to be backup or migrated.</p> <h2 id="specification">Specification</h2> <h3 id="path-levels">Path levels</h3> <p>We define the following levels in BIP32 path:</p> <p><code>m / purpose' / coin_type' / subpurpose' / key_type' / key_index</code></p> <p>Apostrophe in the path indicates that BIP32 hardened derivation is used.</p> <p>This structure follows the <a rel="external" href="https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki">BIP43</a> recommendations and its <a rel="external" href="https://github.com/bitcoin/bips/pull/523/files">amendments for non-Bitcoin usage</a>. Each level has a special meaning, described in the chapters below.</p> <h3 id="purpose-coin-type-subpurpose">Purpose/Coin Type/Subpurpose</h3> <p>This part is constant and set to <code>m / 43' / 60' / 1581'</code>, meaning BIP 43 -&gt; Ethereum -&gt; This EIP.</p> <p>All subtrees under this prefix are the scope of this EIP.</p> <h3 id="key-type">Key type</h3> <p>Describes the purpose for which the key is being used. Key types should be generic. "Instant messaging" is a good example whereas "Whisper" is not. The reason is that you want to be able to use the same identity across different services. Key types are defined at: TBD</p> <p>Hardened derivation is used at this level.</p> <h3 id="key-index">Key index</h3> <p>The key index is a field of variable length identifying a specific key. In its simplest case, it is a number from 0 to 2^31-1. If a larger identifier is desired (for example representing a hash or a GUID), the value must be split across several BIP32 nesting levels, most significant bit first and left aligned, bit-padded with 0s if needed. All levels, except the last one must used hardened key derivation. The last level must use public derivation. This means that every level can carry 31-bit of the identifier to represent.</p> <p>As an example, let's assume we have a key with key type 4' and a key_index representing a 62-bit ID represented as hexadecimal 0x2BCDEFFEDCBAABCD the complete keypath would be <code>m / 43' / 60' / 1581' / 4' / ‭1469833213‬' / ‭1555737549‬ </code>. If you are using random identifiers, it might be convenient to generate a conventional GUID, for example 128-bit just fix the value of the most significant bit of each 32-bit word to 1 for all of them, except the last one which will be 0.</p> <h2 id="rationale">Rationale</h2> <p>The structure proposed above follows the BIP43 generic structure and is similar to the widely adopted BIP44 specification.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-11-09T00:00:00+00:00 2026-02-11T14:49:27+00:00 Andrea Lanfranchihttps://github.com/AndreaLanfranchi Pawel Bylicahttps://github.com/chfast Marius Van Der Wijdenhttps://github.com/MariusVanDerWijden https://wg-eips.ritovision.com/1571/ <h2 id="abstract">Abstract</h2> <p>This draft contains the guidelines to define a new standard for the Stratum protocol used by Ethereum miners to communicate with mining pool servers.</p> <h3 id="conventions">Conventions</h3> <p>The key words <code>MUST</code>, <code>MUST NOT</code>, <code>REQUIRED</code>, <code>SHALL</code>, <code>SHALL NOT</code>, <code>SHOULD</code>, <code>SHOULD NOT</code>, <code>RECOMMENDED</code>, <code>MAY</code>, and <code>OPTIONAL</code> in this document are to be interpreted as described in <a rel="external" href="https://tools.ietf.org/html/rfc2119">RFC 2119</a>. The definition <code>mining pool server</code>, and it's plural form, is to be interpreted as <code>work provider</code> and later in this document can be shortened as <code>pool</code> or <code>server</code>. The definition <code>miner(s)</code>, and it's plural form, is to be interpreted as <code>work receiver/processor</code> and later in this document can be shortened as <code>miner</code> or <code>client</code>.</p> <h3 id="rationale">Rationale</h3> <p>Ethereum does not have an official Stratum implementation yet. It officially supports only getWork which requires miners to constantly pool the work provider. Only recently go-ethereum have implemented a <a rel="external" href="https://github.com/ethereum/go-ethereum/pull/17347">push mechanism</a> to notify clients for mining work, but whereas the vast majority of miners do not run a node, it's main purpose is to facilitate mining pools rather than miners. The Stratum protocol on the other hand relies on a standard stateful TCP connection which allows two-way exchange of line-based messages. Each line contains the string representation of a JSON object following the rules of either <a rel="external" href="https://www.jsonrpc.org/specification_v1">JSON-RPC 1.0</a> or <a rel="external" href="https://www.jsonrpc.org/specification">JSON-RPC 2.0</a>. Unfortunately, in absence of a well defined standard, various flavours of Stratum have bloomed for Ethereum mining as a derivative work for different mining pools implementations. The only attempt to define a standard was made by NiceHash with their <a rel="external" href="https://github.com/nicehash/Specifications/blob/master/EthereumStratum_NiceHash_v1.0.0.txt">EthereumStratum/1.0.0</a> implementation which is the main source this work inspires from. Mining activity, thus the interaction among pools and miners, is at it's basics very simple, and can be summarized with "<em>please find a number (nonce) which coupled to this data as input for a given hashing algorithm produces, as output, a result which is below a certain target</em>". Other messages which may or have to be exchanged among parties during a session are needed to support this basic concept. Due to the simplicity of the subject, the proponent, means to stick with JSON formatted objects rather than investigating more verbose solutions, like for example <a rel="external" href="https://developers.google.com/protocol-buffers/docs/overview">Google's Protocol Buffers</a> which carry the load of strict object definition.</p> <h3 id="stratum-design-flaws">Stratum design flaws</h3> <p>The main Stratum design flaw is the absence of a well defined standard. This implies that miners (and mining software developers) have to struggle with different flavours which make their life hard when switching from one pool to another or even when trying to "guess" which is the flavour implemented by a single pool. Moreover all implementations still suffer from an excessive verbosity for a chain with a very small block time like Ethereum. A few numbers may help understand. A normal <code>mining.notify</code> message weigh roughly 240 bytes: assuming the dispatch of 1 work per block to an audience of 50k connected TCP sockets means the transmission of roughly 1.88TB of data a month. And this can be an issue for large pools. But if we see the same figures the other way round, from a miner's perspective, we totally understand how mining decentralization is heavily affected by the quality of internet connections.</p> <h3 id="sources-of-inspiration">Sources of inspiration</h3> <ul> <li><a rel="external" href="https://github.com/nicehash/Specifications/blob/master/EthereumStratum_NiceHash_v1.0.0.txt">NiceHash EthereumStratum/1.0.0</a></li> <li><a rel="external" href="https://github.com/zcash/zips/blob/23d74b0373c824dd51c7854c0e3ea22489ba1b76/drafts/str4d-stratum/draft1.rst#json-rpc-1-0">Zcash variant of the Stratum protocol</a></li> </ul> <h2 id="specification">Specification</h2> <p>The Stratum protocol is an instance of <a rel="external" href="https://www.jsonrpc.org/specification">JSON-RPC-2.0</a>. The miner is a JSON-RPC client, and the server is a JSON-RPC server. All communications exist within the scope of a <code>session</code>. A session starts at the moment a client opens a TCP connection to the server till the moment either party do voluntary close the very same connection or it gets broken. Servers <strong>MAY</strong> support session resuming if this is initially negotiated (on first session handshaking) between the client and the server. During a session all messages exchanged among server and client are line-based which means all messages are JSON strings terminated by ASCII LF character (which may also be denoted as <code>\n</code> in this document). The LF character <strong>MUST NOT</strong> appear elsewhere in a message. Client and server implementations <strong>MUST</strong> assume that once they read a LF character, the current message has been completely received and can be processed. Line messages are of three types:</p> <ul> <li><code>Requests</code> : messages for which the issuer expects a response. The receiver <strong>MUST</strong> reply back to any request individually</li> <li><code>Responses</code> : solicited messages by a previous request. The responder <strong>MUST</strong> label the response with the same identifier of the originating request.</li> <li><code>Notifications</code> : unsolicited messages for which the issuer is not interested nor is expecting a response. Nevertheless a response (eg. an acknowledgement) <strong>MAY</strong> be sent by the receiver.</li> </ul> <p>During a <code>session</code> both parties <strong>CAN</strong> exchange messages of the above depicted three types.</p> <h3 id="json-rpc-2-0-compliances">JSON-RPC-2.0 Compliances</h3> <p>As per <a rel="external" href="https://www.jsonrpc.org/specification">JSON-RPC-2.0</a> specification requests and responses differ from notifications by the identifier (<code>id</code>) member in the JSON object:</p> <ul> <li>Requests <strong>MUST</strong> have an <code>id</code> member</li> <li>Responses <strong>MUST</strong> have an <code>id</code> member valued exactly as the <code>id</code> member of the request this response is for</li> <li>Notifications <strong>MUST NOT</strong> have an <code>id</code> member</li> </ul> <h3 id="json-rpc-2-0-defiances">JSON-RPC-2.0 Defiances</h3> <p>In order to get the most concise messages among parties of a session/conversation this implementation enforces the following defiances:</p> <ul> <li>JSON member <code>jsonrpc</code> (always valued to "2.0") <strong>MUST ALWAYS BE OMITTED</strong></li> <li>JSON member <code>id</code> <strong>MUST NOT</strong> be <code>null</code>. When member is present, mandatorily in requests and responses, it <strong>MUST</strong> be valued to an integer Number ranging from 0 to 65535. Please note that a message with <code>"id": 0</code> <strong>MUST NOT</strong> be interpreted as a notification: it's a request with identifier 0</li> <li>JSON member <code>id</code> <strong>MUST</strong> be only of type primitive number. The removal of other identifier types (namely strings) is due to the need to reduce the number of bytes transferred.</li> </ul> <h2 id="conventions-1">Conventions</h2> <ul> <li>The representation of a JSON object is, at it's base, a string</li> <li>The conversation among the client and the server is made of strings. Each string ending with a LF (ASCII char 10) denotes a <code>line</code>. Each line <strong>MUST</strong> contain only one JSON root object. Eventually the root object <strong>MAY</strong> contain additional JSON objects in it's members.</li> <li>Aside the <code>LF</code> delimiter each <code>line</code> <strong>MUST</strong> be made of printable ASCII chars in the range 32..126</li> <li>It's implicit and mandatory that each line message corresponds to a well formatted JSON object: see <a rel="external" href="https://www.json.org/">JSON documentation</a></li> <li>JSON objects are made of <code>members</code> which can be of type : primitive of string/number, JSON object, JSON arrays</li> <li>JSON <code>member</code>'s names are strings which <strong>MUST</strong> be composed of printable chars only in the ASCII range 48..57 (numbers) and 97..122 (lower case letters).</li> <li>JSON <code>member</code>'s names <strong>MUST NOT</strong> begin with a number.</li> <li>JSON values <code>arrays</code> : although the JSON notation allows the insertion of different data types within the same array, this behavior is generally not accepted in coding languages. Due to this, by the means of EthereumStratum/2.0.0, all implementers <strong>MUST</strong> assume that an array is made of elements of the very same data type.</li> <li>JSON values <code>booleans</code> : the JSON notation allows to express boolean values as <code>true</code> or <code>false</code>. In EthereumStratum/2.0.0, for better compatibility within arrays, boolean values will be expressed in the hex form of "0" (false) or "1" (true)</li> <li>JSON values <code>strings</code> : any string value <strong>MUST</strong> be composed of printable ASCII chars only in the ASCII range 32..126. Each string is delimited by a <code>"</code> (ASCII 34) at the beginning and at the end. Should the string value contain a <code>"</code> this must be escaped as <code>\"</code></li> <li>Hex values : a Hexadecimal representation of a number is actually a string data type. As a convention, and to reduce the number of transmitted bytes, the prefix "0x" <strong>MUST</strong> always be omitted. In addition any hex number <strong>MUST</strong> be transferred only for their significant part i.e. the non significant zeroes <strong>MUST</strong> be omitted (example : the decimal <code>456</code> must be represented as <code>"1c8"</code> and not as <code>"01c8"</code> although the conversion produces the same decimal value). This directive <strong>DOES NOT APPLY</strong> to hashes and extranonces</li> <li>Hex values casing : all letters in Hexadecimal values <strong>MUST</strong> be lower case. (example : the decimal <code>456</code> must be represented as <code>"1c8"</code> and not as <code>"1C8"</code> although the conversion produces the same decimal value). This directive <strong>DOES NOT APPLY</strong> to hashes.</li> <li>Numbers : any non-fractional number <strong>MUST</strong> be transferred by it's hexadecimal representation</li> </ul> <h3 id="requests">Requests</h3> <p>The JSON representation of <code>request</code> object is made of these parts:</p> <ul> <li>mandatory <code>id</code> member of type Integer : the identifier established by the issuer</li> <li>mandatory <code>method</code> member of type String : the name of the method to be invoked on the receiver side</li> <li>optional <code>params</code> member : in case the method invocation on the receiver side requires the application of additional parameters to be executed. The type <strong>CAN</strong> be Object (with named members of different types) or Array of single type. In case of an array the parameters will be applied by their ordinal position. If the method requested for invocation on the receiver side does not require the application of additional parameters this member <strong>MUST NOT</strong> be present. The notation <code>"params" : null</code> <strong>IS NOT PERMITTED</strong></li> </ul> <h3 id="responses">Responses</h3> <p>The JSON representation of <code>response</code> object is made of these parts:</p> <ul> <li>mandatory <code>id</code> member of type Integer : the identifier of the request this response corresponds to</li> <li>optional <code>error</code> member : whether an error occurred during the parsing of the method or during it's execution this member <strong>MUST</strong> be present and valued. If no errors occurred this member <strong>MUST NOT</strong> be present. For a detailed structure of the <code>error</code> member see below.</li> <li>optional <code>result</code> member : This has to be set, if the corresponding request requires a result from the user. If no errors occurred by invoking the corresponding function, this member <strong>MUST</strong> be present even if one or more information are null. The type can be of Object or single type Array or Primitive string/number. If no data is meant back for the issuer (the method is void on the receiver) or an error occurred this member <strong>MUST NOT</strong> be present.</li> </ul> <p>You'll notice here some differences with standard JSON-RPC-2.0. Namely the result member is not always required. Basically a response like this:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 2</span><span>}</span></span></code></pre> <p>means "request received and processed correctly with no data to send back".</p> <p>To better clarify the concept and clear the field of free interpretations let's take another example of <strong>wrong response</strong></p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 2</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>}</span></span></code></pre> <p>This response syntax leaves room to many interpretations: is it an error? is <code>false</code> the legit response value to the issued request?</p> <p>For this reason responses, we reiterate, <strong>MUST BE</strong> of two types:</p> <ul> <li>success responses : no error occurred during the processing, the request was legit, syntactically correct, and the receiver had no issues processing it. This kind of responses <strong>MUST NOT</strong> have the <code>error</code> member and <strong>MAY</strong> have the <code>result</code> member if a value is expected back to the issuer.</li> <li>failure responses : something wrong with the request, it's syntax, it's validity scope, or server processing problems. This kind of responses <strong>MUST HAVE</strong> the <code>error</code> member and <strong>MAY</strong> have the <code>result</code> member.</li> </ul> <p>The latter deserves a better explanation: failure responses can be distinguished by a severity degree. Example 1 : a client submits a solution and server rejects it cause it's not below target. Server <strong>MUST</strong> respond like this;</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 31</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">error</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">code</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 406</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Bad nonce</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Example 2 : a client submits a solution and server <strong>accepts</strong> it <strong>but</strong> it accounts the share as stale. Server <strong>MUST</strong> respond like this;</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 31</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">error</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">code</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 202</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Stale</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Example 3 : a client submits an authorization request specifying an invalid workername. Server authorizes the account but rejects worker name. Server <strong>MUST</strong> respond like this;</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">error</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">code</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 215</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Invalid Worker Name</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Example 1 depicts the condition of a severe failure while Example 2 and 3 depict a situation where the request has been accepted and processed properly but the result <strong>MAY NOT</strong> be what expected by the client. It's up to the client to evaluate the severity of the error and decide whether to proceed or not.</p> <p>Using proper error codes pools may properly inform miners of the condition of their requests. Error codes <strong>MUST</strong> honor this scheme:</p> <ul> <li>Error codes 2xx : request accepted and processed but some additional info in the <code>error</code> member may give hint</li> <li>Error codes 3xx : server could not process the request due to a lack of authorization by the client</li> <li>Error codes 4xx : server could not process the request due to syntactic problems (method not found, missing params, wrong data types ecc.) or passed <code>param</code> values are not valid.</li> <li>Error codes 5xx : server could not process the request due to internal errors</li> </ul> <h3 id="notifications">Notifications</h3> <p>A notification message has the very same representation of a <code>request</code> with the only difference the <code>id</code> member <strong>MUST NOT</strong> be present. This means the issuer is not interested nor expects any response to this message. It's up to the receiver to take actions accordingly. For instance the receiver <strong>MAY</strong> decide to execute the method, or, in case of errors or methods not allowed, drop the connection thus closing the session.</p> <h4 id="error-member">Error member</h4> <p>As seen above a <code>response</code> <strong>MAY</strong> contain an <code>error</code> member. When present this member <strong>MUST</strong> be an Object with:</p> <ul> <li>mandatory member <code>code</code> : a Number which identifies the error occurred</li> <li>mandatory member <code>message</code> : a short human readable sentence describing the error occurred</li> <li>optional member <code>data</code> : a Structured or Primitive value that contains additional information about the error. The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).</li> </ul> <h2 id="protocol-flow">Protocol Flow</h2> <ul> <li>Client starts session by opening a TCP socket to the server</li> <li>Client advertises and request protocol compatibility</li> <li>Server confirms compatibility and declares ready</li> <li>Client starts/resumes a session</li> <li>Client sends request for authorization for each of it's workers</li> <li>Server replies back with responses for each authorization</li> <li>Server sends <code>mining.set</code> for constant values to be adopted for following mining jobs</li> <li>Server sends <code>mining.notify</code> with minimal job info</li> <li>Client mines on job</li> <li>Client sends <code>mining.submit</code> if any solution found for the job</li> <li>Server replies whether solution is accepted</li> <li>Server optionally sends <code>mining.set</code> for constant values to be adopted for following mining jobs (if something changed)</li> <li>Server sends <code>mining.notify</code> with minimal job info</li> <li>... (continue)</li> <li>Eventually either party closes session and TCP connection</li> </ul> <h3 id="session-handling-hello">Session Handling - Hello</h3> <p><del>One of the worst annoyances until now is that server, at the very moment of socket connection, does not provide any useful information about the stratum flavour implemented. This means the client has to start a conversation by iteratively trying to connect via different protocol flavours. This proposal amends the situation making mandatory for the server to advertise itself to the client. When a new client connects to the server, the server <strong>MUST</strong> send a <code>mining.hello</code> notification :</del></p> <p>It's been noted that charging the server of the duty to advertise itself as first message of the conversation could potentially be harmful in respect of traffic amplification attacks using spoofed IP addresses or in traditional DDos attacks where an attacker need to spend very little resources to force the server to send a large packet back. For this reason the duty of first advertisement is kept on client which will issue a <code>mining.hello</code> request like this:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span> :</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.hello</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> </span></span> <span class="giallo-l"><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">agent</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ethminer-0.17</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">host</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">somemininigpool.com</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">port</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">4d2</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">proto</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">EthereumStratum/2.0.0</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>params</code> member object has these mandatory members:</p> <ul> <li><code>agent</code> (string) the mining software version</li> <li><code>host</code> (string) the host name of the server this client is willing to connect to</li> <li><code>port</code> (hex) the port number of the server this client is willing to connect to</li> <li><code>proto</code> (string) which reports the stratum flavour requested and expected to be implemented by the server;</li> </ul> <p>The rationale behind sending host and port is it enables virtual hosting, where virtual pools or private URLs might be used for DDoS protection, but that are aggregated on Stratum server backends. As with HTTP, the server CANNOT trust the host string. The port is included separately to parallel the client.reconnect method (see below).</p> <p>If the server is prepared to start/resume a session with such requirements it <strong>MUST</strong> reply back with a response like this:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span> :</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span> </span></span> <span class="giallo-l"><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">proto</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">EthereumStratum/2.0.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">encoding</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">gzip</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">resume</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">timeout</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">b4</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">maxerrors</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">5</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">node</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Geth/v1.8.18-unstable-f08f596a/linux-amd64/go1.10.4</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Where the <code>result</code> is an object made of 5 mandatory members</p> <ul> <li><code>proto</code> (string) which <strong>MUST</strong> match the exact version requested by the client</li> <li><code>encoding</code> (string) which value states whether or not all <strong>next messages</strong> should be gzip compressed or not. Possible values are "gzip" or "plain"</li> <li><code>resume</code> (hex) which value states whether or not the host can resume a previously created session;</li> <li><code>timeout</code> (hex) which reports the number of seconds after which the server is allowed to drop connection if no messages from the client</li> <li><code>maxerrors</code> (hex) the maximum number of errors the server will bear before abruptly close connection</li> <li><code>node</code> (string) the node software version underlying the pool</li> </ul> <p>When the server replies back with <code>"encoding" : "gzip"</code> to the client, both parties <strong>MUST</strong> gzip compress all next messages. In case the client is not capable of compression it <strong>MUST</strong> close the connection immediately. Should the server, after this reply, receive other messages as plain text, it <strong>MUST</strong> close the connection.</p> <p>Eventually the client will continue with <code>mining.subscribe</code> (further on descripted)</p> <p>Otherwise, in case of errors or rejection to start the conversation, the server <strong>MAY</strong> reply back with an error giving the other party useful information or, at server's maintainers discretion, abruptly close the connection.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span> :</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">error</span><span class="z-support">&quot;</span><span>:</span><span> </span></span> <span class="giallo-l"><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">code</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 400</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Bad protocol request</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>or</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span> :</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">error</span><span class="z-support">&quot;</span><span>:</span><span> </span></span> <span class="giallo-l"><span> {</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">code</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 403</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Forbidden - Banned IP address</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span> </span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><em>The above two JSON error values are only samples</em> Eventually the server will close the connection.</p> <p>Why a pool should advertise the node's version? It's a matter of transparency : miners should know whether or not pool have upgraded to latest patches/releases for node's software.</p> <h3 id="session-handling-bye">Session Handling - Bye</h3> <p>Disconnection are not gracefully handled in Stratum. Client disconnections from pool may be due to several errors and this leads to waste of TCP sockets on server's side which wait for keepalive timeouts to trigger. A useful notification is <code>mining.bye</code> which, once processed, allows both parties of the session to stop receiving and gracefully close TCP connections</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.bye</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The party receiving this message aknowledges the other party wants to stop the conversation and closes the socket. The issuer will close too. The explicit issuance of this notification implies the session gets abandoned so no session resuming will be possible even on server which support session-resuming. Client reconnecting to the same server which implements session resuming <strong>SHOULD</strong> expect a new session id and <strong>MUST</strong> re-authorize all their workers.</p> <h3 id="session-handling-session-subscription">Session Handling - Session Subscription</h3> <p>After receiving the response to <code>mining.hello</code> from server, the client, in case the server does support session resuming <strong>MAY</strong> request to resume a previously interrupted session with <code>mining.subscribe</code> request:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.subscribe</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">s-12345</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>where <code>params</code> is the id of the session the client wants to resume.</p> <p>Otherwise, if client wants to start a new session <strong>OR</strong> server does not support session resuming, the request of subscription <strong>MUST</strong> omit the <code>params</code> member:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.subscribe</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="session-handling-response-to-subscription">Session Handling - Response to Subscription</h3> <p>A server receiving a client session subscription <strong>MUST</strong> reply back with</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">s-12345</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A server receiving a subscription request with <code>params</code> being a string holding the session id. This cases may apply</p> <ul> <li>If session resuming is not supported <code>result</code> will hold a new session Id which <strong>MUST</strong> be a different value from the <code>session</code> member issued by client in previous <code>mining.subscribe</code> method</li> <li>If session resuming is supported it will retrieve working values from cache and <code>result</code> will have the same id requested by the client. This means a session is "resumed": as a consequence the server <strong>CAN</strong> start pushing jobs omitting to precede them with <code>mining.set</code> (see below) and the client <strong>MUST</strong> continue to use values lastly received within the same session scope. In addition the client <strong>CAN</strong> omit to re-authorize all it's workers.</li> <li>If session resuming is supported but the requested session has expired or it's cache values have been purged <code>result</code> will hold a new session Id which <strong>MUST</strong> be a different value from the <code>session</code> member issued by client in previous <code>mining.subscribe</code> method. As a consequence the server <strong>MUST</strong> wait for client to request authorization for it's workers and <strong>MUST</strong> send <code>mining.set</code> values before pushing jobs. The client <strong>MUST</strong> prepare for a new session discarding all previously cached values (if any).</li> </ul> <p>A server implementing session-resuming <strong>MUST</strong> cache:</p> <ul> <li>The session Ids</li> <li>Any active job per session</li> <li>The extraNonce</li> <li>Any authorized worker</li> </ul> <p>Servers <strong>MAY</strong> drop entries from the cache on their own schedule. It's up to server to enforce session validation for same agent and/or ip.</p> <p>A client which successfully subscribes and resumes session (the <code>session</code> value in server response is identical to <code>session</code> value requested by client on <code>mining.subscribe</code>) <strong>CAN</strong> omit to issue the authorization request for it's workers.</p> <h3 id="session-handling-noop">Session Handling - Noop</h3> <p>There are cases when a miner struggles to find a solution in a reasonable time so it may trigger the timeout imposed by the server in case of no communications (the server, in fact, may think the client got disconnected). To mitigate the problem a new method <code>mining.noop</code>(with no additional parameters) may be requested by the client.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 50</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.noop</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="session-handling-reconnect">Session Handling - Reconnect</h3> <p>Under certain circumstances the server may need to free some resources and or to relocate miners to another machine. Until now the only option for servers was to abruptly close the connection. On the miner's side this action is interpreted as a server malfunction and they, more often than not, switch to a failover pool. The implementation of the notification <code>mining.reconnect</code> helps client to better merge with logic of handling of large mining pools.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.reconnect</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">host</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">someotherhost.com</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">port</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">d80</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">resume</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This notification is meant only from servers to clients. Should a server receive such a notification it will simply ignore it. After the notification has been properly sent, the server is ALLOWED to close the connection, while the client will take the proper actions to reconnect to the suggested end-point. The <code>host</code> member in <code>params</code> object <strong>SHOULD</strong> report a host DNS name and not an IP address: TLS encrypted connections require to validate the CN name in the certificate which, 99% of the cases, is a host name. The third member <code>resume</code> of the <code>params</code> object sets whether or not the receiving server is prepared for session resuming. After this notification has been issued by the server, the client should expect no further messages and <strong>MUST</strong> disconnect.</p> <h3 id="workers-authorization">Workers Authorization</h3> <p>The miner <strong>MUST</strong> authorize at least one worker in order to begin receiving jobs and submit solutions or hashrates. The miner <strong>MAY</strong> authorize multiple workers in the same session. The server <strong>MUST</strong> allow authorization for multiple workers within a session and <strong>MUST</strong> validate at least one authorization from the client before starting to send jobs. A <code>worker</code> is a tuple of the address where rewards must be credited coupled with identifier of the machine actually doing the work. For Ethereum the most common form is <code>&lt;account&gt;.&lt;MachineName&gt;</code>. The same account can be bound to multiple machines. For pool's allowing anonymous mining the account is the address where rewards must be credited, while, for pools requiring registration, the account is the login name. Each time a solution is submitted by the client it must be labelled with the Worker identifier. It's up to server to keep the correct accounting for different addresses.</p> <p>The syntax for the authorization request is the following:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.authorize</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">&lt;account&gt;[.&lt;MachineName&gt;]</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">password</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>params</code> member must be an Array of 2 string elements. For anonymous mining the "password" can be any string value or empty but not null. Pools allowing anonymous mining will simply ignore the value. The server <strong>MUST</strong> reply back either with an error or, in case of success, with</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">w-123</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Where the <code>result</code> member is a string which holds an unique - within the scope of the <code>session</code> - token which identifies the authorized worker. For every further request issued by the client, and related to a Worker action, the client <strong>MUST</strong> use the token given by the server in response to an <code>mining.authorize</code> request. This reduces the number of bytes transferred for solution and /or hashrate submission.</p> <p>If client is resuming a previous session it <strong>CAN</strong> omit the authorization request for it's workers and, in this case, <strong>MUST</strong> use the tokens assigned in the originating session. It's up to the server to keep the correct map between tokens and workers. The server receiving an authorization request where the credentials match previously authorized ones within the same session <strong>MUST</strong> reply back with the previously generated unique token.</p> <h3 id="prepare-for-mining">Prepare for mining</h3> <p>A lot of data is sent over the wire multiple times with useless redundancy. For instance the seed hash is meant to change only every 30000 blocks (roughly 5 days) while fixed-diff pools rarely change the work target. Moreover pools must optimize the search segments among miners trying to assign to every session a different "startNonce" (AKA extraNonce). For this purpose the <code>notification</code> method <code>mining.set</code> allows to set (on miner's side) only those params which change less frequently. The server will keep track of seed, target and extraNonce at session level and will push a notification <code>mining.set</code> whenever any (or all) of those values change to the connected miner.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.set</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">epoch</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">dc</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">target</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0112e0be826d694b2e62d01511f12a6061fbaec8bc02357593e70e52ba</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">algo</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">ethash</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">extranonce</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">af4c</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>At the beginning of each <code>session</code> the server <strong>MUST</strong> send this notification before any <code>mining.notify</code>. All values passed by this notification will be valid for all <strong>NEXT</strong> jobs until a new <code>mining.set</code> notification overwrites them. Description of members is as follows:</p> <ul> <li>optional <code>epoch</code> (hex) : unlike all actual Stratum implementations the server should inform the client of the epoch number instead of passing the seed hash. This is enforced by two reasons: the main one is that client has only one way to compute the epoch number and this is by a linear search from epoch 0 iteratively trying increasing epochs till the hash matches the seed hash. Second reason is that epoch number is more concise than seed hash. In the end the seed hash is only transmitted to inform the client about the epoch and is not involved in the mining algorithm.</li> <li>optional <code>target</code> (hex) : this is the boundary hash already adjusted for pool difficulty. Unlike in EthereumStratum/1.0.0, which provides a <code>mining.set_difficulty</code> notification of an <em>index of difficulty</em>, the proponent opt to pass directly the boundary hash. If omitted the client <strong>MUST</strong> assume a boundary of <code>"0x00000000ffff0000000000000000000000000000000000000000000000000000"</code></li> <li>optional <code>algo</code> (string) : the algorithm the miner is expected to mine on. If omitted the client <strong>MUST</strong> assume <code>"algo": "ethash"</code></li> <li>optional <code>extranonce</code> (hex) : a starting search segment nonce assigned by server to clients so they possibly do not overlap their search segments. If server wants to "cancel" a previously set extranonce it must pass this member valued as an empty string.</li> </ul> <p>Whenever the server detects that one, or two, or three or four values change within the session, the server will issue a notification with one, or two or three or four members in the <code>param</code> object. For this reason on each <strong>new</strong> session the server <strong>MUST</strong> pass all four members. As a consequence the miner is instructed to adapt those values on <strong>next</strong> job which gets notified. The new <code>algo</code> member is defined to be prepared for possible presence of algorithm variants to ethash, namely ethash1a or ProgPow. Pools providing multicoin switching will take care to send a new <code>mining.set</code> to miners before pushing any job after a switch. The client which can't support the data provided in the <code>mining.set</code> notification <strong>MAY</strong> close connection or stay idle till new values satisfy it's configuration (see <code>mining.noop</code>). All client's implementations <strong>MUST</strong> be prepared to accept new extranonces during the session: unlike in EthereumStratum/1.0.0 the optional client advertisement <code>mining.extranonce.subscribe</code> is now implicit and mandatory.</p> <p>The miner receiving the <code>extranonce</code> <strong>MUST</strong> initialize the search segment for next job resizing the extranonce to a hex of 16 bytes thus appending as many zeroes as needed. Extranonce "af4c" means "<em>search segment of next jobs starts from 0xaf4c000000000000</em>" If <code>extranonce</code> is valued to an empty string, or it's never been set within the session scope, the client is free pick any starting point of it's own search segment on subsequent <code>mining.notify</code> jobs.</p> <h3 id="a-detail-of-extranonce">A detail of "extranonce"</h3> <p>Miners connected to a pool might likely process the very same nonces thus wasting a lot of duplicate jobs. A <code>nonce</code> is any valid number which, applied to algorithm and job specifications, produces a result which is below a certain target. For every job pushed by server to client(s) there are 2^64 possible nonces to test.</p> <p>To be noted that:</p> <ul> <li>Any nonce in the 2^64 has the very same possibility to be the right one.</li> <li>A certain hashing job can be solved by more than one nonce</li> </ul> <p>Every "test" over a number is called a hash. Assuming a miner should receive a job for each block and considering the actual average block time of 15 seconds that would mean a miner should try</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> ( 2^64 / 15 ) / 1T ~ 1,229,782.94 TeraHashes per second</span></span></code></pre> <p>This computation capacity is well beyond any miner on the market (including ASICs). For this reason single miners can process only small chunks (segments) of this humongous range. The way miners pick the segments to search on is beyond the scope of this work. Fact is as miners are not coordinated there is no knowledge - for a single miner - of segments picked by other miners. Extranonce concept is here to mitigate this possibility of duplicate jobs charging the server (the work provider) to give miners, at the maximum possible extent, different segments to search on.</p> <p>Giving the above assumptions we can depict a nonce as any number in the hex range:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> Min 0x0000000000000000</span></span> <span class="giallo-l"><span> Max 0xffffffffffffffff</span></span></code></pre> <p><em>the prefix 0x is voluntarily inserted here only to give a better visual representation</em>.</p> <p>The <code>extranonce</code> is, at it's basics, the message of the server saying the client "<em>I give you the first number to start search from</em>". More in detail the <code>extranonce</code> is the leftmost part of that number. Assume a pool notifies the client the usage of extranonce <code>ab5d</code> this means the client will see it's search segment narrowed as</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> Min 0xab5d000000000000</span></span> <span class="giallo-l"><span> Max 0xab5dffffffffffff</span></span></code></pre> <p>Pushing an extranonce of 4 bytes (like in the example) will give pool the possibility to separate segment 65535 different miners ( or if you prefer 0xffff miners ) while leaving the miner still a segment of 2^48 possible nonces to search on. Recalculating, as above, the computation capacity needed to search this segment we get</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> ( 2^48 / 15 ) / 1T ~ 18.76 TeraHashes per second</span></span></code></pre> <p>Which is still a wide segment where miners can randomly (or using other ergodic techniques) pick their internal search segments.</p> <p>Extranonce <strong>MUST</strong> be passed with all relevant bytes (no omission of left zeroes) for a specific reason. Assume an extranonce of "01ac" : it has the same decimal value of "1ac" but the number of bytes changes thus changing available search segment</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> When &quot;01ac&quot; When &quot;1ac&quot;</span></span> <span class="giallo-l"><span> Segment is Segment is</span></span> <span class="giallo-l"><span> Min 0x01ac000000000000 Min 0x1ac0000000000000</span></span> <span class="giallo-l"><span> Max 0x01acffffffffffff Max 0x1acfffffffffffff</span></span></code></pre> <p>As you can see resulting segments are quite different</p> <p>This all said pools (server), when making use of extranonce, <strong>MUST</strong> observe a maximum length of 6 bytes (hex).</p> <h3 id="jobs-notification">Jobs notification</h3> <p>When available server will dispatch jobs to connected miners issuing a <code>mining.notify</code> notification.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.notify</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bf0488aa</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">6526d5</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">645cf20198c2f3861e947d4f67e3ab63b7b2e24dcc9095bd9123e7b33371f6cc</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>params</code> member is made of 4 mandatory elements:</p> <ul> <li>1st element is jobId as specified by pool. To reduce the amount of data sent over the wire pools <strong>SHOULD</strong> keep their job IDs as concise as possible. Pushing a Job id which is identical to headerhash is a bad practice and is highly discouraged.</li> <li>2nd element is the hex number of the block id</li> <li>3rd element is the headerhash.</li> <li>4th element is an hex boolean indicating whether or not eventually found shares from previous jobs will be accounted for sure as stale.</li> </ul> <h3 id="solution-submission">Solution submission</h3> <p>When a miner finds a solution for a job he is mining on it sends a <code>mining.submit</code> request to server.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 31</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.submit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bf0488aa</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">68765fccd712</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">w-123</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>First element of <code>params</code> array is the jobId this solution refers to (as sent in the <code>mining.notify</code> message from the server). Second element is the <code>miner nonce</code> as hex. Third element is the token given to the worker previous <code>mining.authorize</code> request. Any <code>mining.submit</code> request bound to a worker which was not successfully authorized - i.e. the token does not exist in the session - <strong>MUST</strong> be rejected.</p> <p>You'll notice in the sample above the <code>miner nonce</code> is only 12 bytes wide (should be 16). Why? That's because in the previous <code>mining.set</code> the server has set an <code>extranonce</code> of <code>af4c</code>. This means the full nonce is <code>af4c68765fccd712</code> In presence of extranonce the miner <strong>MUST</strong> submit only the chars to append to the extranonce to build the final hex value. If no extranonce is set for the session or for the work the miner <strong>MUST</strong> send all 16 bytes.</p> <p>It's server duty to keep track of the tuples <code>job ids &lt;-&gt; extranonces</code> per session.</p> <p>When the server receives this request it either responds success using the short form</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 31</span><span>}</span></span></code></pre> <p>or, in case of any error or condition with a detailed error object</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 31</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">error</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">code</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 404</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Job not found</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Client <strong>should</strong> treat errors as "soft" errors (stales) or "hard" (bad nonce computation, job not found etc.). Errors in 5xx range are server errors and suggest the miner to abandon the connection and switch to a failover.</p> <h3 id="hashrate">Hashrate</h3> <p>Most pools offer statistic information, in form of graphs or by API calls, about the calculated hashrate expressed by the miner while miners like to compare this data with the hashrate they read on their devices. Communication about parties of these information have never been coded in Stratum and most pools adopt the method from getWork named <code>eth_submitHashrate</code>. In this document we propose an official implementation of the <code>mining.hashrate</code> request. This method behaves differently when issued from client or from server.</p> <h4 id="client-communicates-it-s-hashrate-to-server">Client communicates it's hashrate to server.</h4> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span> :</span><span class="z-constant"> 16</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.hashrate</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">500000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">w-123</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>where <code>params</code> is an array made of two elements: the first is a hexadecimal string representation (32 bytes) of the hashrate the miner reads on it's devices and the latter is the authorization token issued to worker this hashrate is refers to (see above for <code>mining.authorization</code>). Server <strong>MUST</strong> respond back with either an aknowledgment message</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 16</span><span> }</span></span></code></pre> <p>Optionally the server can reply back reporting it's findings about calculated hashrate <strong>for the same worker</strong>.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 16</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span> :</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">4f0000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">w-123</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>In case of errors - for example when the client submits too frequently - with</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 16</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">error</span><span class="z-support">&quot;</span><span> :</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">code</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 220</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">message</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Enhance your calm. Too many requests</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="server-communicates-hashrate-to-client">Server communicates hashrate to client</h4> <p>Optionally the server can <strong>notify</strong> client about it's overall performance (according to schedule set on server) with a <code>mining.hashrate</code> notification composed like this</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">mining.hashrate</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">interval</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 60</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">hr</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">500000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">accepted</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-constant">3692</span><span>,</span><span class="z-constant">20</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">rejected</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 0</span><span>,</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Where <code>params</code> is an object which holds these members for values of the <strong>whole session</strong>:</p> <ul> <li><code>interval</code> (number) the width, in minutes, of the observation window. "<em>in the last x minutes we calculated ...</em>"</li> <li><code>hr</code> (hex) representation of the hashrate the pool has calculated for the miner</li> <li><code>accepted</code> is an array of two number elements : the first is the overall count of accepted shares and the second is the number of stale shares. The array must be interpreted as "total accepted of which x are stale"</li> <li><code>rejected</code> (number) the overall number of rejected shares</li> </ul> <p>The client will eventually take internal actions to reset/restart it's workers.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-11-09T00:00:00+00:00 2026-02-11T14:48:25+00:00 Cyril Lapintecyril.lapinte@mtpelerin.com Laurent Aaprolaurent.aapro@mtpelerin.com https://wg-eips.ritovision.com/1592/ <h2 id="simple-summary">Simple Summary</h2> <p>We propose a standard and an interface to define transfer rules, in the context of ERC20 tokens and possibly beyond.</p> <p>A rule can act based on sender, destination and amount, and is triggered (and rejects the transfer) according to any required business logic.</p> <p>To ease rule reusability and composition, we also propose an interface and base implementation for a rule engine.</p> <h2 id="abstract">Abstract</h2> <p>This standard proposal should answer the following challenges:</p> <ul> <li>Enable integration of rules with interacting platforms such as exchanges, decentralized wallets and DApps.</li> <li>Externale code and storage, improve altogether reusability, gas costs and contracts' memory footprint.</li> <li>Highlight contract behavior and its evolution, in order to ease user interaction with such contract.</li> </ul> <p>If these challenges are answered, this proposal will provide a unified basis for transfer rules and hopefully address the transfer restriction needs of other EIPs as well, e.g. <a href="https://wg-eips.ritovision.com/902/">EIP-902</a>, <a href="https://wg-eips.ritovision.com/1066/">EIP-1066</a> and <a href="https://wg-eips.ritovision.com/1175/">EIP-1175</a>.</p> <p>This document proposes specifications for a standard of <strong>transfer rules</strong> and interfaces to both the rules and the rule engine, which was made to be inherited by a token, but may have a much broader scope in the authors' opinion.</p> <p>The last section of this document illustrates the proposal with a rule template and links to rule implementations.</p> <h2 id="motivation">Motivation</h2> <p>ERC20 was designed as a standard interface allowing any token on Ethereum to be handled by other applications: from wallets to decentralized exchanges. This has been extremely powerful, but future developments in the industry of tokenization are bringing new challenges. For example it is already hard to know exactly why an ERC20 transfer failed, and it will become even harder when many tokens add their own transfer rules to the mix; we propose that it should be trivial to determine before a tx is sent, whether the transfer should turn out valid or invalid, and why (unless conditions change in the meantime obviously). On the other hand, if the rules were changed, it should also be easily detected, so that the interacting party knows it must adjust its expectations or model.</p> <h2 id="specification">Specification</h2> <p>We define below an interface for a rule. Rules are meant to be as simple as possible, to limit gas expenditure, since that logic will be executed on every transfer. Another reason for keeping rules simple and short, and strive for atomicity, is to facilitate both composition and interpretation of rejected transfers. By knowing which rule was triggered, we obtain a clear picture of the reason for rejection.</p> <p>The engine we propose executes all the rules defined by its owner, on every transfer and it is easy to add and remove rules individually, although we have chosen to use quite a raw rule update method, to save on deployment costs, which are often tight when it comes to token smart contracts.</p> <p>Rules are deployed on the blockchain as individual smart contracts, and called upon by the rule engine they were attached to. But any third party, for example an exchange preparing a cashout for a customer, can very cheaply query the rule engine of the token, or a single rule directly, to verify the validity of a transfer before execution, so as to never get a rejected transaction.</p> <h2 id="rule-interface">Rule interface</h2> <p><code>IRule</code> interface should provide a way to validate if an address or a transfer is valid.</p> <p>If one of these two methods is not applicable, it can simply be made to return true systematically. If any parameter of <code>isTransferValid</code> is not needed, its name should be commented out with <code>/* */</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">pragma</span><span class="z-variable z-other"> solidity</span><span class="z-keyword"> ^</span><span class="z-constant">0</span><span class="z-constant">.</span><span class="z-constant">4</span><span>.</span><span class="z-constant">25</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IRule</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isAddressValid</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _address</span><span>)</span><span class="z-entity z-name"> external</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isTransferValid</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _from</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _to</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _amount</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> external</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="withrules-interface">WithRules interface</h2> <p><code>WithRules</code> interface describes the integration of rules to a rule engine. Developers may choose to not implement this interface if their code will only deal with one rule, or if it is not desirable to update the rules.</p> <p>The rules ordering must be thought through carefully. Rules which are cheaper to validate or have a higher chance to break should be put first to reduce global gas expenditure, then business logic should guide the ordering of rules. That is why rules for a given context should be defined as a whole and not individually.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">pragma</span><span class="z-variable z-other"> solidity</span><span class="z-keyword"> ^</span><span class="z-constant">0</span><span class="z-constant">.</span><span class="z-constant">4</span><span>.</span><span class="z-constant">25</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">import</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">./IRule.sol</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IWithRules</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ruleLength</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> rule</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _ruleId</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">IRule</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateAddress</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _address</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateTransfer</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _from</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _to</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _amount</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> public</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> defineRules</span><span>(</span><span class="z-variable">IRule</span><span>[</span><span>]</span><span class="z-variable"> _rules</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> RulesDefined</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> count</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="withrules-implementation">WithRules implementation</h2> <p>We also propose a simple implementation of the rule engine, available <a rel="external" href="https://github.com/MtPelerin/MtPelerin-protocol/blob/master/contracts/rule/WithRules.sol">here</a>. It has been kept minimal both to save on gas costs on each transfer, and to reduce the deployment cost overhead for the derived smart contract.</p> <p>On top of implementing the interface above, this engine also defines two modifiers (<code>whenAddressRulesAreValid</code>and <code>whenTransferRulesAreValid</code>), which can be used throughout the token contract to restrict <code>transfer()</code>, <code>transferFrom</code> and any other function that needs to respect either a simple whitelist or complex transfer rules.</p> <h2 id="integration">Integration</h2> <p>To use rules within a token is as easy as having the token inherit from WithRules, then writing rules according to the IRule interface and deploying each rule individually. The token owner can then use <code>defineRules()</code> to attach all rules in the chosen order, within a single transaction.</p> <p>Below is a template for a rule.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">import</span><span class="z-string"> &quot;../interface/IRule.sol&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> TemplateRule</span><span class="z-storage"> is</span><span class="z-entity z-name"> IRule</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> state vars for business logic</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-comment">/*</span><span class="z-comment"> arguments for init </span><span class="z-comment">*/</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> initializations</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isAddressValid</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> boolean isValid</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> business logic </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> isValid</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isTransferValid</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _amount</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> boolean isValid</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> business logic </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> isValid</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>*** Notes *** The MPS (Mt Pelerin's Share) token is the current live implementation of this standard. Other implementations may be written with different trade-offs: from gas savings to improved security.</p> <h4 id="example-of-rules-implementations">Example of rules implementations</h4> <ul> <li> <p><a rel="external" href="https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule/YesNoRule.sol">YesNo rule</a>: Trivial rule used to demonstrate both a rule and the rule engine.</p> </li> <li> <p><a rel="external" href="https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule/FreezeRule.sol">Freeze rule</a>: This rule allows to prevent any transfer of tokens to or from chosen addresses. A smart blacklist.</p> </li> <li> <p><a rel="external" href="https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule/LockRule.sol">Lock rule</a>: Define a global transfer policy preventing either sending or receiving tokens within a period of time. Exceptions may be granted to some addresses by the token admin. A smart whitelist.</p> </li> <li> <p><a rel="external" href="https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule/UserKycRule.sol">User Kyc Rule</a>: Rule example relying on an existing whitelist to assert transfer and addresses validity. It is a good example of a rule that completely externalizes it's tasks.</p> </li> </ul> <h4 id="example-implementations-are-available-at">Example implementations are available at</h4> <ul> <li><a rel="external" href="https://github.com/MtPelerin/MtPelerin-protocol/tree/master/contracts/rule">Mt Pelerin Bridge protocol rules implementation</a></li> <li><a rel="external" href="https://github.com/MtPelerin/MtPelerin-protocol/blob/master/contracts/token/component/TokenWithRules.sol">Mt Pelerin Token with rules</a></li> </ul> <h2 id="history">History</h2> <p>Historical links related to this standard:</p> <ul> <li>The first regulated tokenized share issued by Mt Pelerin (MPS token) is using an early version of this proposal: https://www.mtpelerin.com/blog/world-first-tokenized-shares The rule engine was updated several times, after the token issuance and during the tokensale, to match changing business and legal requirements, showcasing the solidity and flexibility of the rule engine.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>. External references outside this repository will have their own specific copyrights.</p> 2018-11-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 trustfarmtrustfarm.info@gmail.com trustfarmcpplover@trustfarm.net https://wg-eips.ritovision.com/1485/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP modifies ethash in order to break ASIC miners specialized for the current ethash mining algorithm.</p> <h2 id="abstract">Abstract</h2> <p>This EIP pursue "obsolete current ASIC miners" by modifying PoW algorithm in a very low risk manner and update to latest hash algorithm from deprecated FNV Hash algorithms.</p> <p>Following TEthashV1 algorithm suggests safe transition of PoW algorithms and secure the FNV Algorithm in MIX Parts.</p> <h2 id="motivation">Motivation</h2> <p>Provide original Ethash proof of work verification with minimal set of changes by updating FNV0 algorithm</p> <h2 id="specification">Specification</h2> <h4 id="1-reference-materials-on-ethash-fnv0">1. Reference materials on ETHASH FNV0</h4> <h4 id="where-fnv-applied-on-ethash">Where FNV Applied on ETHASH</h4> <ul> <li> <p>In <a rel="external" href="https://web.archive.org/web/20200505215203/https://github.com/ethereum/wiki/wiki/Ethash">ETHASH</a>, FNV Hash is used on</p> <ul> <li> <ol> <li>On data aggregation function, MIX parts.</li> </ol> </li> <li>Ethash Algorithm</li> </ul> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> Header + Nonce</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> Keccak </span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> **[MIX 0]** --&gt; **[DAG Page]**</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> Mixing &lt;--|</span></span> <span class="giallo-l"><span> ...</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> **[Mix 63]**</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> |-----&gt; Mix64 [Process] ---&gt; Mix Digest [32B]</span></span></code></pre> <ul> <li>FNV used in DAG Generation and Mixing for random access or DAG Page.</li> </ul> </li> </ul> <h4 id="2-current-applied-ethash-fnv-hash-implementation-is-deprecated-now">2. Current applied Ethash FNV hash implementation is deprecated now.</h4> <p><a rel="external" href="https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV-0_hash_(deprecated)">FNV-0_hash (deprecated)</a></p> <p>It is a simple way of hashing algorithm</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> hash = 0</span></span> <span class="giallo-l"><span> for each byte_of_data to be hashed</span></span> <span class="giallo-l"><span> hash = hash × FNV_prime</span></span> <span class="giallo-l"><span> hash = hash XOR octet_of_data</span></span> <span class="giallo-l"><span> return hash</span></span></code></pre> <p>When analysed FNV-0 , there's very weak <a rel="external" href="https://simple.wikipedia.org/wiki/Avalanche_effect">avalanche effect</a>, when hash input changes on 1~2bits. refer <a rel="external" href="https://github.com/tao-foundation/FNV-Analysis#how-to-test-and-analysis-reference-test-code">FNV-Analysis reference section</a></p> <p>We need to research and apply newer FNV hash or short message hash algorithm.</p> <h4 id="3-fnv1a-hash-algorithm-description">3. FNV1A hash algorithm description</h4> <p>Previous proposed algorithm based on FNV1 <a href="https://wg-eips.ritovision.com/1355/">EIP-1355</a></p> <p>There's an implementation that looks like "Missing Offset Bias" at <strong>FNV1A</strong>.</p> <p>Quotation of <a rel="external" href="https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function#FNV-1a_hash">original algorithm FNV1A</a></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>use hash offset</span></span> <span class="giallo-l"><span>FNV-1a hash</span></span> <span class="giallo-l"><span>The FNV-1a hash differs from the FNV-1 hash by only the order in which the multiply and XOR is performed:[8][10]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> hash = FNV_offset_basis</span></span> <span class="giallo-l"><span> for each byte_of_data to be hashed</span></span> <span class="giallo-l"><span> hash = hash XOR byte_of_data</span></span> <span class="giallo-l"><span> hash = hash × FNV_prime</span></span> <span class="giallo-l"><span> return hash</span></span></code></pre> <p>FNV_offset_basis and computation order change of xor and multiplication Makes one more xor and multiply computation, but more secure hash effects than FNV0. and make dispersion boundary condition (0, even number, ..) by using of Prime Number.</p> <h4 id="4-real-implementation-for-fnv1a">4. Real Implementation for FNV1A</h4> <p>Consider real computation resources, in TEthashV1 uses hash byte_of_data to 4bytes aligned data.</p> <p>In TETHashV1, Adapts fully follow the FNV1A implementation.</p> <ul> <li>TETHASHV1 FNV1A implementation</li> </ul> <p>Following are reference implementation of FNV1A adapted in TETHashV1.</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Reference Pseudo c/cpp implementation</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">define</span><span class="z-entity z-name"> FNV_PRIME</span><span class="z-keyword"> 0x</span><span class="z-constant">01000193</span><span class="z-keyword">U</span></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">define</span><span class="z-entity z-name"> FNV_OFFSET_BASIS</span><span class="z-keyword"> 0x</span><span class="z-constant">811c9dc5</span><span class="z-keyword">U</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">define</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span class="z-variable">x</span><span>,</span><span class="z-variable"> y</span><span>)</span><span> (</span><span>(</span><span>(</span><span>(</span><span>FNV_OFFSET_BASIS</span><span class="z-keyword">^</span><span>(</span><span>x</span><span>)</span><span>)</span><span class="z-keyword">*</span><span>FNV_PRIME</span><span>)</span><span class="z-keyword"> ^</span><span> (</span><span>y</span><span>)</span><span>)</span><span class="z-keyword"> *</span><span> FNV_PRIME</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">define</span><span class="z-entity z-name"> fnv1a_reduce</span><span>(</span><span class="z-variable">a</span><span>,</span><span class="z-variable">b</span><span>,</span><span class="z-variable">c</span><span>,</span><span class="z-variable">d</span><span>)</span><span> (</span><span class="z-entity z-name">fnv1a</span><span>(</span><span class="z-entity z-name">fnv1a</span><span>(</span><span class="z-entity z-name">fnv1a</span><span>(</span><span>a</span><span>,</span><span> b</span><span>)</span><span>,</span><span> c</span><span>)</span><span>,</span><span> d</span><span>)</span><span>)</span></span></code></pre> <p>Another Byte aligned implementation of FNV1A , call to FNV1c</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">define</span><span class="z-entity z-name"> FNV_PRIME</span><span class="z-keyword"> 0x</span><span class="z-constant">01000193</span><span class="z-keyword">U</span></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">define</span><span class="z-entity z-name"> FNV_OFFSET_BASIS</span><span class="z-keyword"> 0x</span><span class="z-constant">811c9dc5</span><span class="z-keyword">U</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">define</span><span class="z-entity z-name"> fnv1i</span><span>(</span><span class="z-variable">x</span><span>)</span><span> (</span><span> (</span><span>(</span><span> (</span><span>(</span><span> (</span><span>(</span><span class="z-constant"> \</span></span> <span class="giallo-l"><span> (</span><span> (</span><span>(</span><span>FNV_OFFSET_BASIS</span><span>)</span><span class="z-keyword">^</span><span>(</span><span> (</span><span>(</span><span>x</span><span>)</span><span class="z-keyword">&gt;&gt;</span><span class="z-constant">24</span><span>)</span><span class="z-keyword">&amp;</span><span class="z-keyword">0x</span><span class="z-constant">000000ff</span><span> )</span><span>)</span><span class="z-keyword"> *</span><span> FNV_PRIME</span><span>)</span><span class="z-constant"> \</span></span> <span class="giallo-l"><span class="z-keyword"> ^</span><span> (</span><span>(</span><span>(</span><span>x</span><span>)</span><span class="z-keyword">&gt;&gt;</span><span class="z-constant">16</span><span> )</span><span class="z-keyword">&amp;</span><span class="z-keyword">0x</span><span class="z-constant">000000ff</span><span>)</span><span>)</span><span class="z-keyword"> *</span><span> FNV_PRIME</span><span>)</span><span class="z-constant"> \</span></span> <span class="giallo-l"><span class="z-keyword"> ^</span><span> (</span><span>(</span><span>(</span><span>x</span><span>)</span><span class="z-keyword">&gt;&gt;</span><span class="z-constant">8</span><span> )</span><span class="z-keyword">&amp;</span><span class="z-keyword">0x</span><span class="z-constant">000000ff</span><span>)</span><span>)</span><span class="z-keyword"> *</span><span> FNV_PRIME</span><span>)</span><span class="z-constant"> \</span></span> <span class="giallo-l"><span class="z-keyword"> ^</span><span> (</span><span>(</span><span>(</span><span>x</span><span>)</span><span> )</span><span class="z-keyword">&amp;</span><span class="z-keyword">0x</span><span class="z-constant">000000ff</span><span>)</span><span>)</span><span class="z-keyword"> *</span><span> FNV_PRIME</span><span>)</span><span class="z-constant"> \</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">define</span><span class="z-entity z-name"> fnv1c</span><span>(</span><span class="z-variable">x</span><span>,</span><span class="z-variable"> y</span><span>)</span><span> (</span><span>(</span><span class="z-entity z-name">fnv1i</span><span>(</span><span>x</span><span>)</span><span class="z-keyword"> ^</span><span> (</span><span>y</span><span>)</span><span>)</span><span class="z-keyword"> *</span><span> FNV_PRIME</span><span>)</span></span></code></pre><h4 id="5-fnv-analysis">5. <a rel="external" href="https://github.com/tao-foundation/FNV-Analysis">FNV-Analysis</a></h4> <p>FNV Mix Algorithm Analysis for TEthashV1</p> <h4 id="how-to-test-and-analysis-reference-test-code">How to test and analysis reference test code.</h4> <p>You can compile it with simple in terminal. No additional library needs,</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">gcc</span><span class="z-constant"> -</span><span class="z-constant">o</span><span class="z-string"> fnvtest</span><span class="z-string"> fnvcltest.c</span></span></code></pre> <p>And You can execute it</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>fnvtest</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>F(00,00)::VEC(0, 0, ffffffff, 0):: FNV :00000000, DF=00000000(00) DS(00000000), FNV1 :00000000, DF=00000000(00) DS(00000000), FNV1a:117697cd, DF=117697cd(17) DS(117697cd), FNV1c:1210d00f, DF=127f8dbf(20) DS(11a1725f), F___RC=efe1b9c4, DF:efe1b9c4(19) , F1__RC=deb68dfe, DF:deb68dfe(22) , F1A_RC=99bad28b, DF:99bad28b(17) , F1C_RC=e29fa497, DF:e29fa497(18)</span></span> <span class="giallo-l"><span>F(00,01)::VEC(0, 1, ffffffff, 0):: FNV :00000001, DF=00000001(01) DS(00000001), FNV1 :01000193, DF=01000193(06) DS(01000193), FNV1a:1076963a, DF=010001f7(09) DS(01000193), FNV1c:1110ce7c, DF=03001e73(11) DS(01000193), F___RC=fefffe6d, DF:111e47a9(14) , F1__RC=d9fd8597, DF:074b0869(12) , F1A_RC=72c287e0, DF:eb78556b(19) , F1C_RC=6b6991ef, DF:89f63578(17)</span></span> <span class="giallo-l"><span>F(00,02)::VEC(0, 2, ffffffff, 0):: FNV :00000002, DF=00000003(02) DS(00000001), FNV1 :02000326, DF=030002b5(08) DS(01000193), FNV1a:0f7694a7, DF=1f00029d(11) DS(01000193), FNV1c:1410d335, DF=05001d49(09) DS(030004b9), F___RC=d8fd8404, DF:26027a69(13) , F1__RC=9b16d24c, DF:42eb57db(19) , F1A_RC=c17f0ecb, DF:b3bd892b(18) , F1C_RC=a5be8e78, DF:ced71f97(21)</span></span> <span class="giallo-l"><span>F(00,03)::VEC(0, 3, ffffffff, 0):: FNV :00000003, DF=00000001(01) DS(00000001), FNV1 :030004b9, DF=0100079f(10) DS(01000193), FNV1a:0e769314, DF=010007b3(09) DS(01000193), FNV1c:1310d1a2, DF=07000297(09) DS(01000193), F___RC=b2fb099b, DF:6a068d9f(16) , F1__RC=5c301f01, DF:c726cd4d(17) , F1A_RC=94cf402e, DF:55b04ee5(16) , F1C_RC=aea1a025, DF:0b1f2e5d(17)</span></span> <span class="giallo-l"><span>F(00,04)::VEC(0, 4, ffffffff, 0):: FNV :00000004, DF=00000007(03) DS(00000001), FNV1 :0400064c, DF=070002f5(10) DS(01000193), FNV1a:0d769181, DF=03000295(07) DS(01000193), FNV1c:0e10c9c3, DF=1d001861(09) DS(050007df), F___RC=8cf88f32, DF:3e0386a9(14) , F1__RC=1d496bb6, DF:417974b7(17) , F1A_RC=89401d59, DF:1d8f5d77(20) , F1C_RC=e4e96c7c, DF:4a48cc59(13)</span></span> <span class="giallo-l"><span>F(00,05)::VEC(0, 5, ffffffff, 0):: FNV :00000005, DF=00000001(01) DS(00000001), FNV1 :050007df, DF=01000193(06) DS(01000193), FNV1a:0c768fee, DF=01001e6f(11) DS(01000193), FNV1c:0d10c830, DF=030001f3(09) DS(01000193), F___RC=66f614c9, DF:ea0e9bfb(20) , F1__RC=de62b86b, DF:c32bd3dd(19) , F1A_RC=346e222c, DF:bd2e3f75(21) , F1C_RC=502e5f82, DF:b4c733fe(20)</span></span> <span class="giallo-l"><span>F(00,06)::VEC(0, 6, ffffffff, 0):: FNV :00000006, DF=00000003(02) DS(00000001), FNV1 :06000972, DF=03000ead(10) DS(01000193), FNV1a:0b768e5b, DF=070001b5(09) DS(01000193), FNV1c:1010cce9, DF=1d0004d9(10) DS(030004b9), F___RC=40f39a60, DF:26058ea9(13) , F1__RC=9f7c0520, DF:411ebd4b(16) , F1A_RC=b376a527, DF:8718870b(13) , F1C_RC=1241a9a4, DF:426ff626(17)</span></span> <span class="giallo-l"><span>F(00,07)::VEC(0, 7, ffffffff, 0):: FNV :00000007, DF=00000001(01) DS(00000001), FNV1 :07000b05, DF=01000277(08) DS(01000193), FNV1a:0a768cc8, DF=01000293(06) DS(01000193), FNV1c:0f10cb56, DF=1f0007bf(15) DS(01000193), F___RC=1af11ff7, DF:5a028597(13) , F1__RC=609551d5, DF:ffe954f5(22) , F1A_RC=14293bea, DF:a75f9ecd(21) , F1C_RC=49d34bba, DF:5b92e21e(16)</span></span> <span class="giallo-l"><span>F(00,08)::VEC(0, 8, ffffffff, 0):: FNV :00000008, DF=0000000f(04) DS(00000001), FNV1 :08000c98, DF=0f00079d(12) DS(01000193), FNV1a:09768b35, DF=030007fd(12) DS(01000193), FNV1c:1a10dca7, DF=150017f1(12) DS(0b001151), F___RC=f4eea58e, DF:ee1fba79(21) , F1__RC=21ae9e8a, DF:413bcf5f(19) , F1A_RC=eeebb7a5, DF:fac28c4f(17) , F1C_RC=7da04f47, DF:347304fd(16)</span></span> <span class="giallo-l"><span>F(00,09)::VEC(0, 9, ffffffff, 0):: FNV :00000009, DF=00000001(01) DS(00000001), FNV1 :09000e2b, DF=010002b3(07) DS(01000193), FNV1a:087689a2, DF=01000297(07) DS(01000193), FNV1c:1910db14, DF=030007b3(10) DS(01000193), F___RC=ceec2b25, DF:3a028eab(14) , F1__RC=e2c7eb3f, DF:c36975b5(18) , F1A_RC=54e1aef8, DF:ba0a195d(15) , F1C_RC=d425e1af, DF:a985aee8(16)</span></span> <span class="giallo-l"><span>F(00,0a)::VEC(0, a, ffffffff, 0):: FNV :0000000a, DF=00000003(02) DS(00000001), FNV1 :0a000fbe, DF=03000195(07) DS(01000193), FNV1a:0776880f, DF=0f0001ad(10) DS(01000193), FNV1c:1c10dfcd, DF=050004d9(08) DS(030004b9), F___RC=a8e9b0bc, DF:66059b99(15) , F1__RC=a3e137f4, DF:4126dccb(15) , F1A_RC=213fcd63, DF:75de639b(20) , F1C_RC=7e1d2751, DF:aa38c6fe(18)</span></span> <span class="giallo-l"><span>F(00,0b)::VEC(0, b, ffffffff, 0):: FNV :0000000b, DF=00000001(01) DS(00000001), FNV1 :0b001151, DF=01001eef(12) DS(01000193), FNV1a:0676867c, DF=01000e73(09) DS(01000193), FNV1c:1b10de3a, DF=070001f7(11) DS(01000193), F___RC=82e73653, DF:2a0e86ef(16) , F1__RC=64fa84a9, DF:c71bb35d(19) , F1A_RC=5598ce46, DF:74a70325(14) , F1C_RC=6400c630, DF:1a1de161(14)</span></span> <span class="giallo-l"><span>F(00,0c)::VEC(0, c, ffffffff, 0):: FNV :0000000c, DF=00000007(03) DS(00000001), FNV1 :0c0012e4, DF=070003b5(10) DS(01000193), FNV1a:057684e9, DF=03000295(07) DS(01000193), FNV1c:1610d65b, DF=0d000861(07) DS(050007df), F___RC=5ce4bbea, DF:de038db9(17) , F1__RC=2613d15e, DF:42e955f7(18) , F1A_RC=6a220ff1, DF:3fbac1b7(20) , F1C_RC=6e781da4, DF:0a78db94(15)</span></span> <span class="giallo-l"><span>F(00,0d)::VEC(0, d, ffffffff, 0):: FNV :0000000d, DF=00000001(01) DS(00000001), FNV1 :0d001477, DF=01000693(07) DS(01000193), FNV1a:04768356, DF=010007bf(11) DS(01000193), FNV1c:1510d4c8, DF=03000293(07) DS(01000193), F___RC=36e24181, DF:6a06fa6b(17) , F1__RC=e72d1e13, DF:c13ecf4d(18) , F1A_RC=168d4944, DF:7caf46b5(19) , F1C_RC=65bbcfa1, DF:0bc3d205(13)</span></span> <span class="giallo-l"><span>F(00,0e)::VEC(0, e, ffffffff, 0):: FNV :0000000e, DF=00000003(02) DS(00000001), FNV1 :0e00160a, DF=0300027d(09) DS(01000193), FNV1a:037681c3, DF=07000295(08) DS(01000193), FNV1c:1810d981, DF=0d000d49(09) DS(030004b9), F___RC=10dfc718, DF:263d8699(15) , F1__RC=a8466ac8, DF:4f6b74db(20) , F1A_RC=93e667bf, DF:856b2efb(19) , F1C_RC=76f80ee3, DF:1343c142(11)</span></span> <span class="giallo-l"><span>F(00,0f)::VEC(0, f, ffffffff, 0):: FNV :0000000f, DF=00000001(01) DS(00000001), FNV1 :0f00179d, DF=01000197(07) DS(01000193), FNV1a:02768030, DF=010001f3(08) DS(01000193), FNV1c:1710d7ee, DF=0f000e6f(13) DS(01000193), F___RC=eadd4caf, DF:fa028bb7(17) , F1__RC=695fb77d, DF:c119ddb5(17) , F1A_RC=0f485682, DF:9cae313d(17) , F1C_RC=3667e8dc, DF:409fe63f(18)</span></span> <span class="giallo-l"><span>F(00,10)::VEC(0, 10, ffffffff, 0):: FNV :00000010, DF=0000001f(05) DS(00000001), FNV1 :10001930, DF=1f000ead(13) DS(01000193), FNV1a:01767e9d, DF=0300fead(14) DS(01000193), FNV1c:0210b6df, DF=15006131(09) DS(1500210f), F___RC=c4dad246, DF:2e079ee9(17) , F1__RC=2a790432, DF:4326b34f(16) , F1A_RC=d10adebd, DF:de42883f(16) , F1C_RC=1ce48e12, DF:2a8366ce(15)</span></span></code></pre> <p><code>F(00,01)</code> : is input x,y</p> <p><code>VEC(0, 1, ffffffff, 0)</code> : is <code>fnv_reduce</code> input vector (a,b,c,d)</p> <p><code>FNV :00000001, DF=00000001(01) DS(00000001)</code> :</p> <ul> <li><code>FNV(00,01)</code> result is 00000001 ,</li> <li><code>DF</code> : is changed bitcounts, compared with previous outputs, in this case prev[00,00] current[00,01] input is 1bit changed, and output result 1bit changed.</li> <li><code>DS</code> : is distances of previous result and current result , ABS(prev_fnvresult,current_fnvresult).</li> </ul> <p>** Basically, <code>DF</code> is higher is best on hash algorithm.</p> <p><code>F___RC=fefffe6d, DF:111e47a9(14)</code> : <code>fnv_reduce = fnv(fnv(fnv(a,b),c),d) </code> result is fefffe6d , and Different Bits counts are <code>14</code> bits.</p> <h2 id="rationale">Rationale</h2> <p>In case of ethash algorithm, it can't prevent ASIC forever.</p> <p>And, current ethash algorithm's FNV function is deprecated.</p> <p>So, It needs to be upgraded and it will make current ethash based ASICs obsolete.</p> <p>And current TETHASHV1 FNV1A implementation is based on most of ethash , which is verified for a long time.</p> <p>Another propose of big differencing the Ethash algorithm need to crypto analysis for a long times and need to GPU code optimization times.</p> <p><strong>Verification and Optimization timeline Examples</strong></p> <p>original ethminer (2015) -&gt; claymore optimized miner (2016) [1year]</p> <p>genoil ethminer (2015) -&gt; ethereum-mining/ethminer (2017) [2year]</p> <h2 id="test-results">Test Results::</h2> <p>Tethash miner has 2~3% of hashrate degrade on GPU, due to more core computation time.</p> <h2 id="copyright">Copyright</h2> <p>This work is licensed under a <a rel="external" href="https://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.</p> 2018-10-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kaidong Wuwukd94@pku.edu.cn Chuqiao Rencr025@bucknell.edu Ruthia Herujiahe@gmail.com Yun Mamayun@pku.edu.cn Xuanzhe Liuliuxuanzhe@pku.edu.cn https://wg-eips.ritovision.com/1504/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface/guideline that makes a smart contract upgradable.</p> <h2 id="abstract">Abstract</h2> <p>Ethereum smart contracts have suffered a number of security issues in the past few years. The cost of fixing such a bug in smart contract is significant; for example, the consequences of The DAO attack in June 2016 caused tremendous financial loss and the hard fork of Ethereum blockchain.</p> <p>The following standard makes it possible to upgrade a standard API within smart contracts. This standard provides basic functionalities to upgrade the operations of the contract without data migration. To ensure the decentralization/community interests, it also contains a voting mechanism to control the upgrading process.</p> <h2 id="motivation">Motivation</h2> <p>Smart contract is immutable after deployment. If any security risk is identified or program bug is detected, developers always have to destruct the old contract, deploy a new one and potentially migrate the data (hard fork) to the new contract. In some cases, deploying a smart contract with bugs and potential security vulnerabilities can cause a significant amount of financial loss.</p> <p>We propose this upgradable contract to fix the current situation. With the upgradable contract, developers can deploy a new version of smart contract after previous deployment and retain the data at the same time.</p> <p>For example, after an ERC20-compliant token contract is deployed, the users exploit a vulnerability in the source code. Without the support of upgradable contract, developers have to fix this issue by deploy a new, secured contract otherwise the attackers would take advantage of the security hole, which may cause a tremendous financial loss. A challenge is how to migrate data from the old contract to a new one. With the upgradable contract below, this will become relatively easy as developers only have to upgrade the Handler contract to fix bugs while the Data contract will remain the same.</p> <h2 id="specification">Specification</h2> <p>The upgradable contract consists of three parts:</p> <ul> <li><strong>Handler contract</strong> (implements <strong>Handler interface</strong>) defines operations and provides services. This contract can be upgraded;</li> <li><strong>Data contract</strong> keeps the resources (data) and is controlled by the Handler contract;</li> <li><strong>Upgrader contract (optional)</strong> deals with the voting mechanism and upgrades the Handler contract. The voters are pre-defined by the contract owner.</li> </ul> <blockquote> <p>The following codes are exact copies of the <a rel="external" href="https://gist.github.com/swordghost/77c96a972106af6ec6ccea9c2d66e768">ERC-1504 Upgradable Smart Contract.</a></p> </blockquote> <h3 id="handler-contract-and-handler-interface">Handler contract and Handler interface</h3> <p>Functions of the Handler contract vary with requirements, so developers would better design interfaces for Handler contracts to limit them and make sure external applications are always supported.</p> <p>Below is the specification of Handler interface. In the Handler interface we define the following actions:</p> <ul> <li>Initialize the Data contract;</li> <li>Register the Upgrader contract address;</li> <li>Destruct the Handler contract after upgrading is done;</li> <li>Verify the current Handler is the working one → it should always return true.</li> </ul> <p>Developers have to define their business-related functions as well.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Handler interface.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Handler defines business related functions.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Use the interface to ensure that your external services are always supported.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Because of function live(), we design IHandler as an abstract contract rather than a true interface.</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> IHandler</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Initialize the data contarct.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _str</span><span class="z-comment"> value of exmStr of Data contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _int</span><span class="z-comment"> value of exmInt of Data contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _array</span><span class="z-comment"> value of exmArray of Data contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initialize</span><span> (</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _str</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _int</span><span>,</span><span class="z-support"> uint16</span><span> [</span><span>]</span><span class="z-variable z-parameter z-function"> _array</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Register Upgrader contract address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _upgraderAddr</span><span class="z-comment"> address of the Upgrader contract.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> registerUpgrader</span><span> (</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _upgraderAddr</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Upgrader contract calls this to check if it is registered.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> if</span><span class="z-comment"> the Upgrader contract is registered.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isUpgraderRegistered</span><span> (</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Handler has been upgraded so the original one has to self-destruct.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> done</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Check if the Handler contract is a working Handler contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> It is used to prove the contract is a Handler contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> always</span><span class="z-comment"> true.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> live</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Functions - define functions here </span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Events - add events here </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The process of deploying a Handler contract:</p> <ol> <li>Deploy Data contract;</li> <li>Deploy a Handler contract at a given address specified in the Data contract;</li> <li>Register the Handler contract address by calling setHandler() in the Data contract, or use an Upgrader contract to switch the Handler contract, which requires that Data contract is initialized;</li> <li>Initialize Data contract if haven’t done it already.</li> </ol> <h3 id="data-contract">Data Contract</h3> <p>Below is the specification of Data contract. There are three parts in the Data contract:</p> <ul> <li><strong>Administrator Data</strong>: owner’s address, Handler contract’s address and a boolean indicating whether the contract is initialized or not;</li> <li><strong>Upgrader Data</strong>: Upgrader contract’s address, upgrade proposal’s submission timestamp and proposal’s time period;</li> <li><strong>Resource Data</strong>: all other resources that the contract needs to keep and manage.</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Data Contract</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> DataContract</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Management data </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Owner and Handler contract</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> private</span><span> owner</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> private</span><span> handlerAddr</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Ready?</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-storage z-type"> private</span><span> valid</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Upgrader data </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> private</span><span> upgraderAddr</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> proposalBlockNumber</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> proposalPeriod</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Upgrading status of the Handler contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> UpgradingStatus</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ Can be upgraded</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Done</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ In upgrading</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> InProgress</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ Another proposal is in progress</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Blocked</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ Expired</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Expired</span><span>,</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">/ Original Handler contract error</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Error</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Data resources - define variables here </span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Modifiers </span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Check if msg.sender is the Handler contract. It is used for setters.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If fail, throw PermissionException.</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> onlyHandler</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// Check if msg.sender is not permitted to call getters. It is used for getters (if necessary)</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">If</span><span class="z-entity z-name"> fail</span><span>, </span><span class="z-entity z-name">throw</span><span class="z-entity z-name"> GetterPermissionException</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name"> modifier</span><span class="z-entity z-name"> allowedAddress</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">Check</span><span class="z-entity z-name"> if</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> working</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">It</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> used</span><span class="z-entity z-name"> for</span><span class="z-entity z-name"> all</span><span class="z-entity z-name"> functions</span><span class="z-entity z-name"> providing</span><span class="z-entity z-name"> services</span><span class="z-entity z-name"> after</span><span class="z-entity z-name"> initialization</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">If</span><span class="z-entity z-name"> fail</span><span>, </span><span class="z-entity z-name">throw</span><span class="z-entity z-name"> UninitializationException</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name"> modifier</span><span class="z-entity z-name"> ready</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /** </span><span class="z-entity z-name">Management</span><span class="z-entity z-name"> functions</span><span> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">Initializer</span><span>. </span><span class="z-entity z-name">Just</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> can</span><span class="z-entity z-name"> call</span><span class="z-entity z-name"> it</span><span>. </span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">param</span><span class="z-entity z-name"> _str</span><span class="z-entity z-name"> default</span><span class="z-entity z-name"> value</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> this</span><span>.</span><span class="z-entity z-name">exmStr</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">param</span><span class="z-entity z-name"> _int</span><span class="z-entity z-name"> default</span><span class="z-entity z-name"> value</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> this</span><span>.</span><span class="z-entity z-name">exmInt</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">param</span><span class="z-entity z-name"> _array</span><span class="z-entity z-name"> default</span><span class="z-entity z-name"> value</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> this</span><span>.</span><span class="z-entity z-name">exmArray</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> PermissionException</span><span class="z-entity z-name"> msg</span><span>.</span><span class="z-entity z-name">sender</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> not</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> ReInitializationException</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> has</span><span class="z-entity z-name"> been</span><span class="z-entity z-name"> initialized</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">return</span><span class="z-entity z-name"> if</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> initialization</span><span class="z-entity z-name"> succeeds</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> initialize</span><span> (</span><span class="z-entity z-name">string</span><span class="z-entity z-name"> _str</span><span>, </span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> _int</span><span>, </span><span class="z-entity z-name">uint16</span><span> [] </span><span class="z-entity z-name">_array</span><span>) </span><span class="z-storage z-type">external</span><span class="z-entity z-name"> onlyHandler</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-entity z-name">bool</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">Set</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> for</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> contract</span><span>. </span><span class="z-entity z-name">Owner</span><span class="z-entity z-name"> must</span><span class="z-entity z-name"> set</span><span class="z-entity z-name"> one</span><span class="z-entity z-name"> to</span><span class="z-entity z-name"> initialize</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> Data</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">Handler</span><span class="z-entity z-name"> can</span><span class="z-entity z-name"> be</span><span class="z-entity z-name"> set</span><span class="z-entity z-name"> by</span><span class="z-entity z-name"> owner</span><span class="z-entity z-name"> or</span><span class="z-entity z-name"> Upgrader</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">param</span><span class="z-entity z-name"> _handlerAddr</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> a</span><span class="z-entity z-name"> deployed</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">param</span><span class="z-entity z-name"> _originalHandlerAddr</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> original</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span>, </span><span class="z-entity z-name">only</span><span class="z-entity z-name"> used</span><span class="z-entity z-name"> when</span><span class="z-entity z-name"> an</span><span class="z-entity z-name"> Upgrader</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> want</span><span class="z-entity z-name"> to</span><span class="z-entity z-name"> set</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> PermissionException</span><span class="z-entity z-name"> msg</span><span>.</span><span class="z-entity z-name">sender</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> not</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> owner</span><span class="z-entity z-name"> nor</span><span class="z-entity z-name"> a</span><span class="z-entity z-name"> registered</span><span class="z-entity z-name"> Upgrader</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> UpgraderException</span><span class="z-entity z-name"> Upgrader</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> does</span><span class="z-entity z-name"> not</span><span class="z-entity z-name"> provide</span><span class="z-entity z-name"> a</span><span class="z-entity z-name"> right</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> original</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">return</span><span class="z-entity z-name"> if</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> successfully</span><span class="z-entity z-name"> set</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> setHandler</span><span> (</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> _handlerAddr</span><span>, </span><span class="z-entity z-name">address</span><span class="z-entity z-name"> _originalHandlerAddr</span><span>) </span><span class="z-storage z-type">external</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-entity z-name">bool</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /** </span><span class="z-entity z-name">Upgrader</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> functions</span><span> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">Register</span><span class="z-entity z-name"> an</span><span class="z-entity z-name"> Upgrader</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> in</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">If</span><span class="z-entity z-name"> a</span><span class="z-entity z-name"> proposal</span><span class="z-entity z-name"> has</span><span class="z-entity z-name"> not</span><span class="z-entity z-name"> been</span><span class="z-entity z-name"> accepted</span><span class="z-entity z-name"> until</span><span class="z-entity z-name"> proposalBlockNumber</span><span> + </span><span class="z-entity z-name">proposalPeriod</span><span>, </span><span class="z-entity z-name">it</span><span class="z-entity z-name"> can</span><span class="z-entity z-name"> be</span><span class="z-entity z-name"> replaced</span><span class="z-entity z-name"> by</span><span class="z-entity z-name"> a</span><span class="z-entity z-name"> new</span><span class="z-entity z-name"> one</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">param</span><span class="z-entity z-name"> _upgraderAddr</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> a</span><span class="z-entity z-name"> deployed</span><span class="z-entity z-name"> Upgrader</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> PermissionException</span><span class="z-entity z-name"> msg</span><span>.</span><span class="z-entity z-name">sender</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> not</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> owner</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> UpgraderConflictException</span><span class="z-entity z-name"> Another</span><span class="z-entity z-name"> Upgrader</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> working</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">return</span><span class="z-entity z-name"> if</span><span class="z-entity z-name"> Upgrader</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> successfully</span><span class="z-entity z-name"> registered</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> startUpgrading</span><span> (</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> _upgraderAddr</span><span>) </span><span class="z-storage z-type">public</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-entity z-name">bool</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">Getter</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> proposalPeriod</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> UninitializationException</span><span class="z-entity z-name"> uninitialized</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> GetterPermissionException</span><span class="z-entity z-name"> msg</span><span>.</span><span class="z-entity z-name">sender</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> not</span><span class="z-entity z-name"> permitted</span><span class="z-entity z-name"> to</span><span class="z-entity z-name"> call</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> getter</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">return</span><span class="z-entity z-name"> this</span><span>.</span><span class="z-entity z-name">proposalPeriod</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> getProposalPeriod</span><span> (</span><span>) </span><span class="z-storage z-type">public</span><span class="z-storage z-type"> view</span><span class="z-entity z-name"> isReady</span><span class="z-entity z-name"> allowedAddress</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-entity z-name">uint256</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">Setter</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> proposalPeriod</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">param</span><span class="z-entity z-name"> _proposalPeriod</span><span class="z-entity z-name"> new</span><span class="z-entity z-name"> value</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> this</span><span>.</span><span class="z-entity z-name">proposalPeriod</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> UninitializationException</span><span class="z-entity z-name"> uninitialized</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> PermissionException</span><span class="z-entity z-name"> msg</span><span>.</span><span class="z-entity z-name">sender</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> not</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> owner</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">return</span><span class="z-entity z-name"> if</span><span class="z-entity z-name"> this</span><span>.</span><span class="z-entity z-name">proposalPeriod</span><span class="z-entity z-name"> is</span><span class="z-entity z-name"> successfully</span><span class="z-entity z-name"> set</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> setProposalPeriod</span><span> (</span><span class="z-entity z-name">uint256</span><span class="z-entity z-name"> _proposalPeriod</span><span>) </span><span class="z-storage z-type">public</span><span class="z-entity z-name"> isReady</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-entity z-name">bool</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">Return</span><span class="z-entity z-name"> upgrading</span><span class="z-entity z-name"> status</span><span class="z-entity z-name"> for</span><span class="z-entity z-name"> Upgrader</span><span class="z-entity z-name"> contracts</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">param</span><span class="z-entity z-name"> _originalHandlerAddr</span><span class="z-entity z-name"> address</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> original</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">exception</span><span class="z-entity z-name"> UninitializationException</span><span class="z-entity z-name"> uninitialized</span><span class="z-entity z-name"> contract</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">return</span><span class="z-entity z-name"> Handler</span><span class="z-entity z-name"> contract</span><span>&#39;</span><span class="z-entity z-name">s</span><span class="z-entity z-name"> upgrading</span><span class="z-entity z-name"> status</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> canBeUpgraded</span><span> (</span><span class="z-entity z-name">address</span><span class="z-entity z-name"> _originalHandlerAddr</span><span>) </span><span class="z-storage z-type">external</span><span class="z-storage z-type"> view</span><span class="z-entity z-name"> isReady</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-entity z-name">UpgradingStatus</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /// </span><span class="z-entity z-name">Check</span><span class="z-entity z-name"> if</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> has</span><span class="z-entity z-name"> been</span><span class="z-entity z-name"> initialized</span><span>.</span></span> <span class="giallo-l"><span> /// @</span><span class="z-entity z-name">return</span><span class="z-entity z-name"> if</span><span class="z-entity z-name"> the</span><span class="z-entity z-name"> contract</span><span class="z-entity z-name"> has</span><span class="z-entity z-name"> been</span><span class="z-entity z-name"> initialized</span><span>.</span></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> live</span><span> (</span><span>) </span><span class="z-storage z-type">external</span><span class="z-storage z-type"> view</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-entity z-name">bool</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /** </span><span class="z-entity z-name">Getters</span><span class="z-entity z-name"> and</span><span class="z-entity z-name"> setters</span><span class="z-entity z-name"> of</span><span class="z-entity z-name"> data</span><span class="z-entity z-name"> resources</span><span>: </span><span class="z-entity z-name">define</span><span class="z-entity z-name"> functions</span><span class="z-entity z-name"> here</span><span> */</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="upgrader-contract-optional">Upgrader Contract (Optional)</h3> <p>Handler contract can be upgraded by calling setHandler() of Data contract. If the owner wants to collect ideas from users, an Upgrader contract will help him/her manage voting and upgrading.</p> <p>Below is the specification of Upgrader contract:</p> <ul> <li>The Upgrader contract has the ability to take votes from the registered voters. <ul> <li>The contract owner is able to add voters any time before the proposal expires;</li> <li>Voter can check the current status of the proposal (succeed or expired).</li> </ul> </li> <li>Developers are able to delete this Upgrader contract by calling done() any time after deployment.</li> </ul> <p>The Upgrader contract works as follows:</p> <ol> <li>Verify the Data contract, its corresponding Handler contract and the new Handler contract have all been deployed;</li> <li>Deploy an Upgrader contract using Data contract address, previous Handler contract address and new Handler contract address;</li> <li>Register upgrader address in the new Handler contract first, then the original handler and finally the Data contract;</li> <li>Call startProposal() to start the voting process;</li> <li>Call getResolution() before the expiration;</li> <li>Upgrading succeed or proposal is expired.</li> </ol> <p>Note:</p> <ul> <li>Function done() can be called at any time to let upgrader destruct itself.</li> <li>Function status() can be called at any time to show caller status of the upgrader.</li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Handler upgrader</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Upgrader</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Data contract</span></span> <span class="giallo-l"><span> DataContract </span><span class="z-storage z-type">public</span><span> data</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Original Handler contract</span></span> <span class="giallo-l"><span> IHandler </span><span class="z-storage z-type">public</span><span> originalHandler</span><span>;</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> New Handler contract</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> public</span><span> newHandlerAddr</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Marker </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> UpgraderStatus</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Preparing</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Voting</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Success</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Expired</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> End</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> UpgraderStatus </span><span class="z-storage z-type">public</span><span> status</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Check if the proposal is expired.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If so, contract would be marked as expired.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception PreparingUpgraderException proposal has not been started.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception ReupgradingException upgrading has been done.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception ExpirationException proposal is expired.</span></span> <span class="giallo-l"><span class="z-storage z-type"> modifier</span><span class="z-entity z-name"> notExpired</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>status </span><span class="z-keyword">!=</span><span> UpgraderStatus</span><span>.</span><span>Preparing</span><span>,</span><span class="z-string"> &quot;Invalid proposal!&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>status </span><span class="z-keyword">!=</span><span> UpgraderStatus</span><span>.</span><span>Success</span><span>,</span><span class="z-string"> &quot;Upgrading has been done!&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>status </span><span class="z-keyword">!=</span><span> UpgraderStatus</span><span>.</span><span>Expired</span><span>,</span><span class="z-string"> &quot;Proposal is expired!&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>data</span><span>.</span><span class="z-entity z-name">canBeUpgraded</span><span>(</span><span class="z-support">address</span><span>(</span><span>originalHandler</span><span>)</span><span>)</span><span class="z-keyword"> !=</span><span> DataContract</span><span>.</span><span>UpgradingStatus</span><span>.</span><span>InProgress</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> status </span><span class="z-keyword">=</span><span> UpgraderStatus</span><span>.</span><span>Expired</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-constant">false</span><span>,</span><span class="z-string"> &quot;Proposal is expired!&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-constant"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Start voting.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Upgrader must do upgrading check, namely checking if Data contract and 2 Handler contracts are ok.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception RestartingException proposal has been already started.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception PermissionException msg.sender is not the owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception UpgraderConflictException another upgrader is working.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception NoPreparationException original or new Handler contract is not prepared.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> startProposal</span><span> (</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Anyone can try to get resolution.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If voters get consensus, upgrade the Handler contract.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> If expired, self-destruct.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Otherwise, do nothing.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception PreparingUpgraderException proposal has not been started.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception ExpirationException proposal is expired.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> status</span><span class="z-comment"> of proposal.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getResolution</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span>(</span><span class="z-storage z-type">UpgraderStatus</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Destruct itself.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> exception PermissionException msg.sender is not the owner.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> done</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span><span class="z-comment"> Other voting mechanism related variables and functions </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="caveats">Caveats</h3> <p>Since the Upgrader contract in <a href="https://wg-eips.ritovision.com/1504/">ERC-1504</a> has a simple voting mechanism, it is prone to all the limitations that the voting contract is facing:</p> <ul> <li>The administrator can only be the owner of data and Handler contracts. Furthermore, only the administrator has the power to add voters and start a proposal.</li> <li>It requires voters to be constantly active, informative and attentive to make a upgrader succeed.</li> <li>The voting will only be valid in a given time period. If in a given time period the contract cannot collect enough “yes” to proceed, the proposal will be marked expired.</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="data-contract-and-handler-contract">Data Contract and Handler Contract</h3> <p>A smart contract is actually a kind of software, which provides some kind of services. From the perspective of software engineering, a service consists of <strong>resources</strong> that abstract the data and <strong>operations</strong> that abstract the process logic on the data. The requirement of upgrading is mostly on the logic part. Therefore, in order to make a smart contract upgradable, we divide it into two parts:</p> <ol> <li>Data contract keeps the resources;</li> <li>Handler contract contains operations.</li> </ol> <p>The Handler contract can be upgraded in the future while the Data contract is permanent. Handler contract can manipulate the variables in Data contract through the getter and setter functions provided by Data contract.</p> <h3 id="upgrader-contract-and-voting-mechanism">Upgrader Contract and Voting Mechanism</h3> <p>In order to prevent centralization and protect the interests of the community and stakeholders, we also design a voting mechanism in the Upgrader contract. Upgrader contract contains addresses of Data contract and two Handler contracts, and collects votes from pre-defined voters to upgrade the Handler contract when the pre-set condition is fulfilled.</p> <p>For simplicity, the upgradable contract comes with a very minimal version of the voting mechanism. If the contract owner wants to implement a more complex voting mechanism, he/she can modify the existing voting mechanism to incorporate upgradability. The expiration mechanism (see modifier notExpried in Upgrader contract and related functions in Data contract) and upgrading check (see function startProposal() in Upgrader contract) to the contract are mandatory.</p> <h3 id="gas-and-complexity-regarding-the-enumeration-extension">Gas and Complexity (regarding the enumeration extension)</h3> <p>Using an upgrader will cost some gas. If the Handler contract is upgraded by the owner, it just costs gas that a contract call will cost, which is usually significantly lower than creating and deploying a new contract.</p> <p>Although upgrading contract may take some efforts and gas, it is a much less painful than deprecating the insecure contract/creating a new contract or hard fork (e.g. DAO attack). Contract creation requires a significant amount of effort and gas. One of the advantages of upgradable contracts is that the contract owners don’t have to create new contracts; instead, they only need to upgrade parts of contract that cause issues, which is less expensive compared to data loss and blockchain inconsistency. In other words, upgradable contracts make Data contract more scalable and flexible.</p> <h3 id="community-consensus">Community Consensus</h3> <p>Thank you to those who helped on review and revise the proposal:</p> <ul> <li><a rel="external" href="https://github.com/lsankar4033">@lsankar4033</a> from MIT</li> <li>more</li> </ul> <p>The proposal is initiated and developed by the team Renaissance and the Research Group of Blockchain System @ Center for Operating System at Peking University.</p> <p>We have been very inclusive in this process and invite anyone with questions or contributions into our discussion. However, this standard is written only to support the identified use cases which are listed herein.</p> <h2 id="implementations">Implementations</h2> <ol> <li><a rel="external" href="https://www.renaissance.app">Renaissance</a> - a protocol that connect creators and fans financially</li> <li><a href="https://wg-eips.ritovision.com/1504/">ERC-1504</a> - a reference implementation</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-10-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Anurag Angaraanurag.angara@gmail.com Andy Chorlianandychorlian@gmail.com Shane Hamptonshanehampton1@gmail.com Noah Zinsmeisternoahwz@gmail.com https://wg-eips.ritovision.com/1484/ <h2 id="simple-summary">Simple Summary</h2> <p>A protocol for aggregating digital identity information that's broadly interoperable with existing, proposed, and hypothetical future digital identity standards.</p> <h2 id="abstract">Abstract</h2> <p>This EIP proposes an identity management and aggregation framework on the Ethereum blockchain. It allows entities to claim an <code>Identity</code> via a singular <code>Identity Registry</code> smart contract, associate it with Ethereum addresses in a variety of meaningful ways, and use it to interact with smart contracts. This enables arbitrarily complex identity-related functionality. Notably (among other features) ERC-1484 <code>Identities</code>: are self-sovereign, can natively support <a href="https://wg-eips.ritovision.com/725/">ERC-725</a> and <a href="https://wg-eips.ritovision.com/1056/">ERC-1056</a> identities, are <a rel="external" href="https://github.com/NoahZinsmeister/ERC-1484/blob/master/best-practices/DID-Method.md">DID compliant</a>, and can be fully powered by <a rel="external" href="https://github.com/NoahZinsmeister/ERC-1484/tree/master/contracts/examples/Providers/MetaTransactions">meta-transactions</a>.</p> <h2 id="motivation">Motivation</h2> <p>Emerging identity standards and related frameworks proposed by the Ethereum community (including ERCs/EIPs <a href="https://wg-eips.ritovision.com/725/">725</a>, <a rel="external" href="https://github.com/ethereum/EIPs/issues/735">735</a>, <a rel="external" href="https://github.com/ethereum/EIPs/issues/780">780</a>, <a href="https://wg-eips.ritovision.com/1056/">1056</a>, etc.) define and instrumentalize digital identity in a variety of ways. As existing approaches mature, new standards emerge, and isolated, non-standard approaches to identity develop, coordinating on identity will become increasingly burdensome for blockchain users and developers, and involve the unnecessary duplication of work.</p> <p>The proliferation of on-chain identity solutions can be traced back to the fact that each codifies a notion of identity and links it to specific aspects of Ethereum (claims protocols, per-identity smart contracts, signature verification schemes, etc.). This proposal eschews that approach, instead introducing a protocol layer in between the Ethereum network and individual identity applications. This solves identity management and interoperability challenges by enabling any identity-driven application to leverage an un-opinionated identity management protocol.</p> <h2 id="definitions">Definitions</h2> <ul> <li> <p><code>Identity Registry</code>: A single smart contract which is the hub for all <code>Identities</code>. The primary responsibility of the <code>Registry</code> is to define and enforce the rules of a global namespace for <code>Identities</code>, which are individually denominated by Ethereum Identification Numbers (EINs).</p> </li> <li> <p><code>Identity</code>: A data structure containing all the core information relevant to an identity, namely: a <code>Recovery Address</code>, an <code>Associated Addresses</code> set, a <code>Providers</code> set, and a <code>Resolvers</code> set. <code>Identities</code> are denominated by EINs (incrementing <code>uint</code> identifiers starting at 1), which are unique but otherwise uninformative. Each <code>Identity</code> is a Solidity struct:</p> </li> </ul> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">struct</span><span class="z-entity z-name"> Identity</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> recoveryAddress</span><span>;</span></span> <span class="giallo-l"><span> AddressSet</span><span>.</span><span>Set associatedAddresses</span><span>;</span></span> <span class="giallo-l"><span> AddressSet</span><span>.</span><span>Set providers</span><span>;</span></span> <span class="giallo-l"><span> AddressSet</span><span>.</span><span>Set resolvers</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <ul> <li> <p><code>Associated Address</code>: An Ethereum address publicly associated with an <code>Identity</code>. In order for an address to become an <code>Associated Address</code>, an <code>Identity</code> must either transact from or produce an appropriately signed message from the candidate address and an existing <code>Associated Address</code>, indicating intent to associate. An <code>Associated Address</code> can be removed from an <code>Identity</code> by transacting/producing a signature indicating intent to disassociate. A given address may only be an <code>Associated Address</code> for one <code>Identity</code> at any given time.</p> </li> <li> <p><code>Provider</code>: An Ethereum address (typically but not by definition a smart contract) authorized to act on behalf of <code>Identities</code> who have authorized them to do so. This includes but is not limited to managing the <code>Associated Address</code>, <code>Provider</code>, and <code>Resolver</code> sets for an <code>Identity</code>. <code>Providers</code> exist to facilitate user adoption by making it easier to manage <code>Identities</code>.</p> </li> <li> <p><code>Resolver</code>: A smart contract containing arbitrary information pertaining to <code>Identities</code>. A resolver may implement an identity standard, such as ERC-725, or may consist of a smart contract leveraging or declaring identifying information about <code>Identities</code>. These could be simple attestation structures or more sophisticated financial dApps, social media dApps, etc. Each <code>Resolver</code> added to an <code>Identity</code> makes the <code>Identity</code> more informative.</p> </li> <li> <p><code>Recovery Address</code>: An Ethereum address (either an account or smart contract) that can be used to recover lost <code>Identities</code> as outlined in the <a href="https://wg-eips.ritovision.com/1484/#recovery">Recovery</a> section.</p> </li> <li> <p><code>Destruction</code>: In the event of irrecoverable loss of control of an <code>Identity</code>, <code>Destruction</code> is a contingency measure to permanently disable the <code>Identity</code>. It removes all <code>Associated Addresses</code>, <code>Providers</code>, and optionally <code>Resolvers</code> while preserving the <code>Identity</code>. Evidence of the existence of the <code>Identity</code> persists, while control over the <code>Identity</code> is nullified.</p> </li> </ul> <h2 id="specification">Specification</h2> <p>A digital identity in this proposal can be viewed as an omnibus account, containing more information about an identity than any individual identity application could. This omnibus identity is resolvable to an unlimited number of sub-identities called <code>Resolvers</code>. This allows an atomic entity, the <code>Identity</code>, to be resolvable to abstract data structures, the <code>Resolvers</code>. <code>Resolvers</code> recognize <code>Identities</code> by any of their <code>Associated Addresses</code>, or by their <code>EIN</code>.</p> <p>The protocol revolves around claiming an <code>Identity</code> and managing <code>Associated Addresses</code>, <code>Providers</code> and <code>Resolvers</code>. Identities can delegate much or all of this responsibility to one or more <code>Providers</code>, or perform it directly from an <code>Associated Address</code>. <code>Associated Addresses</code>/<code>Providers</code> may add and remove <code>Resolvers</code> and <code>Providers</code> indiscriminately. <code>Associated Addresses</code> may only be added or removed with the appropriate permission.</p> <h3 id="identity-registry">Identity Registry</h3> <p>The <code>Identity Registry</code> contains functionality to create new <code>Identities</code> and for existing <code>Identities</code> to manage their <code>Associated Addresses</code>, <code>Providers</code>, and <code>Resolvers</code>. It is important to note that this registry fundamentally requires transactions for every aspect of building out an <code>Identity</code>. However, recognizing the importance of accessibility to dApps and identity applications, we empower <code>Providers</code> to build out <code>Identities</code> on the behalf of users, without requiring users to pay gas costs. An example of this pattern, often referred to as a meta transactions, can be <a rel="external" href="https://github.com/NoahZinsmeister/ERC-1484/tree/master/contracts/examples/Providers/MetaTransactions">seen in the reference implementation</a>.</p> <p>Due to the fact that multiple addresses can be associated with a given identity (though not the reverse), <code>Identities</code> are denominated by <code>EIN</code>. This <code>uint</code> identifier can be encoded in QR format or mapped to more user-friendly formats, such as a <code>string</code>, in registries at the <code>Provider</code> or <code>Resolver</code> level.</p> <h3 id="address-management">Address Management</h3> <p>The address management function consists of trustlessly connecting multiple user-owned <code>Associated Addresses</code> to an <code>Identity</code>. It does not give special status to any particular <code>Associated Address</code>, rather leaving this (optional) specification to identity applications built on top of the protocol - for instance, <code>management</code>, <code>action</code>, <code>claim</code> and <code>encryption</code> keys denominated in the ERC-725 standard, or <code>identifiers</code> and <code>delegates</code> as denominated in ERC-1056. This allows a user to access common identity data from multiple wallets while still:</p> <ul> <li>retaining the ability to interact with contracts outside of their identity</li> <li>taking advantage of address-specific permissions established at the application layer of a user's identity.</li> </ul> <p>Trustlessness in the address management function is achieved through a robust permissioning scheme. To add an <code>Associated Address</code> to an <code>Identity</code>, implicit permission from a transaction sender or explicit permission from a signature is required from 1) an address already within the registry and 2) an address to be claimed. Importantly, the transaction need not come from any particular address, as long as permission is established, which allows not only users but third parties (companies, governments, etc.) to bear the overhead of managing identities. To prevent a compromised <code>Associated Address</code> from unilaterally removing other <code>Associated Addresses</code>, it's only possible to remove an <code>Associated Address</code> by transacting or producing a signature from it.</p> <p>All signatures required in ERC-1484 are designed per the <a href="https://wg-eips.ritovision.com/191/">ERC-191</a> v0 specification. To avoid replay attacks, all signatures must include a timestamp within a rolling lagged window of the current <code>block.timestamp</code>. For more information, see this <a rel="external" href="https://github.com/NoahZinsmeister/ERC-1484/blob/master/best-practices/VerifyingSignatures.md">best practices document</a> in the reference implementation.</p> <h3 id="provider-management">Provider Management</h3> <p>While the protocol allows users to directly call identity management functions, it also aims to be more robust and future-proof by allowing <code>Providers</code>, typically smart contracts, to perform identity management functions on a user's behalf. A <code>Provider</code> set by an <code>Identity</code> can perform address management and resolver management functions by passing a user's <code>EIN</code> in function calls.</p> <h3 id="resolver-management">Resolver Management</h3> <p>A <code>Resolver</code> is any smart contract that encodes information which resolves to an <code>Identity</code>. We remain agnostic about the specific information that can be encoded in a resolver and the functionality that this enables. The existence of <code>Resolvers</code> is primarily what makes this ERC an identity <em>protocol</em> rather than an identity <em>application</em>. <code>Resolvers</code> resolve abstract data in smart contracts to an atomic entity, the <code>Identity</code>.</p> <h3 id="recovery">Recovery</h3> <p>If users lose control over an <code>Associated Address</code>, the <code>Recovery Address</code> provides a fallback mechanism. Upon <code>Identity</code> creation, a <code>Recovery Address</code> is passed as a parameter by the creator. Recovery functionality is triggered in three scenarios:</p> <p><strong>1. Changing Recovery Address</strong>: If a recovery key is lost, an <code>Associated Address</code>/<code>Provider</code> can <a href="https://wg-eips.ritovision.com/1484/#triggerrecoveryaddresschange">triggerRecoveryAddressChange</a>/<a href="https://wg-eips.ritovision.com/1484/#triggerrecoveryaddresschangefor">triggerRecoveryAddressChangeFor</a>. To prevent malicious behavior from someone who has gained control of an <code>Associated Address</code> or <code>Provider</code> and is changing the <code>Recovery Address</code> to one under their control, this action triggers a 14 day challenge period during which the old <code>Recovery Address</code> may reject the change by <a href="https://wg-eips.ritovision.com/1484/#triggerrecovery">triggering recovery</a>. If the <code>Recovery Address</code> does not reject the change within 14 days, the <code>Recovery Address</code> is changed.</p> <p><strong>2. Recovery</strong>: Recovery occurs when a user recognizes that an <code>Associated Address</code> or the <code>Recovery Address</code> belonging to the user is lost or stolen. In this instance the <code>Recovery Address</code> must call <a href="https://wg-eips.ritovision.com/1484/#triggerrecovery">triggerRecovery</a>. This removes all <code>Associated Addresses</code> and <code>Providers</code> from the corresponding <code>Identity</code> and replaces them with an address passed in the function call. The <code>Identity</code> and associated <code>Resolvers</code> maintain integrity. The user is now responsible for adding the appropriate un-compromised addresses back to their <code>Identity</code>.</p> <p><em>Importantly, the <code>Recovery Address</code> can be a user-controlled wallet or another address, such as a multisig wallet or smart contract. This allows for arbitrarily sophisticated recovery logic! This includes the potential for recovery to be fully compliant with standards such as <a rel="external" href="https://decentralized.id/">DID</a>.</em></p> <p><strong>3. Destruction</strong> The Recovery scheme offers considerable power to a <code>Recovery Address</code>; accordingly, <code>Destruction</code> is a nuclear option to combat malicious control over an <code>Identity</code> when a <code>Recovery Address</code> is compromised. If a malicious actor compromises a user's <code>Recovery Address</code> and triggers recovery, any address removed in the <code>Recovery</code> process can call <a href="https://wg-eips.ritovision.com/1484/#triggerdestruction">triggerDestruction</a> within 14 days to permanently disable the <code>Identity</code>. The user would then need to create a new <code>Identity</code>, and would be responsible for engaging in recovery schemes for any identity applications built in the <code>Resolver</code> or <code>Provider</code> layers.</p> <h4 id="alternative-recovery-considerations">Alternative Recovery Considerations</h4> <p>We considered many possible alternatives when devising the Recovery process outlined above. We ultimately selected the scheme that was most un-opinionated, modular, and consistent with the philosophy behind the <code>Associated Address</code>, <code>Provider</code>, and <code>Resolver</code> components. Still, we feel that it is important to highlight some of the other recovery options we considered, to provide a rationale as to how we settled on what we did.</p> <p><strong>High Level Concerns</strong> Fundamentally, a Recovery scheme needs to be resilient to a compromised address taking control of a user's <code>Identity</code>. A secondary concern is preventing a compromised address from maliciously destroying a user's identity due to off-chain utility, which is not an optimal scenario, but is strictly better than if they've gained control.</p> <p><strong>Alternative 1: Nuclear Option</strong> This approach would allow any <code>Associated Address</code> to destroy an <code>Identity</code> whenever another <code>Associated Address</code> is compromised. While this may seem severe, we strongly considered it because this ERC is an identity <em>protocol</em>, not an identity <em>application</em>. This means that though a user's compromised <code>Identity</code> is destroyed, they should still have recourse to whatever restoration mechanisms are available in each of their actual identities at the <code>Resolver</code> and/or <code>Provider</code> level. We ultimately dismissed this approach for two main reasons:</p> <ul> <li>It is not robust in cases where a user has only one <code>Associated Address</code></li> <li>It would increase the frequency of recovery requests to identity applications due to its unforgiving nature.</li> </ul> <p><strong>Alternative 2: Unilateral Address Removal via Providers</strong> This would allow <code>Associated Addresses</code>/<code>Providers</code> to remove <code>Associated Addresses</code> without a signature from said address. This implementation would allow <code>Providers</code> to include arbitrarily sophisticated schemes for removing a rogue address - for instance, multi-sig requirements, centralized off-chain verification, user controlled master addresses, deferral to a jurisdictional contract, and more. To prevent a compromised <code>Associated Address</code> from simply setting a malicious <code>Provider</code> to remove un-compromised addresses, it would have required a waiting period between when a <code>Provider</code> is set and when they would be able to remove an <code>Associated Address</code>. We dismissed this approach because we felt it placed too high of a burden on <code>Providers</code>. If a <code>Provider</code> offered a sophisticated range of functionality to a user, but post-deployment a threat was found in the Recovery logic of the provider, <code>Provider</code>-specific infrastructure would need to be rebuilt. We also considered including a flag that would allow a user to decide whether or not a <code>Provider</code> may remove <code>Associated Addresses</code> unilaterally. Ultimately, we concluded that only allowing removal of <code>Associated Addresses</code> via the <code>Recovery Address</code> enables equally sophisticated recovery logic while separating the functionality from <code>Providers</code>, leaving less room for users to relinquish control to potentially flawed implementations.</p> <h2 id="rationale">Rationale</h2> <p>We find that at a protocol layer, identities should not rely on specific claim or attestation structures, but should instead be a part of a trustless framework upon which arbitrarily sophisticated claim and attestation structures may be built.</p> <p>The main criticism of existing identity solutions is that they're overly restrictive. We aim to limit requirements, keep identities modular and future-proof, and remain un-opinionated regarding any functionality a particular identity component may have. This proposal gives users the option to interact on the blockchain using an robust <code>Identity</code> rather than just an address.</p> <h2 id="implementation">Implementation</h2> <p><strong>The reference implementation for ERC-1484 may be found in <a rel="external" href="https://github.com/NoahZinsmeister/ERC-1484">NoahZinsmeister/ERC-1484</a>.</strong></p> <h4 id="identityexists">identityExists</h4> <p>Returns a <code>bool</code> indicating whether or not an <code>Identity</code> denominated by the passed <code>EIN</code> exists.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> identityExists</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="hasidentity">hasIdentity</h4> <p>Returns a <code>bool</code> indicating whether or not the passed <code>_address</code> is associated with an <code>Identity</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> hasIdentity</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="getein">getEIN</h4> <p>Returns the <code>EIN</code> associated with the passed <code>_address</code>. Throws if the address is not associated with an <code>EIN</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getEIN</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span>;</span></span></code></pre><h4 id="isassociatedaddressfor">isAssociatedAddressFor</h4> <p>Returns a <code>bool</code> indicating whether or not the passed <code>_address</code> is associated with the passed <code>EIN</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isAssociatedAddressFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="isproviderfor">isProviderFor</h4> <p>Returns a <code>bool</code> indicating whether or not the passed <code>provider</code> has been set by the passed <code>EIN</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isProviderFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> provider</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="isresolverfor">isResolverFor</h4> <p>Returns a <code>bool</code> indicating whether or not the passed <code>resolver</code> has been set by the passed <code>EIN</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isResolverFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> resolver</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="getidentity">getIdentity</h4> <p>Returns the <code>recoveryAddress</code>, <code>associatedAddresses</code>, <code>providers</code> and <code>resolvers</code> of the passed <code>EIN</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getIdentity</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> recoveryAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> associatedAddresses</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> providers</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> resolvers</span></span> <span class="giallo-l"><span> )</span><span>;</span></span></code></pre><h4 id="createidentity">createIdentity</h4> <p>Creates an <code>Identity</code>, setting the <code>msg.sender</code> as the sole <code>Associated Address</code>. Returns the <code>EIN</code> of the new <code>Identity</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> createIdentity</span><span>(</span><span class="z-support">address</span><span class="z-variable"> recoveryAddress</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> providers</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> resolvers</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#identitycreated">IdentityCreated</a></p> <h4 id="createidentitydelegated">createIdentityDelegated</h4> <p>Performs the same logic as <code>createIdentity</code>, but can be called by any address. This function requires a signature from the <code>associatedAddress</code> to ensure their consent.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> createIdentityDelegated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> recoveryAddress</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> associatedAddress</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> providers</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> resolvers</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> timestamp</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#identitycreated">IdentityCreated</a></p> <h4 id="addassociatedaddress">addAssociatedAddress</h4> <p>Adds the <code>addressToAdd</code> to the <code>EIN</code> of the <code>approvingAddress</code>. The <code>msg.sender</code> must be either of the <code>approvingAddress</code> or the <code>addressToAdd</code>, and the signature must be from the other one.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addAssociatedAddress</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> approvingAddress</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> addressToAdd</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> timestamp</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#associatedaddressadded">AssociatedAddressAdded</a></p> <h4 id="addassociatedaddressdelegated">addAssociatedAddressDelegated</h4> <p>Adds the <code>addressToAdd</code> to the <code>EIN</code> of the <code>approvingAddress</code>. Requires signatures from both the <code>approvingAddress</code> and the <code>addressToAdd</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addAssociatedAddressDelegated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> approvingAddress</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> addressToAdd</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> timestamp</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#associatedaddressadded">AssociatedAddressAdded</a></p> <h4 id="removeassociatedaddress">removeAssociatedAddress</h4> <p>Removes the <code>msg.sender</code> as an <code>Associated Address</code> from its <code>EIN</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeAssociatedAddress</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#associatedaddressremoved">AssociatedAddressRemoved</a></p> <h4 id="removeassociatedaddressdelegated">removeAssociatedAddressDelegated</h4> <p>Removes the <code>addressToRemove</code> from its associated <code>EIN</code>. Requires a signature from the <code>addressToRemove</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeAssociatedAddressDelegated</span><span>(</span><span class="z-support">address</span><span class="z-variable"> addressToRemove</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> timestamp</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#associatedaddressremoved">AssociatedAddressRemoved</a></p> <h4 id="addproviders">addProviders</h4> <p>Adds an array of <code>Providers</code> to the <code>Identity</code> of the <code>msg.sender</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addProviders</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> providers</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#provideradded">ProviderAdded</a></p> <h4 id="addprovidersfor">addProvidersFor</h4> <p>Performs the same logic as <code>addProviders</code>, but must be called by a <code>Provider</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addProvidersFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> providers</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#provideradded">ProviderAdded</a></p> <h4 id="removeproviders">removeProviders</h4> <p>Removes an array of <code>Providers</code> from the <code>Identity</code> of the <code>msg.sender</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeProviders</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> providers</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#providerremoved">ProviderRemoved</a></p> <h4 id="removeprovidersfor">removeProvidersFor</h4> <p>Performs the same logic as <code>removeProviders</code>, but is called by a <code>Provider</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeProvidersFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> providers</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#providerremoved">ProviderRemoved</a></p> <h4 id="addresolvers">addResolvers</h4> <p>Adds an array of <code>Resolvers</code> to the <code>EIN</code> of the <code>msg.sender</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addResolvers</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> resolvers</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#resolveradded">ResolverAdded</a></p> <h4 id="addresolversfor">addResolversFor</h4> <p>Performs the same logic as <code>addResolvers</code>, but must be called by a <code>Provider</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addResolversFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> resolvers</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#resolveradded">ResolverAdded</a></p> <h4 id="removeresolvers">removeResolvers</h4> <p>Removes an array of <code>Resolvers</code> from the <code>EIN</code> of the <code>msg.sender</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeResolvers</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> resolvers</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#resolverremoved">ResolverRemoved</a></p> <h4 id="removeresolversfor">removeResolversFor</h4> <p>Performs the same logic as <code>removeResolvers</code>, but must be called by a <code>Provider</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeResolversFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> resolvers</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#resolverremoved">ResolverRemoved</a></p> <h4 id="triggerrecoveryaddresschange">triggerRecoveryAddressChange</h4> <p>Initiates a change in the current <code>recoveryAddress</code> for the <code>EIN</code> of the <code>msg.sender</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> triggerRecoveryAddressChange</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newRecoveryAddress</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#recoveryaddresschangetriggered">RecoveryAddressChangeTriggered</a></p> <h4 id="triggerrecoveryaddresschangefor">triggerRecoveryAddressChangeFor</h4> <p>Initiates a change in the current <code>recoveryAddress</code> for a given <code>EIN</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> triggerRecoveryAddressChangeFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newRecoveryAddress</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#recoveryaddresschangetriggered">RecoveryAddressChangeTriggered</a></p> <h4 id="triggerrecovery">triggerRecovery</h4> <p>Triggers <code>EIN</code> recovery from the current <code>recoveryAddress</code>, or the old <code>recoveryAddress</code> if changed within the last 2 weeks.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> triggerRecovery</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newAssociatedAddress</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> timestamp</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#recoverytriggered">RecoveryTriggered</a></p> <h4 id="triggerdestruction">triggerDestruction</h4> <p>Triggers destruction of an <code>EIN</code>. This renders the <code>Identity</code> permanently unusable.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> triggerDestruction</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> firstChunk</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> lastChunk</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> clearResolvers</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span><span>;</span></span></code></pre> <p>Triggers event: <a href="https://wg-eips.ritovision.com/1484/#identitydestroyed">IdentityDestroyed</a></p> <h3 id="events">Events</h3> <h4 id="identitycreated">IdentityCreated</h4> <p>MUST be triggered when an <code>Identity</code> is created.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> IdentityCreated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> recoveryAddress</span><span>, </span><span class="z-support">address</span><span class="z-variable"> associatedAddress</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> providers</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> resolvers</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="associatedaddressadded">AssociatedAddressAdded</h4> <p>MUST be triggered when an address is added to an <code>Identity</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> AssociatedAddressAdded</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> approvingAddress</span><span>, </span><span class="z-support">address</span><span class="z-variable"> addedAddress</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="associatedaddressremoved">AssociatedAddressRemoved</h4> <p>MUST be triggered when an address is removed from an <code>Identity</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> AssociatedAddressRemoved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> removedAddress</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span><span>)</span><span>;</span></span></code></pre><h4 id="provideradded">ProviderAdded</h4> <p>MUST be triggered when a provider is added to an <code>Identity</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ProviderAdded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> provider</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span><span>)</span><span>;</span></span></code></pre><h4 id="providerremoved">ProviderRemoved</h4> <p>MUST be triggered when a provider is removed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ProviderRemoved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> provider</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span><span>)</span><span>;</span></span></code></pre><h4 id="resolveradded">ResolverAdded</h4> <p>MUST be triggered when a resolver is added.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ResolverAdded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> resolvers</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span><span>)</span><span>;</span></span></code></pre><h4 id="resolverremoved">ResolverRemoved</h4> <p>MUST be triggered when a resolver is removed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ResolverRemoved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> resolvers</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span><span>)</span><span>;</span></span></code></pre><h4 id="recoveryaddresschangetriggered">RecoveryAddressChangeTriggered</h4> <p>MUST be triggered when a recovery address change is triggered.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> RecoveryAddressChangeTriggered</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> oldRecoveryAddress</span><span>, </span><span class="z-support">address</span><span class="z-variable"> newRecoveryAddress</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="recoverytriggered">RecoveryTriggered</h4> <p>MUST be triggered when recovery is triggered.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> RecoveryTriggered</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> oldAssociatedAddresses</span><span>, </span><span class="z-support">address</span><span class="z-variable"> newAssociatedAddress</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="identitydestroyed">IdentityDestroyed</h4> <p>MUST be triggered when an <code>Identity</code> is destroyed.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> IdentityDestroyed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> recoveryAddress</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> resolversReset</span><span>)</span><span>;</span></span></code></pre><h3 id="solidity-interface">Solidity Interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IdentityRegistryInterface</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isSigned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> messageHash</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Identity View Functions /////////////////////////////////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> identityExists</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hasIdentity</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getEIN</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isAssociatedAddressFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isProviderFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> provider</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isResolverFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> resolver</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getIdentity</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> recoveryAddress</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> associatedAddresses</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> providers</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span class="z-variable"> resolvers</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Identity Management Functions ///////////////////////////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createIdentity</span><span>(</span><span class="z-support">address</span><span class="z-variable"> recoveryAddress</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> providers</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> resolvers</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createIdentityDelegated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> recoveryAddress</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> associatedAddress</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> providers</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> resolvers</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> timestamp</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addAssociatedAddress</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> approvingAddress</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> addressToAdd</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> timestamp</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addAssociatedAddressDelegated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> approvingAddress</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> addressToAdd</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span>[</span><span class="z-variable">2</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> timestamp</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeAssociatedAddress</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeAssociatedAddressDelegated</span><span>(</span><span class="z-support">address</span><span class="z-variable"> addressToRemove</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> timestamp</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addProviders</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> providers</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addProvidersFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> providers</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeProviders</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> providers</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeProvidersFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> providers</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addResolvers</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> resolvers</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addResolversFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> resolvers</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeResolvers</span><span>(</span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> resolvers</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeResolversFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> resolvers</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Recovery Management Functions ///////////////////////////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> triggerRecoveryAddressChange</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newRecoveryAddress</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> triggerRecoveryAddressChangeFor</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newRecoveryAddress</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> triggerRecovery</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newAssociatedAddress</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> v</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> r</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> s</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> timestamp</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> triggerDestruction</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> ein</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> firstChunk</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> lastChunk</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> resetResolvers</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Events //////////////////////////////////////////////////////////////////////////////////////////////////////////</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityCreated</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> recoveryAddress</span><span>, </span><span class="z-support">address</span><span class="z-variable"> associatedAddress</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> providers</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> resolvers</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AssociatedAddressAdded</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> approvingAddress</span><span>, </span><span class="z-support">address</span><span class="z-variable"> addedAddress</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> AssociatedAddressRemoved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> removedAddress</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ProviderAdded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> provider</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ProviderRemoved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> provider</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> delegated</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ResolverAdded</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> resolvers</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ResolverRemoved</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> resolvers</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RecoveryAddressChangeTriggered</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> oldRecoveryAddress</span><span>, </span><span class="z-support">address</span><span class="z-variable"> newRecoveryAddress</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RecoveryTriggered</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span>[</span><span>]</span><span class="z-variable"> oldAssociatedAddresses</span><span>, </span><span class="z-support">address</span><span class="z-variable"> newAssociatedAddress</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> IdentityDestroyed</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> initiator</span><span>, </span><span class="z-support">uint</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> ein</span><span>, </span><span class="z-support">address</span><span class="z-variable"> recoveryAddress</span><span>, </span><span class="z-support">bool</span><span class="z-variable"> resolversReset</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>Identities</code> established under this standard consist of existing Ethereum addresses; accordingly, there are no backwards compatibility issues. Deployed, non-upgradeable smart contracts that wish to become <code>Resolvers</code> for <code>Identities</code> will need to write wrapper contracts that resolve addresses to <code>EIN</code>-denominated <code>Identities</code>.</p> <h2 id="additional-references">Additional References</h2> <ul> <li><a rel="external" href="https://github.com/NoahZinsmeister/ERC-1484">ERC-1484 Reference Implementation</a></li> <li><a href="https://wg-eips.ritovision.com/191/">ERC-191 Signatures</a></li> <li><a href="https://wg-eips.ritovision.com/725/">ERC-725 Identities</a></li> <li><a href="https://wg-eips.ritovision.com/1056/">ERC-1056 Identities</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-10-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Iamnot Chrishttps://github.com/cohabo https://wg-eips.ritovision.com/1491/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for Human Capital Accounting tokens.</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for HUCAP tokens within smart contracts. This standard provides basic functionality to discover, track and transfer the motivational hierarchy of human resources. While blockchain architecture has succeeded in the financialisation of integrity by way of transparency; correspondingly real world outcomes will be proportional to the degree of individualisation of capital by way of knowledge.</p> <h2 id="motivation">Motivation</h2> <p>The Ethereum protocol architecture has a deterministic world-view bounded to the random reality of the human domain that supplies the intentions and logic. The yellow paper formally defines the EVM as a state machine with only deterministic parameters and state transition operators. Oracle requests to another on-chain contract, and/or off-chain HTTP lookups still make for multiple deterministic transactions.</p> <p>A standard interface that allows the appraisal of individual capabilities concurrently with output and the overall knowledge-base will reduce market search costs and increase the autonomous insertion of mindful innovation into the blockchain ecosystem. We provide for simple smart contracts to define and track an arbitrarily large number of HUCAP assets. Additional applications are discussed below.</p> <p>The Belief-Desire-Intention model is a plan-theoretic framework for establishing means-end coherence in agent based modelling system. The blockchain's cryptographic security architecture reliably scales to a blockchain based PKI web-of-trust hierarchies. ERC-20 token standard allows any tokens on Ethereum to be re-used by other applications: from wallets to decentralized exchanges. ERC-721 token standard allows wallet/broker/auction applications to work with any NFT on Ethereum. ERC-1155 Crypto Item standard allows a smart contract interface where one can represent any number of ERC-20 and ERC-721 assets in a single contract.</p> <p>This standard is inspired by the belief–desire–intention (BDI) model of human practical reasoning developed by Michael Bratman as a way of explaining future-directed intention. A BDI agent is a particular type of bounded rational software agent, imbued with particular mental attitudes, viz: Beliefs, Desires and Intentions (BDI). The model identifies commitment as the distinguishing factor between desire and intention, and a noteworthy property that leads to (1) temporal persistence in plans and in the sense of explicit reference to time, (2) further plans being made on the basis of those to which it is already committed, (3) hierarchical nature of plans, since the overarching plan remains in effect while subsidiary plans are being executed.</p> <p>The BDI software model is an attempt to solve a problem of plans and planning choice and the execution thereof. The complement of which tenders a sufficient metric for indicating means-end coherence and ascribing cost baselines to such outcomes.</p> <h2 id="specification">Specification</h2> <h4 id="main-interface">Main Interface</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.25</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> experimental</span><span class="z-constant"> ABIEncoderV2</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-**** Human Capital Accounting Standard</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> See https://github.com/freeworkculture/kazini/issues/11</span></span> <span class="giallo-l"><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0xf23a6e61.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC_HUCAP</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Compute the index value of an Agents BDI in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Set the stance of an agent</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> updateIndex</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the active/inactive and states of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Set the stance of an agent</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> iam</span><span>(</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> iam_</span><span>,</span><span class="z-storage z-type"> IERC_HUCAP_TYPES</span><span>.</span><span class="z-support z-variable">IS</span><span class="z-variable"> state_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Fetch the bdi index value of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Set the stance of an agent</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> index</span><span>(</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint8</span><span class="z-variable"> index_</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Count of Public Keys in key ring of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Set the stance of an agent</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> ringLength</span><span>(</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> ringlength_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the PGP Public Key Id of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-comment"> &quot;&quot; Set the stance of an agent</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> keyId</span><span>(</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-storage z-type"> KEYID_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the merit data of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-comment"> &quot;&quot; Set the stance of an agent</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> merits</span><span>(</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> experience_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> reputation_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> talent_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span class="z-variable"> index_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> hash_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the accreditation of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-comment"> &quot;&quot; Set the stance of an agent</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> kbase</span><span>(</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">IERC_HUCAP_TYPES</span><span>.</span><span class="z-support z-variable">KBase</span><span class="z-variable"> kbase_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the desire of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _desire</span><span class="z-comment"> Pro-attitude</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> desire</span><span>(</span><span class="z-support">bytes1</span><span class="z-variable z-parameter z-function"> _desire</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the intention of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _intention</span><span class="z-comment"> Conduct-controlling pro-attitude</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> intention</span><span>(</span><span class="z-support">bool</span><span class="z-variable z-parameter z-function"> _intention</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Cycle the intention of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _intention</span><span class="z-comment"> Conduct-controlling pro-attitude</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> flipIntention</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the user data of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-comment"> &quot;&quot; Conduct-controlling pro-attitude</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDoer</span><span>(</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> fPrint</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> iam_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> email</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> fName</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> lName</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> age</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> data_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the belief data of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _kbase</span><span class="z-comment"> Source address</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getBelief</span><span>(</span><span class="z-storage z-type">IERC_HUCAP_TYPES</span><span>.</span><span class="z-support z-variable">KBase</span><span class="z-variable z-parameter z-function"> _kbase</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> country_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> cAuthority_</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> score_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the desire data of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _desire</span><span class="z-comment"> Pro-attitides</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getDesire</span><span>(</span><span class="z-support">bytes1</span><span class="z-variable z-parameter z-function"> _desire</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>,</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the intention of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _intention</span><span class="z-comment"> Conduct-controlling pro-attitude</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getIntention</span><span>(</span><span class="z-support">bool</span><span class="z-variable z-parameter z-function"> _intention</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">IERC_HUCAP_TYPES</span><span>.</span><span class="z-support z-variable">IS</span><span>,</span><span class="z-support">bytes32</span><span>,</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Sign the Public Key of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Address of key to sign, must belong to an Agent </span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> sign</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyOwner</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> signed</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Sign the Public Key of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-comment"> &quot;&quot; internal helper function to add key in keyring</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> sign</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyDoer</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> signed</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Revoke the Public Key of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Address of key to revoke, must belong to an Agent</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revoke</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyDoer</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> revoked</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Revoke the Public Key of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-comment"> &quot;&quot; internal helper function to remove key from keyring</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revoke</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyDoer</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> revoked</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the trust level for a Public Key of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _level</span><span class="z-comment"> Degree of trust</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> trust</span><span>(</span><span class="z-storage z-type">Trust</span><span class="z-variable z-parameter z-function"> _level</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Increment the number of keys in the keyring of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _keyd</span><span class="z-comment"> Target key</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> incSigns</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _keyd</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> ProxyKey</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Decrement the number of keys in the keyring of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _keyd</span><span class="z-comment"> Target key</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> decSigns</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _keyd</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> ProxyKey</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the knowledge credentials of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _kbase</span><span class="z-comment"> Level of accreditation</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _country</span><span class="z-comment"> Source country</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _cAuthority</span><span class="z-comment"> Accreditation authority</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _score</span><span class="z-comment"> Accreditation </span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _year</span><span class="z-comment"> Year of Accreditation</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setbdi</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> KBase</span><span class="z-variable z-parameter z-function"> _kbase</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _country</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _cAuthority</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _score</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _year</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> ProxyBDI</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> qualification_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the SNA metrics of an Agent in the ecosystem</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _refMSD</span><span class="z-comment"> Minimum shortest distance</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _refRank</span><span class="z-comment"> Rank of target key</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _refSigned</span><span class="z-comment"> No of keys signed I have signed</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _refSigs</span><span class="z-comment"> No. of keys that have signed my key</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _refTrust</span><span class="z-comment"> Degree of tructThrows on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setbdi</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _refMSD</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _refRank</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _refSigned</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _refSigs</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _refTrust</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> ProxyBDI</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> reputation_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the talents of an Agent in the ecosystem</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _talent</span><span class="z-comment"> Agent&#39;s talent</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setbdi</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _talent</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> ProxyBDI</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> talent_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the desires of an Agent in the ecosystem</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _desire</span><span class="z-comment"> Pro-attitude</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _goal</span><span class="z-comment"> A goal is an instatiated pro-attitude</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setbdi</span><span>(</span><span class="z-support">bytes1</span><span class="z-variable z-parameter z-function"> _desire</span><span>,</span><span class="z-storage z-type"> Desire</span><span class="z-variable z-parameter z-function"> _goal</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyDoer</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the intention of an Agent in the ecosystem</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _service</span><span class="z-comment"> Conducting-controlling pro-attitude</span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setbdi</span><span>(</span><span class="z-storage z-type">Intention</span><span class="z-variable z-parameter z-function"> _service</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyDoer</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the targeted intention of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _intention</span><span class="z-comment"> Conduct-controlling pro-attitude</span></span> <span class="giallo-l"><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _state</span><span class="z-comment"> Agent stance </span></span> <span class="giallo-l"><span class="z-storage z-type"> @dev</span><span class="z-comment"> For the purpose of </span></span> <span class="giallo-l"><span class="z-comment"> Throws on any error rather than return a false flag to minimize user errors</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> intention</span><span>(</span><span class="z-support">bool</span><span class="z-variable z-parameter z-function"> _intention</span><span>,</span><span class="z-storage z-type"> IERC_HUCAP_TYPES</span><span>.</span><span class="z-support z-variable">IS</span><span class="z-variable z-parameter z-function"> _state</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">IERC_HUCAP_TYPES</span><span>.</span><span class="z-support z-variable">IS</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> End of interface IERC_HUCAP </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span></code></pre><h4 id="user-defined-types-extension-interface">User Defined Types Extension Interface</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC_HUCAP_TYPES</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> Enums</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Weights 1, 2, 4, 8, 16, 32, 64, 128 256</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> KBase</span><span> {</span><span class="z-variable z-other z-enummember">PRIMARY</span><span>,</span><span class="z-variable z-other z-enummember">SECONDARY</span><span>,</span><span class="z-variable z-other z-enummember">TERTIARY</span><span>,</span><span class="z-variable z-other z-enummember">CERTIFICATION</span><span>,</span><span class="z-variable z-other z-enummember">DIPLOMA</span><span>,</span><span class="z-variable z-other z-enummember">LICENSE</span><span>,</span><span class="z-variable z-other z-enummember">BACHELOR</span><span>,</span><span class="z-variable z-other z-enummember">MASTER</span><span>,</span><span class="z-variable z-other z-enummember">DOCTORATE</span><span>}</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> IS</span><span> {</span><span class="z-variable z-other z-enummember"> CLOSED</span><span>,</span><span class="z-variable z-other z-enummember"> CREATOR</span><span>,</span><span class="z-variable z-other z-enummember"> CURATOR</span><span>,</span><span class="z-variable z-other z-enummember"> ACTIVE</span><span>,</span><span class="z-variable z-other z-enummember"> INACTIVE</span><span>,</span><span class="z-variable z-other z-enummember"> RESERVED</span><span>,</span><span class="z-variable z-other z-enummember"> PROVER</span><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> Structus </span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Clearance</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Zero</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Unknown</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Generic</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Poor</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Casual</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Partial</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Complete</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> Ultimate</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> End of interface IERC_HUCAP_TYPES </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h4 id="web-of-trust-extension-interface">Web-of-trust Extension Interface</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.25</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> experimental</span><span class="z-constant"> ABIEncoderV2</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC_HUCAP_KEYSIGNING_EXTENSION</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> _InterfaceId_ERC165_ </span><span class="z-keyword">=</span><span class="z-string"> &quot;CREATOR 0.0118 XOR OF ALL FUNCTIONS IN THE INTERFACE&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Complies to ERC165</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> KEY MASKING TABLE</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> bytes32 constant public MASK = 0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> bytes32 constant public KEYID = 0xffffffffffffffffffffffffffffffffff90EBAC34FC40EAC30FC9CB464A2E56; // EXAMPLE PGP PUBLIC KEY ID</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> bytes32 constant public KEY_CERTIFICATION = 0x01ffffffffffffff &lt;&lt; 192; // “C” Key Certification</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> bytes32 constant public SIGN_DATA = 0x02ffffffffffffff &lt;&lt; 192; // “S” Sign Data</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> bytes32 constant public ENCRYPT_COMMUNICATIONS = 0x04ffffffffffffff &lt;&lt; 192; // “E” Encrypt Communications</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Clearance constant public Trust = 0x03ff &lt;&lt; 192; // Trust: Unknown</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> BYTES32 Value with </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Public Key Id, masking</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Key Certification masking</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Split Key masking</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Generic masking</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Ordinary masking</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Trust.Unknown masking</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> bytes32 constant public DOER = 0x11ff10ff100f03ffff00ffffffffffffffff90EBAC34FC40EAC30FC9CB464A2E56;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> KEY_CERTIFICATION </span><span class="z-keyword">=</span><span class="z-constant"> 0x01ffffffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> “C” Key Certification</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> SIGN_DATA </span><span class="z-keyword">=</span><span class="z-constant"> 0x02ffffffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> “S” Sign Data</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> ENCRYPT_COMMUNICATIONS </span><span class="z-keyword">=</span><span class="z-constant"> 0x04ffffffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> “E” Encrypt Communications</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> ENCRYPT_STORAGE </span><span class="z-keyword">=</span><span class="z-constant"> 0x08ffffffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> “E” Encrypt Storage</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> SPLIT_KEY </span><span class="z-keyword">=</span><span class="z-constant"> 0x10ffffffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Split key</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> AUTHENTICATION </span><span class="z-keyword">=</span><span class="z-constant"> 0x20ffffffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> “A” Authentication</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> MULTI_SIGNATURE </span><span class="z-keyword">=</span><span class="z-constant"> 0x80ffffffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Held by more than one person</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> TRUST_AMOUNT </span><span class="z-keyword">=</span><span class="z-constant"> 0xffffffffffff00ff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> BINARY_DOCUMENT </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff00ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x00: Signature of a binary document.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> CANONICAL_DOCUMENT </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff01ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x01: Signature of a canonical text document.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> STANDALONE_SIGNATURE </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff02ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x02: Standalone signature.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> GENERIC </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff10ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x10: Generic certification of a User ID and Public-Key packet.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> PERSONA </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff11ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x11: Persona certification of a User ID and Public-Key packet.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> CASUAL </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff12ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x12: Casual certification of a User ID and Public-Key packet.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> POSITIVE </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff13ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x13: Positive certification of a User ID and Public-Key packet.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> SUBKEY_BINDING </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff18ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x18: Subkey Binding Signature</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> PRIMARY_KEY_BINDING </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff19ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x19: Primary Key Binding Signature</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> DIRECTLY_ON_KEY </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff1Fffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x1F: Signature directly on a key</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> KEY_REVOCATION </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff20ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x20: Key revocation signature</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> SUBKEY_REVOCATION </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff28ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x28: Subkey revocation signature</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> CERTIFICATION_REVOCATION </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff30ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x30: Certification revocation signature</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> TIMESTAMP </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff40ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x40: Timestamp signature.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> THIRD_PARTY_CONFIRMATION </span><span class="z-keyword">=</span><span class="z-constant"> 0xffff50ffffffffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 0x50: Third-Party Confirmation signature.</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> ORDINARY </span><span class="z-keyword">=</span><span class="z-constant"> 0xffffffff100fffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> INTRODUCER </span><span class="z-keyword">=</span><span class="z-constant"> 0xffffffff010fffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> constant</span><span class="z-storage z-type"> public</span><span> ISSUER </span><span class="z-keyword">=</span><span class="z-constant"> 0xffffffff001fffff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> EDGES MASKING TABLE</span></span> <span class="giallo-l"><span> Clearance </span><span class="z-storage z-type">internal</span><span> TRUST </span><span class="z-keyword">=</span><span class="z-entity z-name"> Clearance</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> Zero</span><span class="z-keyword">:</span><span class="z-constant"> 0x01ff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>,</span></span> <span class="giallo-l"><span> Unknown</span><span class="z-keyword">:</span><span class="z-constant"> 0x03ff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>,</span></span> <span class="giallo-l"><span> Generic</span><span class="z-keyword">:</span><span class="z-constant"> 0x07ff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>,</span></span> <span class="giallo-l"><span> Poor</span><span class="z-keyword">:</span><span class="z-constant"> 0xF0ff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>,</span></span> <span class="giallo-l"><span> Casual</span><span class="z-keyword">:</span><span class="z-constant"> 0xF1ff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>,</span></span> <span class="giallo-l"><span> Partial</span><span class="z-keyword">:</span><span class="z-constant"> 0xF3ff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>,</span></span> <span class="giallo-l"><span> Complete</span><span class="z-keyword">:</span><span class="z-constant"> 0xF7ff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span><span>,</span></span> <span class="giallo-l"><span> Ultimate</span><span class="z-keyword">:</span><span class="z-constant"> 0xFFff</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 192</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> /// </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Cycle through state transition of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> /// </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> toggle on/off a doer agent</span></span> <span class="giallo-l"><span class="z-comment"> // </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> flipTo</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyOwner</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">IS</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> /// </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Turn Agent in the ecosystem to on/off.</span></span> <span class="giallo-l"><span class="z-comment"> /// </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> toggle on/off a doer agent</span></span> <span class="giallo-l"><span class="z-comment"> // </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> toggle</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyOwner</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> /// </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Set the trust level of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> /// </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _level</span><span class="z-comment"> toggle on/off a doer agent</span></span> <span class="giallo-l"><span class="z-comment"> // </span><span class="z-storage z-type">@dev</span><span class="z-comment"> `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> trust</span><span>(</span><span class="z-storage z-type">Trust</span><span class="z-variable z-parameter z-function"> _level</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-storage z-type"> Trust</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> LogCall</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> origin</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> _data</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> End of interface IERC_HUCAP_KEYSIGNING_EXTENSION </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h4 id="human-capital-accounting-extension-interface">Human Capital Accounting Extension Interface</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.25</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> experimental</span><span class="z-constant"> ABIEncoderV2</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC_HUCAP_TRACKUSERS_EXTENSION</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Instantiate an Agent in the ecosystem with default data.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> initialise a doer agent</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> initAgent</span><span>(</span><span class="z-storage z-type">Doers</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyControlled</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the data by uuid of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _uuid</span><span class="z-comment"> Get the address of a unique uid</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAgent</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _uuid</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the data of all Talents in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Query if address belongs to an agent</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> iam</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the data of all Talents in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Query if address belongs to a doer</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isDoer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">IS</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the number of doers that can be spawned by a Creators.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The query condition of the contract</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the count data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAgent</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> keyid_</span><span>,</span><span class="z-storage z-type"> IS</span><span class="z-variable"> state_</span><span>,</span><span class="z-support"> bool</span><span class="z-variable"> active_</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> myDoers_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the data of all Talents in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _talent</span><span class="z-comment"> The talent whose frequency is being queried</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getTalents</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _talent</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> talentK_</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> talentI_</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> talentR_</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> talentF_</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Increment a kind of talent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> The</span><span class="z-comment"> talent whose frequency is being queried</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> incTalent</span><span>(</span><span>)</span><span class="z-storage z-type"> payable</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyDoer</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Decrement a kind of talent in the ecosystem..</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> The</span><span class="z-comment"> talent whose frequency is being queried</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> decTalent</span><span>(</span><span>)</span><span class="z-storage z-type"> payable</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> onlyDoer</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the Public-Key Id of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Set the Public-key Id of an agent</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setAgent</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _keyId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyControlled</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Transition the states of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Set the stance of an agent</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setAgent</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>,</span><span class="z-storage z-type"> IS</span><span class="z-variable z-parameter z-function"> _state</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyControlled</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">IS</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the active status of an Agent in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _address</span><span class="z-comment"> Toggle the true/false status of an agent</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setAgent</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _address</span><span>,</span><span class="z-support"> bool</span><span class="z-variable z-parameter z-function"> _active</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyControlled</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the data of all Intentions of Agents in the ecosystem.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _serviceId</span><span class="z-comment"> Track number of offers available</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> @dev `anybody` can retrieve the talent data in the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setAllPromises</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _serviceId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-entity z-name"> onlyControlled</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> End of interface IERC_HUCAP_TRACKUSERS_EXTENSION </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span></code></pre><h2 id="rationale">Rationale</h2> <p>[WIP]</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>[WIP]</p> <h2 id="test-cases">Test Cases</h2> <p>[WIP]</p> <h2 id="implementation">Implementation</h2> <p>[WIP]</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-10-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Christoph Mussenbrockhttps://github.com/christoph2806 https://wg-eips.ritovision.com/1523/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for insurance policies, based on ERC 721.</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for insurance policies within smart contracts. Insurance policies are financial assets which are unique in some aspects, as they are connected to a customer, a specific risk, or have other unique properties like premium, period, carrier, underwriter etc. Nevertheless, there are many potential applications where insurance policies can be traded, transferred or otherwise treated as an asset. The ERC 721 standard already provides the standard and technical means to handle policies as a specific class of non fungible tokens. insurance In this proposal, we define a minimum metadata structure with properties which are common to the greatest possible class of policies.</p> <h2 id="motivation">Motivation</h2> <p>For a decentralized insurance protocol, a standard for insurance policies is crucial for interoperability of the involved services and application. It allows policies to be bundled, securitized, traded in a uniform and flexible way by many independent actors like syndicates, brokers, and insurance companies.</p> <h2 id="specification">Specification</h2> <p>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> <p>An ERC-1523 compliant insurance policy is a non-fungible token which <strong>MUST adhere to the ERC-721 token standard</strong> and <strong>MUST implement theERC721Metadata and the ERC721Enumerable interface</strong>:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-1523 Insurance Policy Standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x5a04be32</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1523</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC721, ERC721Metadata, ERC721Enumerable </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The implementor MAY choose values for the <code>name</code> and <code>symbol</code>.</p> <p>The <strong>policy metadata extension</strong> is <strong>RECOMMENDED</strong> for ERC-1523 smart contracts. This allows your smart contract to be interrogated for policy metadata.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-1523 Insurance Policy Standard, optional policy metadata extension</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See ...</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x5a04be32</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1523PolicyMetadata</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC1523 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Metadata string for a given property.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Properties are identified via hash of their property path.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> e.g. the property &quot;name&quot; in the ERC721 Metadata JSON Schema has the path /properties/name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> and the property path hash is the keccak256() of this property path. </span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> this allows for efficient addressing of arbitrary properties, as the set of properties is potentially unlimited.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if `_propertyPathHash` is not a valid property path hash. </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> policyMetadata</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _tokenId</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _propertyPathHash</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _property</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>In analogy to the “ERC721 Metadata JSON Schema”, the tokenURI <strong>MUST</strong> point to a JSON file with the following properties:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Asset Metadata</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Identifies the asset to which this NFT represents</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Describes the asset to which this NFT represents</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-invalid z-illegal"> \</span><span class="z-invalid z-illegal">[</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal"> p</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">m</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">s</span><span class="z-invalid z-illegal"> a</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">c</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">r</span><span class="z-invalid z-illegal">d</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">g</span><span class="z-invalid z-illegal"> t</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal"> t</span><span class="z-invalid z-illegal">h</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal"> f</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">o</span><span class="z-invalid z-illegal">w</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">n</span><span class="z-invalid z-illegal">g</span><span class="z-invalid z-illegal"> t</span><span class="z-invalid z-illegal">a</span><span class="z-invalid z-illegal">b</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">\</span><span class="z-invalid z-illegal">]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="additional-parameters-for-the-metadata-json-schema">Additional parameters for the metadata JSON Schema</h3> <table><thead><tr><th>Parameter</th><th>Type</th><th>Mandatory</th><th>Description</th></tr></thead><tbody> <tr><td>carrier</td><td>string</td><td>yes</td><td>Describes the carrier which takes the primary risk</td></tr> <tr><td>risk</td><td>string</td><td>yes</td><td>Describes the risk</td></tr> <tr><td>status</td><td>string</td><td>yes</td><td>Describes the status of the policy, e.g. applied for, underwritten, expired</td></tr> <tr><td>parameters</td><td>string</td><td>no</td><td>Describes further parameters characterizing the risk</td></tr> <tr><td>terms</td><td>string</td><td>no</td><td>Describes legal terms &amp; conditions which apply for this policy</td></tr> <tr><td>premium</td><td>string</td><td>no</td><td>A string representation of the premium, <strong>MAY</strong> contain currency denominator</td></tr> <tr><td>sum_insured</td><td>string</td><td>no</td><td>A string representation of the sum insured, <strong>MAY</strong> contain currency denominator</td></tr> </tbody></table> <p>Parameters which are mandatory <strong>MUST</strong> be included in the metadata JSON. Other parameters <strong>MAY</strong> be included. However, the proposed optional parameters <strong>SHOULD</strong> be used for the intended purpose, so e.g. if the premium amount would be included in the metadata, the parameter name <strong>SHOULD</strong> be "premium". All parameters <strong>MAY</strong> be plain text or <strong>MAY</strong> also be URIs pointing to resources which contain the respective information, and which <strong>MAY</strong> be protected by an authentication mechanism.</p> <h2 id="rationale">Rationale</h2> <p>Insurance policies form an important class of financial assets, and it is natural to express those assets as a class of non-fungible tokens which adhere to the established ERC-721 standard. We propose a standard for the accompanying metadata structures which are needed to uniquely define an insurance policy. Standardization is key because we expect decentralized insurance to receive widespread adoption and it is crucial to establish a unified standard to enable composability and the creation of universal toolsets. We therefore propose a standardized naming scheme for the different parameters describing an insurance policy. We propose three mandatory parameters which need to be included in every NFT and further parameters which <strong>MAY</strong> be used, and for which we only standardize the naming conventions.</p> <h3 id="mandatory-parameters">Mandatory parameters</h3> <p>While policies can have a multitude of possible properties, it is common that policies are issued by some entity, which is basically the entity responsible for paying out claims. Second, an insurance policy is typically related to a specific risk. Some risks are unique, but there are cases where many policies share the same risk (e.g. all flight delay policies for the same flight). In general, the relation of policies to risks is a many-to-one relation with the special case of a one-to-one relation. Third, a policy has a lifecycle of different statuses. Therefore the NFT We believe that those four properties are necessary to describe a policy. For many applications, those properties may be even sufficient.</p> <h3 id="optional-parameters">Optional parameters</h3> <p>Most policies need more parameters to characterize the risk and other features, like premium, period etc. The naming conventions are listed in the above table. However, any implementation <strong>MAY</strong> chose to implement more properties.</p> <h3 id="on-chain-vs-off-chain-metadata">On-chain vs. off-chain metadata</h3> <p>For some applications it will be sufficient to store the metadata in an off-chain repository or database which can be addressed by the tokenURI resource locator. For more advanced applications, it can be desirable to have metadata available on-chain. Therefore, we require that the <code>tokenURI</code> <strong>MUST</strong> point to a JSON with the above structure, while the implementation of the <code>policyMetadata</code> function is <strong>OPTIONAL</strong>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h2 id="test-cases">Test Cases</h2> <h2 id="implementation">Implementation</h2> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-10-09T00:00:00+00:00 2026-02-11T14:49:27+00:00 Maurelianhttps://github.com/Maurelian https://wg-eips.ritovision.com/1482/ <h2 id="simple-summary">Simple Summary</h2> <p>Include an explicit definition of the acceptable timestamp drift in the protocol specification.</p> <h2 id="abstract">Abstract</h2> <p>On the basis that both Geth and Parity implement the same timestamp validation requirements, this should be written into the reference specification.</p> <h2 id="motivation">Motivation</h2> <p>There is a lack of clarity about how accurate timestamps in the block header must be. The yellow paper describes the timestamp as</p> <blockquote> <p>A scalar value equal to the reasonable output of Unix’s time() at this block’s inception</p> </blockquote> <p>This causes <a rel="external" href="https://ethereum.stackexchange.com/questions/5924/how-do-ethereum-mining-nodes-maintain-a-time-consistent-with-the-network/5926#5926">confusion</a> about the safe use of the <code>TIMESTAMP</code> opcode (solidity's <code>block.timestamp</code> or <code>now</code>) in smart contract development.</p> <p>Differing interpretations of 'reasonable' may create a risk of consenus failures.</p> <h2 id="specification">Specification</h2> <p>The yellow paper should define a timestamp as:</p> <blockquote> <p>A scalar value equal to the output of Unix’s time() at this block’s inception. For the purpose of block validation, it must be greater than the previous block's timestamp, and no more than 15 seconds greater than system time.</p> </blockquote> <h2 id="rationale">Rationale</h2> <p>Both <a rel="external" href="https://github.com/ethereum/go-ethereum/blob/4e474c74dc2ac1d26b339c32064d0bac98775e77/consensus/ethash/consensus.go#L45">Geth</a> and <a rel="external" href="https://github.com/paritytech/parity-ethereum/blob/73db5dda8c0109bb6bc1392624875078f973be14/ethcore/src/verification/verification.rs#L296-L307">Parity</a> reject blocks with timestamp more than 15 seconds in the future. This establishes a defacto standard, which should be made explicit in the reference specification.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>It may be necessary to relax this requirement for blocks which were mined early in the main chain's history, if they would be considered invalid.</p> <h2 id="test-cases">Test Cases</h2> <p>These would be important to have.</p> <h2 id="implementation">Implementation</h2> <p>_The implementations must be completed before any EIP is given status "Final", but it need not be completed before the EIP is accepted. While there is merit to the approach of reaching consensus on the specification and rationale before writing code, the principle of "rough consensus and running code" is still useful when it comes to resolving many discussions of API details. _</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-10-02T00:00:00+00:00 2026-02-11T14:49:28+00:00 Paul Bouchonmail@bitpshr.net Erik Markshttps://github.com/rekmarks https://wg-eips.ritovision.com/1474/ <h2 id="simple-summary">Simple Summary</h2> <p>This proposal defines a standard set of remote procedure call methods that an Ethereum node should implement.</p> <h2 id="abstract">Abstract</h2> <p>Nodes created by the current generation of Ethereum clients expose inconsistent and incompatible remote procedure call (RPC) methods because no formal Ethereum RPC specification exists. This proposal standardizes such a specification to provide developers with a predictable Ethereum RPC interface regardless of underlying node implementation.</p> <h2 id="specification">Specification</h2> <h3 id="concepts">Concepts</h3> <h4 id="rfc-2119">RFC-2119</h4> <p>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 <a rel="external" href="https://www.ietf.org/rfc/rfc2119.txt">RFC-2119</a>.</p> <h4 id="json-rpc">JSON-RPC</h4> <p>Communication with Ethereum nodes is accomplished using <a rel="external" href="https://www.jsonrpc.org/specification">JSON-RPC</a>, a stateless, lightweight <a rel="external" href="https://en.wikipedia.org/wiki/Remote_procedure_call">remote procedure call</a> protocol that uses <a rel="external" href="http://www.json.org/">JSON</a> as its data format. Ethereum RPC methods <strong>MUST</strong> be called using <a rel="external" href="https://www.jsonrpc.org/specification#request_object">JSON-RPC request objects</a> and <strong>MUST</strong> respond with <a rel="external" href="https://www.jsonrpc.org/specification#response_object">JSON-RPC response objects</a>.</p> <h4 id="error-codes">Error codes</h4> <p>If an Ethereum RPC method encounters an error, the <code>error</code> member included on the response object <strong>MUST</strong> be an object containing a <code>code</code> member and descriptive <code>message</code> member. The following list contains all possible error codes and associated messages:</p> <table><thead><tr><th>Code</th><th>Message</th><th>Meaning</th><th>Category</th></tr></thead><tbody> <tr><td>-32700</td><td>Parse error</td><td>Invalid JSON</td><td>standard</td></tr> <tr><td>-32600</td><td>Invalid request</td><td>JSON is not a valid request object</td><td>standard</td></tr> <tr><td>-32601</td><td>Method not found</td><td>Method does not exist</td><td>standard</td></tr> <tr><td>-32602</td><td>Invalid params</td><td>Invalid method parameters</td><td>standard</td></tr> <tr><td>-32603</td><td>Internal error</td><td>Internal JSON-RPC error</td><td>standard</td></tr> <tr><td>-32000</td><td>Invalid input</td><td>Missing or invalid parameters</td><td>non-standard</td></tr> <tr><td>-32001</td><td>Resource not found</td><td>Requested resource not found</td><td>non-standard</td></tr> <tr><td>-32002</td><td>Resource unavailable</td><td>Requested resource not available</td><td>non-standard</td></tr> <tr><td>-32003</td><td>Transaction rejected</td><td>Transaction creation failed</td><td>non-standard</td></tr> <tr><td>-32004</td><td>Method not supported</td><td>Method is not implemented</td><td>non-standard</td></tr> <tr><td>-32005</td><td>Limit exceeded</td><td>Request exceeds defined limit</td><td>non-standard</td></tr> <tr><td>-32006</td><td>JSON-RPC version not supported</td><td>Version of JSON-RPC protocol is not supported</td><td>non-standard</td></tr> </tbody></table> <p>Example error response:</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-constant"> 1337</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">error</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">code</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-constant"> -</span><span class="z-constant">32003,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">message</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Transaction rejected</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="value-encoding">Value encoding</h4> <p>Specific types of values passed to and returned from Ethereum RPC methods require special encoding:</p> <h5 id="quantity"><code>Quantity</code></h5> <ul> <li>A <code>Quantity</code> value <strong>MUST</strong> be hex-encoded.</li> <li>A <code>Quantity</code> value <strong>MUST</strong> be "0x"-prefixed.</li> <li>A <code>Quantity</code> value <strong>MUST</strong> be expressed using the fewest possible hex digits per byte.</li> <li>A <code>Quantity</code> value <strong>MUST</strong> express zero as "0x0".</li> </ul> <p>Examples <code>Quantity</code> values:</p> <table><thead><tr><th>Value</th><th>Valid</th><th>Reason</th></tr></thead><tbody> <tr><td>0x</td><td><code>invalid</code></td><td>empty not a valid quantity</td></tr> <tr><td>0x0</td><td><code>valid</code></td><td>interpreted as a quantity of zero</td></tr> <tr><td>0x00</td><td><code>invalid</code></td><td>leading zeroes not allowed</td></tr> <tr><td>0x41</td><td><code>valid</code></td><td>interpreted as a quantity of 65</td></tr> <tr><td>0x400</td><td><code>valid</code></td><td>interpreted as a quantity of 1024</td></tr> <tr><td>0x0400</td><td><code>invalid</code></td><td>leading zeroes not allowed</td></tr> <tr><td>ff</td><td><code>invalid</code></td><td>values must be prefixed</td></tr> </tbody></table> <h5 id="block-identifier"><code>Block Identifier</code></h5> <p>The RPC methods below take a default block identifier as a parameter.</p> <ul> <li><code>eth_getBalance</code></li> <li><code>eth_getStorageAt</code></li> <li><code>eth_getTransactionCount</code></li> <li><code>eth_getCode</code></li> <li><code>eth_call</code></li> <li><code>eth_getProof</code></li> </ul> <p>Since there is no way to clearly distinguish between a <code>Data</code> parameter and a <code>Quantity</code> parameter, <a href="https://wg-eips.ritovision.com/1898/">EIP-1898</a> provides a format to specify a block either using the block hash or block number. The block identifier is a JSON <code>object</code> with the following fields:</p> <table><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td><code>[blockNumber]</code></td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>}</td><td>The block in the canonical chain with this number</td></tr> <tr><td>OR <code>[blockHash]</code></td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>The block uniquely identified by this hash. The <code>blockNumber</code> and <code>blockHash</code> properties are mutually exclusive; exactly one of them must be set.</td></tr> <tr><td><code>requireCanonical</code></td><td>{<code>boolean</code>}</td><td>(optional) Whether or not to throw an error if the block is not in the canonical chain as described below. Only allowed in conjunction with the <code>blockHash</code> tag. Defaults to <code>false</code>.</td></tr> </tbody></table> <p>If the block is not found, the callee SHOULD raise a JSON-RPC error (the recommended error code is <code>-32001: Resource not found</code>. If the tag is <code>blockHash</code> and <code>requireCanonical</code> is <code>true</code>, the callee SHOULD additionally raise a JSON-RPC error if the block is not in the canonical chain (the recommended error code is <code>-32000: Invalid input</code> and in any case should be different than the error code for the block not found case so that the caller can distinguish the cases). The block-not-found check SHOULD take precedence over the block-is-canonical check, so that if the block is not found the callee raises block-not-found rather than block-not-canonical.</p> <h5 id="data"><code>Data</code></h5> <ul> <li>A <code>Data</code> value <strong>MUST</strong> be hex-encoded.</li> <li>A <code>Data</code> value <strong>MUST</strong> be "0x"-prefixed.</li> <li>A <code>Data</code> value <strong>MUST</strong> be expressed using two hex digits per byte.</li> </ul> <p>Examples <code>Data</code> values:</p> <table><thead><tr><th>Value</th><th>Valid</th><th>Reason</th></tr></thead><tbody> <tr><td>0x</td><td><code>valid</code></td><td>interpreted as empty data</td></tr> <tr><td>0x0</td><td><code>invalid</code></td><td>each byte must be represented using two hex digits</td></tr> <tr><td>0x00</td><td><code>valid</code></td><td>interpreted as a single zero byte</td></tr> <tr><td>0x41</td><td><code>true</code></td><td>interpreted as a data value of 65</td></tr> <tr><td>0x004200</td><td><code>true</code></td><td>interpreted as a data value of 16896</td></tr> <tr><td>0xf0f0f</td><td><code>false</code></td><td>bytes require two hex digits</td></tr> <tr><td>004200</td><td><code>false</code></td><td>values must be prefixed</td></tr> </tbody></table> <h5 id="proposing-changes">Proposing changes</h5> <p>New Ethereum RPC methods and changes to existing methods <strong>MUST</strong> be proposed via the traditional EIP process. This allows for community consensus around new method implementations and proposed method modifications. RPC method proposals <strong>MUST</strong> reach "draft" status before being added to this proposal and the official Ethereum RPC specification defined herein.</p> <h3 id="methods">Methods</h3> <h4 id="web3-clientversion">web3_clientVersion</h4> <h5 id="description">Description</h5> <p>Returns the version of the current client</p> <h5 id="parameters">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns">Returns</h5> <p>{<code>string</code>} - client version</p> <h5 id="example">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;web3_clientVersion&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [],</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Mist/v0.9.3/darwin/go1.4.1</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="web3-sha3">web3_sha3</h4> <h5 id="description-1">Description</h5> <p>Hashes data using the Keccak-256 algorithm</p> <h5 id="parameters-1">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>data to hash</td></tr> </tbody></table> <h5 id="returns-1">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - Keccak-256 hash of the given data</p> <h5 id="example-1">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;web3_sha3&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0x68656c6c6f20776f726c64&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc94770007dda54cF92009BFF0dE90c06F603a09f</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="net-listening">net_listening</h4> <h5 id="description-2">Description</h5> <p>Determines if this client is listening for new network connections</p> <h5 id="parameters-2">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-2">Returns</h5> <p>{<code>boolean</code>} - <code>true</code> if listening is active or <code>false</code> if listening is not active</p> <h5 id="example-2">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;net_listening&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="net-peercount">net_peerCount</h4> <h5 id="description-3">Description</h5> <p>Returns the number of peers currently connected to this client</p> <h5 id="parameters-3">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-3">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - number of connected peers</p> <h5 id="example-3">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;net_peerCount&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x2</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="net-version">net_version</h4> <h5 id="description-4">Description</h5> <p>Returns the chain ID associated with the current network</p> <h5 id="parameters-4">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-4">Returns</h5> <p>{<code>string</code>} - chain ID associated with the current network</p> <p>Common chain IDs:</p> <ul> <li><code>"1"</code> - Ethereum mainnet</li> <li><code>"3"</code> - Ropsten testnet</li> <li><code>"4"</code> - Rinkeby testnet</li> <li><code>"42"</code> - Kovan testnet</li> </ul> <p><strong>Note:</strong> See EIP-155 for a <a href="https://wg-eips.ritovision.com/155/#list-of-chain-id-s">complete list</a> of possible chain IDs.</p> <h5 id="example-4">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;net_version&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">3</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-accounts">eth_accounts</h4> <h5 id="description-5">Description</h5> <p>Returns a list of addresses owned by this client</p> <h5 id="parameters-5">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-5">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data[]</code></a>} - array of addresses</p> <h5 id="example-5">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_accounts&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xc94770007dda54cF92009BFF0dE90c06F603a09f</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-blocknumber">eth_blockNumber</h4> <h5 id="description-6">Description</h5> <p>Returns the number of the most recent block seen by this client</p> <h5 id="parameters-6">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-6">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - number of the latest block</p> <h5 id="example-6">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_blockNumber&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc94</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-call">eth_call</h4> <h5 id="description-7">Description</h5> <p>Executes a new message call immediately without submitting a transaction to the network</p> <h5 id="parameters-7">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<code>object</code>}</td><td>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[from]</code> - transaction sender<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>to</code> - transaction recipient or <code>null</code> if deploying a contract<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[gas]</code> - gas provided for transaction execution<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[gasPrice]</code> - price in wei of each gas used<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[value]</code> - value in wei sent with this transaction<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[data]</code> - contract code or a hashed method call with encoded args</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>|<a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code>, or a block identifier as described in <a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a></td></tr> </tbody></table> <h5 id="returns-7">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - return value of executed contract</p> <h5 id="example-7">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_call&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [{</span></span> <span class="giallo-l"><span class="z-string"> &quot;data&quot;: &quot;0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;from&quot;: &quot;0xb60e8dd61c5d32be8058bb8eb970870f07233155&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;gas&quot;: &quot;0x76c0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;gasPrice&quot;: &quot;0x9184e72a000&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;to&quot;: &quot;0xd46e8dd67c5d32be8058bb8eb970870f07244567&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;value&quot;: &quot;0x9184e72a&quot;</span></span> <span class="giallo-l"><span class="z-string"> }]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-coinbase">eth_coinbase</h4> <h5 id="description-8">Description</h5> <p>Returns the coinbase address for this client</p> <h5 id="parameters-8">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-8">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - coinbase address</p> <h5 id="example-8">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_coinbase&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc94770007dda54cF92009BFF0dE90c06F603a09f</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-estimategas">eth_estimateGas</h4> <h5 id="description-9">Description</h5> <p>Estimates the gas necessary to complete a transaction without submitting it to the network</p> <p><strong>Note:</strong> The resulting gas estimation may be significantly more than the amount of gas actually used by the transaction. This is due to a variety of reasons including EVM mechanics and node performance.</p> <h5 id="parameters-9">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<code>object</code>}</td><td>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[from]</code> - transaction sender<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[to]</code> - transaction recipient<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[gas]</code> - gas provided for transaction execution<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[gasPrice]</code> - price in wei of each gas used<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[value]</code> - value in wei sent with this transaction<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[data]</code> - contract code or a hashed method call with encoded args</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code></td></tr> </tbody></table> <h5 id="returns-9">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - amount of gas required by transaction</p> <h5 id="example-9">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_estimateGas&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [{</span></span> <span class="giallo-l"><span class="z-string"> &quot;data&quot;: &quot;0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;from&quot;: &quot;0xb60e8dd61c5d32be8058bb8eb970870f07233155&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;gas&quot;: &quot;0x76c0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;gasPrice&quot;: &quot;0x9184e72a000&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;to&quot;: &quot;0xd46e8dd67c5d32be8058bb8eb970870f07244567&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;value&quot;: &quot;0x9184e72a&quot;</span></span> <span class="giallo-l"><span class="z-string"> }]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x5208</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-gasprice">eth_gasPrice</h4> <h5 id="description-10">Description</h5> <p>Returns the current price of gas expressed in wei</p> <h5 id="parameters-10">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-10">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - current gas price in wei</p> <h5 id="example-10">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_gasPrice&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x09184e72a000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getbalance">eth_getBalance</h4> <h5 id="description-11">Description</h5> <p>Returns the balance of an address in wei</p> <h5 id="parameters-11">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>address to query for balance</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>|<a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code>, or a block identifier as described in <a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a></td></tr> </tbody></table> <h5 id="returns-11">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - balance of the provided account in wei</p> <h5 id="example-11">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getBalance&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xc94770007dda54cF92009BFF0dE90c06F603a09f&quot;, &quot;latest&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0234c8a3397aab58</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getblockbyhash">eth_getBlockByHash</h4> <h5 id="description-12">Description</h5> <p>Returns information about a block specified by hash</p> <h5 id="parameters-12">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>hash of a block</td></tr> <tr><td>2</td><td>{<code>boolean</code>}</td><td><code>true</code> will pull full transaction objects, <code>false</code> will pull transaction hashes</td></tr> </tbody></table> <h5 id="returns-12">Returns</h5> <p>{<code>null|object</code>} - <code>null</code> if no block is found, otherwise a block object with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>extraData</code> - "extra data" field of this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>hash</code> - block hash or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>logsBloom</code> - logs bloom filter or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>miner</code> - address that received this block's mining rewards</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>nonce</code> - proof-of-work hash or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>parentHash</code> - parent block hash</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>receiptsRoot</code> -root of this block's receipts trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>sha3Uncles</code> - SHA3 of the uncles data in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>stateRoot</code> - root of this block's final state trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>transactionsRoot</code> - root of this block's transaction trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>difficulty</code> - difficulty for this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasLimit</code> - maximum gas allowed in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasUsed</code> - total used gas by all transactions in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>number</code> - block number or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>size</code> - size of this block in bytes</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>timestamp</code> - unix timestamp of when this block was collated</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>totalDifficulty</code> - total difficulty of the chain until this block</li> <li>{<code>Array&lt;Transaction&gt;</code>} <code>transactions</code> - list of transaction objects or hashes</li> <li>{<code>Array&lt;Transaction&gt;</code>} <code>uncles</code> - list of uncle hashes</li> </ul> <h5 id="example-12">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getBlockByHash&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;:[&quot;0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331&quot;, true]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">difficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">extraData</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasLimit</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logsBloom</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">miner</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4e65fda2159562a496f9f3522f89122a3088497a</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">number</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b4</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">parentHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">sha3Uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">size</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">stateRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">timestamp</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x54e34e8e</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">totalDifficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactions</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionsRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x1606e5...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5145a9...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getblockbynumber">eth_getBlockByNumber</h4> <h5 id="description-13">Description</h5> <p>Returns information about a block specified by number</p> <h5 id="parameters-13">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code></td></tr> <tr><td>2</td><td>{<code>boolean</code>}</td><td><code>true</code> will pull full transaction objects, <code>false</code> will pull transaction hashes</td></tr> </tbody></table> <h5 id="returns-13">Returns</h5> <p>{<code>null|object</code>} - <code>null</code> if no block is found, otherwise a block object with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>extraData</code> - "extra data" field of this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>hash</code> - block hash or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>logsBloom</code> - logs bloom filter or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>miner</code> - address that received this block's mining rewards</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>nonce</code> - proof-of-work hash or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>parentHash</code> - parent block hash</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>receiptsRoot</code> -root of this block's receipts trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>sha3Uncles</code> - SHA3 of the uncles data in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>stateRoot</code> - root of this block's final state trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>transactionsRoot</code> - root of this block's transaction trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>difficulty</code> - difficulty for this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasLimit</code> - maximum gas allowed in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasUsed</code> - total used gas by all transactions in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>number</code> - block number or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>size</code> - size of this block in bytes</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>timestamp</code> - unix timestamp of when this block was collated</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>totalDifficulty</code> - total difficulty of the chain until this block</li> <li>{<code>Array&lt;Transaction&gt;</code>} <code>transactions</code> - list of transaction objects or hashes</li> <li>{<code>Array&lt;Transaction&gt;</code>} <code>uncles</code> - list of uncle hashes</li> </ul> <h5 id="example-13">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getBlockByNumber&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;:[&quot;0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331&quot;, true]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">difficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">extraData</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasLimit</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logsBloom</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">miner</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4e65fda2159562a496f9f3522f89122a3088497a</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">number</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b4</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">parentHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">sha3Uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">size</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">stateRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">timestamp</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x54e34e8e</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">totalDifficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactions</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionsRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x1606e5...</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5145a9...</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getblocktransactioncountbyhash">eth_getBlockTransactionCountByHash</h4> <h5 id="description-14">Description</h5> <p>Returns the number of transactions in a block specified by block hash</p> <h5 id="parameters-14">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>hash of a block</td></tr> </tbody></table> <h5 id="returns-14">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - number of transactions in the specified block</p> <h5 id="example-14">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getBlockTransactionCountByHash&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xc94770007dda54cF92009BFF0dE90c06F603a09f&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getblocktransactioncountbynumber">eth_getBlockTransactionCountByNumber</h4> <h5 id="description-15">Description</h5> <p>Returns the number of transactions in a block specified by block number</p> <h5 id="parameters-15">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code></td></tr> </tbody></table> <h5 id="returns-15">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - number of transactions in the specified block</p> <h5 id="example-15">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getBlockTransactionCountByNumber&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xe8&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getcode">eth_getCode</h4> <h5 id="description-16">Description</h5> <p>Returns the contract code stored at a given address</p> <h5 id="parameters-16">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>address to query for code</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>|<a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code>, or a block identifier as described in <a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a></td></tr> </tbody></table> <h5 id="returns-16">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - code from the specified address</p> <h5 id="example-16">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getCode&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xa94f5374fce5edbc8e2a8697c15331677e6ebf0b&quot;, &quot;0x2&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x600160008035811a818181146012578301005b601b6001356025565b8060005260206000f25b600060078202905091905056</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getfilterchanges">eth_getFilterChanges</h4> <h5 id="description-17">Description</h5> <p>Returns a list of all logs based on filter ID since the last log retrieval</p> <h5 id="parameters-17">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>}</td><td>ID of the filter</td></tr> </tbody></table> <h5 id="returns-17">Returns</h5> <p>{<code>Array&lt;Log&gt;</code>} - array of log objects with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>address</code> - address from which this log originated</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>blockHash</code> - hash of block containing this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>data</code> - contains the non-indexed arguments of the log</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>transactionHash</code> - hash of the transaction that created this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>blockNumber</code> - number of block containing this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>logIndex</code> - index of this log within its block or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>transactionIndex</code> - index of the transaction that created this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data[]</code></a>} <code>topics</code> - list of order-dependent topics</li> <li>{<code>boolean</code>} <code>removed</code> - <code>true</code> if this filter has been destroyed and is invalid</li> </ul> <p><strong>Note:</strong> The return value of <code>eth_getFilterChanges</code> when retrieving logs from <code>eth_newBlockFilter</code> and <code>eth_newPendingTransactionFilter</code> filters will be an array of hashes, not an array of Log objects.</p> <h5 id="example-17">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getFilterChanges&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0x16&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">address</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockNumber</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x1b4</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">data</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">topics</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>],</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getfilterlogs">eth_getFilterLogs</h4> <h5 id="description-18">Description</h5> <p>Returns a list of all logs based on filter ID</p> <h5 id="parameters-18">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>}</td><td>ID of the filter</td></tr> </tbody></table> <h5 id="returns-18">Returns</h5> <p>{<code>Array&lt;Log&gt;</code>} - array of log objects with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} address - address from which this log originated</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} blockHash - hash of block containing this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} data - contains the non-indexed arguments of the log</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} transactionHash - hash of the transaction that created this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} blockNumber - number of block containing this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} logIndex - index of this log within its block or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} transactionIndex - index of the transaction that created this log or <code>null</code> if pending</li> <li>{<code>Array&lt;Data&gt;</code>} topics - list of order-dependent topics</li> <li>{<code>boolean</code>} removed - <code>true</code> if this filter has been destroyed and is invalid</li> </ul> <p><strong>Note:</strong> The return value of <code>eth_getFilterLogs</code> when retrieving logs from <code>eth_newBlockFilter</code> and <code>eth_newPendingTransactionFilter</code> filters will be an array of hashes, not an array of Log objects.</p> <h5 id="example-18">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getFilterLogs&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0x16&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">address</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockNumber</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x1b4</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">data</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">topics</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>],</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getlogs">eth_getLogs</h4> <h5 id="description-19">Description</h5> <p>Returns a list of all logs based on a filter object</p> <h5 id="parameters-19">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<code>object</code>}</td><td>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>} <code>[fromBlock]</code> - block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code><br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>} <code>[toBlock]</code> - block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code><br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>|<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data[]</code></a>} <code>[address]</code> - contract address or a list of addresses from which logs should originate<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data[]</code></a>} <code>[topics]</code> - list of order-dependent topics<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[blockhash]</code> - restrict logs to a block by hash</td></tr> </tbody></table> <p><strong>Note:</strong> If <code>blockhash</code> is passed, neither <code>fromBlock</code> nor <code>toBlock</code> are allowed or respected.</p> <h5 id="returns-19">Returns</h5> <p>{<code>Array&lt;Log&gt;</code>} - array of log objects with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>address</code> - address from which this log originated</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>blockHash</code> - hash of block containing this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>data</code> - contains the non-indexed arguments of the log</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>transactionHash</code> - hash of the transaction that created this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>blockNumber</code> - number of block containing this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>logIndex</code> - index of this log within its block or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>transactionIndex</code> - index of the transaction that created this log or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>topics</code> - list of order-dependent topics</li> <li>{<code>boolean</code>} <code>removed</code> - <code>true</code> if this filter has been destroyed and is invalid</li> </ul> <h5 id="example-19">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getLogs&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [{</span></span> <span class="giallo-l"><span class="z-string"> &quot;topics&quot;:[&quot;0x000000000000000000000000a94f5374fce5edbc8e2a8697c15331677e6ebf0b&quot;]</span></span> <span class="giallo-l"><span class="z-string"> }]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">address</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x16c5785ac562ff41e2dcfdf829c5a142f1fccd7d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcfdf829c5a142f1fccd7d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockNumber</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x1b4</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">data</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">topics</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>],</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xdf829c5a142f1fccd7d8216c5785ac562ff41e2dcfdf5785ac562ff41e2dcf</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getstorageat">eth_getStorageAt</h4> <h5 id="description-20">Description</h5> <p>Returns the value from a storage position at an address</p> <h5 id="parameters-20">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>address of stored data</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>}</td><td>index into stored data</td></tr> <tr><td>3</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>|<a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code>, or a block identifier as described in <a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a></td></tr> </tbody></table> <h5 id="returns-20">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - value stored at the given address and data index</p> <h5 id="example-20">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getStorageAt&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0x295a70b2de5e3953354a6a8344e616ed314d7251&quot;, &quot;0x0&quot;, &quot;latest&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000000004d2</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-gettransactionbyblockhashandindex">eth_getTransactionByBlockHashAndIndex</h4> <h5 id="description-21">Description</h5> <p>Returns information about a transaction specified by block hash and transaction index</p> <h5 id="parameters-21">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>hash of a block</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>}</td><td>index of a transaction in the specified block</td></tr> </tbody></table> <h5 id="returns-21">Returns</h5> <p>{<code>null|object</code>} - <code>null</code> if no transaction is found, otherwise a transaction object with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>r</code> - ECDSA signature r</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>s</code> - ECDSA signature s</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>blockHash</code> - hash of block containing this transaction or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>from</code> - transaction sender</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>hash</code> - hash of this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>input</code> - contract code or a hashed method call</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>to</code> - transaction recipient or <code>null</code> if deploying a contract</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>v</code> - ECDSA recovery ID</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>blockNumber</code> - number of block containing this transaction or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gas</code> - gas provided for transaction execution</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasPrice</code> - price in wei of each gas used</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>nonce</code> - unique number identifying this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>transactionIndex</code> - index of this transaction in the block or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>value</code> - value in wei sent with this transaction</li> </ul> <h5 id="example-21">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getTransactionByBlockHashAndIndex&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;:[&quot;0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331&quot;, &quot;0x0&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockNumber</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x5daf3b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">from</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa7d9ddbe1f17865597fbd27ec712455208b6b76d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gas</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc350</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasPrice</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4a817c800</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">input</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x68656c6c6f21</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x15</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">r</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">s</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">to</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x41</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">v</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x25</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">value</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf3dbb76162000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-gettransactionbyblocknumberandindex">eth_getTransactionByBlockNumberAndIndex</h4> <h5 id="description-22">Description</h5> <p>Returns information about a transaction specified by block number and transaction index</p> <h5 id="parameters-22">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code></td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>}</td><td>index of a transaction in the specified block</td></tr> </tbody></table> <h5 id="returns-22">Returns</h5> <p>{<code>null|object</code>} - <code>null</code> if no transaction is found, otherwise a transaction object with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>r</code> - ECDSA signature r</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>s</code> - ECDSA signature s</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>blockHash</code> - hash of block containing this transaction or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>from</code> - transaction sender</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>hash</code> - hash of this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>input</code> - contract code or a hashed method call</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>to</code> - transaction recipient or <code>null</code> if deploying a contract</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>v</code> - ECDSA recovery ID</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>blockNumber</code> - number of block containing this transaction or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gas</code> - gas provided for transaction execution</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasPrice</code> - price in wei of each gas used</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>nonce</code> - unique number identifying this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>transactionIndex</code> - index of this transaction in the block or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>value</code> - value in wei sent with this transaction</li> </ul> <h5 id="example-22">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getTransactionByBlockNumberAndIndex&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;:[&quot;0x29c&quot;, &quot;0x0&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockNumber</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x5daf3b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">from</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa7d9ddbe1f17865597fbd27ec712455208b6b76d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gas</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc350</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasPrice</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4a817c800</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">input</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x68656c6c6f21</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x15</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">r</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">s</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">to</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x41</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">v</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x25</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">value</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf3dbb76162000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-gettransactionbyhash">eth_getTransactionByHash</h4> <h5 id="description-23">Description</h5> <p>Returns information about a transaction specified by hash</p> <h5 id="parameters-23">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>hash of a transaction</td></tr> </tbody></table> <h5 id="returns-23">Returns</h5> <p>{<code>null|object</code>} - <code>null</code> if no transaction is found, otherwise a transaction object with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>r</code> - ECDSA signature r</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>s</code> - ECDSA signature s</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>blockHash</code> - hash of block containing this transaction or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>from</code> - transaction sender</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>hash</code> - hash of this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>input</code> - contract code or a hashed method call</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>to</code> - transaction recipient or <code>null</code> if deploying a contract</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>v</code> - ECDSA recovery ID</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>blockNumber</code> - number of block containing this transaction or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gas</code> - gas provided for transaction execution</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasPrice</code> - price in wei of each gas used</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>nonce</code> - unique number identifying this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>transactionIndex</code> - index of this transaction in the block or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>value</code> - value in wei sent with this transaction</li> </ul> <h5 id="example-23">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getTransactionByHash&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1d59ff54b1eb26b013ce3cb5fc9dab3705b415a67127a003c3e61eb445bb8df2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockNumber</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x5daf3b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">from</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa7d9ddbe1f17865597fbd27ec712455208b6b76d</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gas</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc350</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasPrice</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4a817c800</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x88df016429689c079f3b2f6ad39fa052532c56795b733da78a91ebe6a713944b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">input</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x68656c6c6f21</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x15</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">r</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b5e176d927f8e9ab405058b2d2457392da3e20f328b16ddabcebc33eaac5fea</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">s</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4ba69724e8f69de52f0125ad8b3c5c2cef33019bac3249e2c0a2192766d1721c</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">to</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf02c1c8e6114b1dbe8937a39260b5b0a374432bb</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x41</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">v</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x25</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">value</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf3dbb76162000</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-gettransactioncount">eth_getTransactionCount</h4> <h5 id="description-24">Description</h5> <p>Returns the number of transactions sent from an address</p> <h5 id="parameters-24">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>address to query for sent transactions</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>|<a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code>, or a block identifier as described in <a href="https://wg-eips.ritovision.com/1474/#block-identifier"><code>Block Identifier</code></a></td></tr> </tbody></table> <h5 id="returns-24">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - number of transactions sent from the specified address</p> <h5 id="example-24">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getTransactionCount&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xc94770007dda54cF92009BFF0dE90c06F603a09f&quot;, &quot;latest&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-gettransactionreceipt">eth_getTransactionReceipt</h4> <h5 id="description-25">Description</h5> <p>Returns the receipt of a transaction specified by hash</p> <p><strong>Note:</strong> Transaction receipts are unavailable for pending transactions.</p> <h5 id="parameters-25">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>hash of a transaction</td></tr> </tbody></table> <h5 id="returns-25">Returns</h5> <p>{<code>null|object</code>} - <code>null</code> if no transaction is found, otherwise a transaction receipt object with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>blockHash</code> - hash of block containing this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>contractAddress</code> - address of new contract or <code>null</code> if no contract was created</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>from</code> - transaction sender</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>logsBloom</code> - logs bloom filter</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>to</code> - transaction recipient or <code>null</code> if deploying a contract</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>transactionHash</code> - hash of this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>blockNumber</code> - number of block containing this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>cumulativeGasUsed</code> - gas used by this and all preceding transactions in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasUsed</code> - gas used by this transaction</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>status</code> - <code>1</code> if this transaction was successful or <code>0</code> if it failed</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>transactionIndex</code> - index of this transaction in the block</li> <li>{<code>Array&lt;Log&gt;</code>} <code>logs</code> - list of log objects generated by this transaction</li> </ul> <h5 id="example-25">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getTransactionReceipt&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">blockNumber</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0xb</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">contractAddress</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0xb60e8dd61c5d32be8058bb8eb970870f07233155</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">cumulativeGasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x33bc</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x4dc</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logs</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>],</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logsBloom</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00...0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">status</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionIndex</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getunclebyblockhashandindex">eth_getUncleByBlockHashAndIndex</h4> <h5 id="description-26">Description</h5> <p>Returns information about an uncle specified by block hash and uncle index position</p> <h5 id="parameters-26">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>hash of a block</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>}</td><td>index of uncle</td></tr> </tbody></table> <h5 id="returns-26">Returns</h5> <p>{<code>null|object</code>} - <code>null</code> if no block or uncle is found, otherwise an uncle object with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>extraData</code> - "extra data" field of this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>hash</code> - block hash or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>logsBloom</code> - logs bloom filter or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>miner</code> - address that received this block's mining rewards</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>nonce</code> - proof-of-work hash or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>parentHash</code> - parent block hash</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>receiptsRoot</code> -root of this block's receipts trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>sha3Uncles</code> - SHA3 of the uncles data in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>stateRoot</code> - root of this block's final state trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>transactionsRoot</code> - root of this block's transaction trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>difficulty</code> - difficulty for this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasLimit</code> - maximum gas allowed in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasUsed</code> - total used gas by all transactions in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>number</code> - block number or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>size</code> - size of this block in bytes</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>timestamp</code> - unix timestamp of when this block was collated</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>totalDifficulty</code> - total difficulty of the chain until this block</li> <li>{<code>Array&lt;Transaction&gt;</code>} <code>uncles</code> - list of uncle hashes</li> </ul> <h5 id="example-26">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getUncleByBlockHashAndIndex&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xc6ef2fc5426d6ad6fd9e2a26abeab0aa2411b7ab17f30a99d3cb96aed1d1055b&quot;, &quot;0x0&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">difficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">extraData</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasLimit</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logsBloom</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">miner</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4e65fda2159562a496f9f3522f89122a3088497a</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">number</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b4</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">parentHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">sha3Uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">size</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">stateRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">timestamp</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x54e34e8e</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">totalDifficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionsRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getunclebyblocknumberandindex">eth_getUncleByBlockNumberAndIndex</h4> <h5 id="description-27">Description</h5> <p>Returns information about an uncle specified by block number and uncle index position</p> <h5 id="parameters-27">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code></td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>}</td><td>index of uncle</td></tr> </tbody></table> <h5 id="returns-27">Returns</h5> <p>{<code>null|object</code>} - <code>null</code> if no block or uncle is found, otherwise an uncle object with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>extraData</code> - "extra data" field of this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>hash</code> - block hash or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>logsBloom</code> - logs bloom filter or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>miner</code> - address that received this block's mining rewards</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>nonce</code> - proof-of-work hash or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>parentHash</code> - parent block hash</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>receiptsRoot</code> -root of this block's receipts trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>sha3Uncles</code> - SHA3 of the uncles data in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>stateRoot</code> - root of this block's final state trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>transactionsRoot</code> - root of this block's transaction trie</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>difficulty</code> - difficulty for this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasLimit</code> - maximum gas allowed in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>gasUsed</code> - total used gas by all transactions in this block</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>number</code> - block number or <code>null</code> if pending</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>size</code> - size of this block in bytes</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>timestamp</code> - unix timestamp of when this block was collated</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>totalDifficulty</code> - total difficulty of the chain until this block</li> <li>{<code>Array&lt;Transaction&gt;</code>} <code>uncles</code> - list of uncle hashes</li> </ul> <h5 id="example-27">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getUncleByBlockNumberAndIndex&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0x29c&quot;, &quot;0x0&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">difficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">extraData</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0000000000000000000000000000000000000000000000000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasLimit</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">gasUsed</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9f759</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">hash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">logsBloom</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">miner</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4e65fda2159562a496f9f3522f89122a3088497a</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">nonce</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe04d296d2460cfb8472af2c5fd05b5a214109c25688d3704aed5484f9a7792f2</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">number</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1b4</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">parentHash</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x9646252be9520f6e71339a8df9c55e4d7619deeb018d2a3f2d21fc165dde5eb5</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">sha3Uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">size</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">stateRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xd5855eb08b3387c0af375e9cdb6acfc05eb8f519e419b874b6ff2ffda7ed1dff</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">timestamp</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x54e34e8e</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">totalDifficulty</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x027f07</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">transactionsRoot</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">uncles</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span><span>]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getunclecountbyblockhash">eth_getUncleCountByBlockHash</h4> <h5 id="description-28">Description</h5> <p>Returns the number of uncles in a block specified by block hash</p> <h5 id="parameters-28">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>hash of a block</td></tr> </tbody></table> <h5 id="returns-28">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - number of uncles in the specified block</p> <h5 id="example-28">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getUncleCountByBlockHash&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xc94770007dda54cF92009BFF0dE90c06F603a09f&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getunclecountbyblocknumber">eth_getUncleCountByBlockNumber</h4> <h5 id="description-29">Description</h5> <p>Returns the number of uncles in a block specified by block number</p> <h5 id="parameters-29">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>}</td><td>block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code></td></tr> </tbody></table> <h5 id="returns-29">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - number of uncles in the specified block</p> <h5 id="example-29">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getUncleCountByBlockNumber&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xe8&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-getwork">eth_getWork</h4> <h5 id="description-30">Description</h5> <p>Returns a list containing relevant information for proof-of-work</p> <h5 id="parameters-30">Parameters</h5> <p><em>none</em></p> <h5 id="returns-30">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data[]</code></a>} - array with the following items:</p> <ol> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - current block header pow-hash</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - seed hash used for the DAG</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - boundary condition ("target"), 2^256 / difficulty</li> </ol> <h5 id="example-30">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_getWork&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span> [</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">0x5EED00000000000000000000000000005EED0000000000000000000000000000</span><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">0xd1ff1c01710000000000000000000000d1ff1c01710000000000000000000000</span><span class="z-entity z-name">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-hashrate">eth_hashrate</h4> <h5 id="description-31">Description</h5> <p>Returns the number of hashes-per-second this node is mining at</p> <h5 id="parameters-31">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-31">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - number of hashes-per-second</p> <h5 id="example-31">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_hashrate&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x38a</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-mining">eth_mining</h4> <h5 id="description-32">Description</h5> <p>Determines if this client is mining new blocks</p> <h5 id="parameters-32">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-32">Returns</h5> <p>{<code>boolean</code>} - <code>true</code> if this client is mining or <code>false</code> if it is not mining</p> <h5 id="example-32">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_mining&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-newblockfilter">eth_newBlockFilter</h4> <h5 id="description-33">Description</h5> <p>Creates a filter to listen for new blocks that can be used with <code>eth_getFilterChanges</code></p> <h5 id="parameters-33">Parameters</h5> <p><em>none</em></p> <h5 id="returns-33">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - ID of the newly-created filter that can be used with <code>eth_getFilterChanges</code></p> <h5 id="example-33">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_newBlockFilter&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-newfilter">eth_newFilter</h4> <h5 id="description-34">Description</h5> <p>Creates a filter to listen for specific state changes that can then be used with <code>eth_getFilterChanges</code></p> <h5 id="parameters-34">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<code>object</code>}</td><td>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>} <code>[fromBlock]</code> - block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code><br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>|<code>string</code>} <code>[toBlock]</code> - block number, or one of <code>"latest"</code>, <code>"earliest"</code> or <code>"pending"</code><br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>|<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data[]</code></a>} <code>[address]</code> - contract address or a list of addresses from which logs should originate<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data[]</code></a>} <code>[topics]</code> - list of order-dependent topics</td></tr> </tbody></table> <p><strong>Note:</strong> Topics are order-dependent. A transaction with a log with topics <code>[A, B]</code> will be matched by the following topic filters:</p> <ul> <li><code>[]</code> - "anything"</li> <li><code>[A]</code> - "A in first position (and anything after)"</li> <li><code>[null, B]</code> - "anything in first position AND B in second position (and anything after)"</li> <li><code>[A, B]</code> - "A in first position AND B in second position (and anything after)"</li> <li><code>[[A, B], [A, B]]</code> - "(A OR B) in first position AND (A OR B) in second position (and anything after)"</li> </ul> <h5 id="returns-34">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - ID of the newly-created filter that can be used with <code>eth_getFilterChanges</code></p> <h5 id="example-34">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_newFilter&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [{</span></span> <span class="giallo-l"><span class="z-string"> &quot;topics&quot;: [&quot;0x0000000000000000000000000000000000000000000000000000000012341234&quot;]</span></span> <span class="giallo-l"><span class="z-string"> }]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-newpendingtransactionfilter">eth_newPendingTransactionFilter</h4> <h5 id="description-35">Description</h5> <p>Creates a filter to listen for new pending transactions that can be used with <code>eth_getFilterChanges</code></p> <h5 id="parameters-35">Parameters</h5> <p><em>none</em></p> <h5 id="returns-35">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} - ID of the newly-created filter that can be used with <code>eth_getFilterChanges</code></p> <h5 id="example-35">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_newPendingTransactionFilter&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-protocolversion">eth_protocolVersion</h4> <h5 id="description-36">Description</h5> <p>Returns the current Ethereum protocol version</p> <h5 id="parameters-36">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-36">Returns</h5> <p>{<code>string</code>} - current Ethereum protocol version</p> <h5 id="example-36">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_protocolVersion&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">54</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-sendrawtransaction">eth_sendRawTransaction</h4> <h5 id="description-37">Description</h5> <p>Sends and already-signed transaction to the network</p> <h5 id="parameters-37">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>signed transaction data</td></tr> </tbody></table> <h5 id="returns-37">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - transaction hash, or the zero hash if the transaction is not yet available</p> <h5 id="example-37">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_sendRawTransaction&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-sendtransaction">eth_sendTransaction</h4> <h5 id="description-38">Description</h5> <p>Creates, signs, and sends a new transaction to the network</p> <h5 id="parameters-38">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<code>object</code>}</td><td>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>from</code> - transaction sender<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[to]</code> - transaction recipient<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[gas="0x15f90"]</code> - gas provided for transaction execution<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[gasPrice]</code> - price in wei of each gas used<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[value]</code> - value in wei sent with this transaction<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[data]</code> - contract code or a hashed method call with encoded args<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[nonce]</code> - unique number identifying this transaction</td></tr> </tbody></table> <h5 id="returns-38">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - transaction hash, or the zero hash if the transaction is not yet available</p> <h5 id="example-38">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_sendTransaction&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [{</span></span> <span class="giallo-l"><span class="z-string"> &quot;data&quot;: &quot;0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;from&quot;: &quot;0xb60e8dd61c5d32be8058bb8eb970870f07233155&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;gas&quot;: &quot;0x76c0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;gasPrice&quot;: &quot;0x9184e72a000&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;to&quot;: &quot;0xd46e8dd67c5d32be8058bb8eb970870f07244567&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;value&quot;: &quot;0x9184e72a&quot;</span></span> <span class="giallo-l"><span class="z-string"> }]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-sign">eth_sign</h4> <h5 id="description-39">Description</h5> <p>Calculates an Ethereum-specific signature in the form of <code>keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))</code></p> <h5 id="parameters-39">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>address to use for signing</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>data to sign</td></tr> </tbody></table> <h5 id="returns-39">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - signature hash of the provided data</p> <h5 id="example-39">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_sign&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0x9b2055d370f73ec7d8a03e965129118dc8f5bf83&quot;, &quot;0xdeadbeaf&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-signtransaction">eth_signTransaction</h4> <h5 id="description-40">Description</h5> <p>Signs a transaction that can be submitted to the network at a later time using with <code>eth_sendRawTransaction</code></p> <h5 id="parameters-40">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<code>object</code>}</td><td>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>from</code> - transaction sender<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[to]</code> - transaction recipient<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[gas="0x15f90"]</code> - gas provided for transaction execution<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[gasPrice]</code> - price in wei of each gas used<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[value]</code> - value in wei sent with this transaction<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} <code>[data]</code> - contract code or a hashed method call with encoded args<br/>@property {<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>[nonce]</code> - unique number identifying this transaction</td></tr> </tbody></table> <h5 id="returns-40">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - signature hash of the transaction object</p> <h5 id="example-40">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_signTransaction&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [{</span></span> <span class="giallo-l"><span class="z-string"> &quot;data&quot;: &quot;0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;from&quot;: &quot;0xb60e8dd61c5d32be8058bb8eb970870f07233155&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;gas&quot;: &quot;0x76c0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;gasPrice&quot;: &quot;0x9184e72a000&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;to&quot;: &quot;0xd46e8dd67c5d32be8058bb8eb970870f07244567&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;value&quot;: &quot;0x9184e72a&quot;</span></span> <span class="giallo-l"><span class="z-string"> }]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xa3f20717a250c2b0b729b7e5becbff67fdaef7e0699da4de7ca5895b02a170a12d887fd3b17bfdce3481f10bea41f45ba9f709d39ce8325427b57afcfc994cee1b</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-signtypeddata">eth_signTypedData</h4> <h5 id="description-41">Description</h5> <p>Calculates an Ethereum-specific signature in the form of <code>keccak256("\x19Ethereum Signed Message:\n" + len(message) + message))</code></p> <h5 id="parameters-41">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>address to use for signing</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>message to sign containing type information, a domain separator, and data</td></tr> </tbody></table> <p><strong>Note:</strong> Client developers should refer to EIP-712 for complete semantics around <a href="https://wg-eips.ritovision.com/712/#specification">encoding and signing data</a>. Dapp developers should refer to EIP-712 for the expected structure of <a href="https://wg-eips.ritovision.com/712/#parameters">RPC method input parameters</a>.</p> <h5 id="returns-41">Returns</h5> <p>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>} - signature hash of the provided message</p> <h5 id="example-41">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_signTypedData&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826&quot;, {</span></span> <span class="giallo-l"><span class="z-string"> &quot;types&quot;: {</span></span> <span class="giallo-l"><span class="z-string"> &quot;EIP712Domain&quot;: [{</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;name&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span class="z-string"> }, {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;version&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span class="z-string"> }, {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;chainId&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;: &quot;uint256&quot;</span></span> <span class="giallo-l"><span class="z-string"> }, {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;verifyingContract&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;: &quot;address&quot;</span></span> <span class="giallo-l"><span class="z-string"> }],</span></span> <span class="giallo-l"><span class="z-string"> &quot;Person&quot;: [{</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;name&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span class="z-string"> }, {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;wallet&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;: &quot;address&quot;</span></span> <span class="giallo-l"><span class="z-string"> }],</span></span> <span class="giallo-l"><span class="z-string"> &quot;Mail&quot;: [{</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;from&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;: &quot;Person&quot;</span></span> <span class="giallo-l"><span class="z-string"> }, {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;to&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;: &quot;Person&quot;</span></span> <span class="giallo-l"><span class="z-string"> }, {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;contents&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;: &quot;string&quot;</span></span> <span class="giallo-l"><span class="z-string"> }]</span></span> <span class="giallo-l"><span class="z-string"> },</span></span> <span class="giallo-l"><span class="z-string"> &quot;primaryType&quot;: &quot;Mail&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;domain&quot;: {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;Ether Mail&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;version&quot;: &quot;1&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;chainId&quot;: 1,</span></span> <span class="giallo-l"><span class="z-string"> &quot;verifyingContract&quot;: &quot;0xCcCCccccCCCCcCCCCCCcCcCccCcCCCcCcccccccC&quot;</span></span> <span class="giallo-l"><span class="z-string"> },</span></span> <span class="giallo-l"><span class="z-string"> &quot;message&quot;: {</span></span> <span class="giallo-l"><span class="z-string"> &quot;from&quot;: {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;Cow&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;wallet&quot;: &quot;0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826&quot;</span></span> <span class="giallo-l"><span class="z-string"> },</span></span> <span class="giallo-l"><span class="z-string"> &quot;to&quot;: {</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;: &quot;Bob&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;wallet&quot;: &quot;0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB&quot;</span></span> <span class="giallo-l"><span class="z-string"> },</span></span> <span class="giallo-l"><span class="z-string"> &quot;contents&quot;: &quot;Hello, Bob!&quot;</span></span> <span class="giallo-l"><span class="z-string"> }</span></span> <span class="giallo-l"><span class="z-string"> }]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x4355c47d63924e8a72e509b65029052eb6c299d53a04e167c5775fd466751c9d07299936d304c153f6443dfa05f40ff007d72911b6f72307f996231605b915621c</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-submithashrate">eth_submitHashrate</h4> <h5 id="description-42">Description</h5> <p>Submit a mining hashrate</p> <h5 id="parameters-42">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>hash rate</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>random ID identifying this node</td></tr> </tbody></table> <h5 id="returns-42">Returns</h5> <p>{<code>boolean</code>} - <code>true</code> if submitting went through successfully, <code>false</code> otherwise</p> <h5 id="example-42">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_submitHashrate&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [</span></span> <span class="giallo-l"><span class="z-string"> &quot;0x0000000000000000000000000000000000000000000000000000000000500000&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;0x59daa26581d0acd1fce254fb7e85952f4c09d0915afd33d3886cd914bc7d283c&quot;</span></span> <span class="giallo-l"><span class="z-string"> ]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-submitwork">eth_submitWork</h4> <h5 id="description-43">Description</h5> <p>Submit a proof-of-work solution</p> <h5 id="parameters-43">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>nonce found</td></tr> <tr><td>2</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>header's pow-hash</td></tr> <tr><td>3</td><td>{<a href="https://wg-eips.ritovision.com/1474/#data"><code>Data</code></a>}</td><td>mix digest</td></tr> </tbody></table> <h5 id="returns-43">Returns</h5> <p>{<code>boolean</code>} - <code>true</code> if the provided solution is valid, <code>false</code> otherwise</p> <h5 id="example-43">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_submitWork&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [</span></span> <span class="giallo-l"><span class="z-string"> &quot;0x0000000000000001&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;0xD1GE5700000000000000000000000000D1GE5700000000000000000000000000&quot;</span></span> <span class="giallo-l"><span class="z-string"> ]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-syncing">eth_syncing</h4> <h5 id="description-44">Description</h5> <p>Returns information about the status of this client's network synchronization</p> <h5 id="parameters-44">Parameters</h5> <p><em>(none)</em></p> <h5 id="returns-44">Returns</h5> <p>{<code>boolean|object</code>} - <code>false</code> if this client is not syncing with the network, otherwise an object with the following members:</p> <ul> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>currentBlock</code> - number of the most-recent block synced</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>highestBlock</code> - number of latest block on the network</li> <li>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>} <code>startingBlock</code> - block number at which syncing started</li> </ul> <h5 id="example-44">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_syncing&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: []</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">currentBlock</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x386</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">highestBlock</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x454</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">startingBlock</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x384</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h4 id="eth-uninstallfilter">eth_uninstallFilter</h4> <h5 id="description-45">Description</h5> <p>Destroys a filter based on filter ID</p> <p><strong>Note:</strong> This should only be called if a filter and its notifications are no longer needed. This will also be called automatically on a filter if its notifications are not retrieved using <code>eth_getFilterChanges</code> for a period of time.</p> <h5 id="parameters-45">Parameters</h5> <table><thead><tr><th>#</th><th>Type</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>{<a href="https://wg-eips.ritovision.com/1474/#quantity"><code>Quantity</code></a>}</td><td>ID of the filter to destroy</td></tr> </tbody></table> <h5 id="returns-45">Returns</h5> <p>{<code>boolean</code>} - <code>true</code> if the filter is found and successfully destroyed or <code>false</code> if it is not</p> <h5 id="example-45">Example</h5> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Request</span></span> <span class="giallo-l"><span class="z-entity z-name">curl</span><span class="z-constant"> -</span><span class="z-constant">X</span><span class="z-string"> POST</span><span class="z-constant"> -</span><span class="z-constant">-data</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">{</span></span> <span class="giallo-l"><span class="z-string"> &quot;id&quot;: 1337,</span></span> <span class="giallo-l"><span class="z-string"> &quot;jsonrpc&quot;: &quot;2.0&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;method&quot;: &quot;eth_uninstallFilter&quot;,</span></span> <span class="giallo-l"><span class="z-string"> &quot;params&quot;: [&quot;0xb&quot;]</span></span> <span class="giallo-l"><span class="z-string">}</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> &lt;</span><span class="z-string">ur</span><span>l</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Response</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">id</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-string"> 1337,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">jsonrpc</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span></span> <span class="giallo-l"><span class="z-entity z-name"> &quot;</span><span class="z-entity z-name">result</span><span class="z-entity z-name">&quot;</span><span class="z-support">:</span><span class="z-constant"> true</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <hr /> <h2 id="rationale">Rationale</h2> <p>Much of Ethereum's effectiveness as an enterprise-grade application platform depends on its ability to provide a reliable and predictable developer experience. Nodes created by the current generation of Ethereum clients expose RPC endpoints with differing method signatures; this forces applications to work around method inconsistencies to maintain compatibility with various Ethereum RPC implementations.</p> <p>Both Ethereum client developers and downstream dapp developers lack a formal Ethereum RPC specification. This proposal standardizes such a specification in a way that's versionable and modifiable through the traditional EIP process.</p> <h2 id="backwards-compatibility">Backwards compatibility</h2> <p>This proposal impacts Ethereum client developers by requiring that any exposed RPC interface adheres to this specification. This proposal impacts dapp developers by requiring that any RPC calls currently used in applications are made according to this specification.</p> <h2 id="implementation">Implementation</h2> <p>The current generation of Ethereum clients includes several implementations that attempt to expose this RPC specification:</p> <table><thead><tr><th>Client Name</th><th>Language</th><th>Homepage</th></tr></thead><tbody> <tr><td>Geth</td><td>Go</td><td><a rel="external" href="https://geth.ethereum.org">geth.ethereum.org</a></td></tr> <tr><td>Parity</td><td>Rust</td><td><a rel="external" href="https://parity.io/ethereum">parity.io/ethereum</a></td></tr> <tr><td>Aleth</td><td>C++</td><td><a rel="external" href="https://cpp-ethereum.org">cpp-ethereum.org</a></td></tr> </tbody></table> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-10-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Maxim Kupriianovmk@atlant.io Julian Svirskyjs@atlant.io https://wg-eips.ritovision.com/1462/ <h2 id="simple-summary">Simple Summary</h2> <p>An extension to ERC-20 standard token that provides compliance with securities regulations and legal enforceability.</p> <h2 id="abstract">Abstract</h2> <p>This EIP defines a minimal set of additions to the default token standard such as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a>, that allows for compliance with domestic and international legal requirements. Such requirements include KYC (Know Your Customer) and AML (Anti Money Laundering) regulations, and the ability to lock tokens for an account, and restrict them from transfer due to a legal dispute. Also the ability to attach additional legal documentation, in order to set up a dual-binding relationship between the token and off-chain legal entities.</p> <p>The scope of this standard is being kept as narrow as possible to avoid restricting potential use-cases of this base security token. Any additional functionality and limitations not defined in this standard may be enforced on per-project basis.</p> <h2 id="motivation">Motivation</h2> <p>There are several security token standards that have been proposed recently. Examples include <a rel="external" href="https://github.com/ethereum/EIPs/issues/1411">ERC-1400</a>, also <a rel="external" href="https://eips.ethereum.org/EIPS/eip-1450">ERC-1450</a>. We have concerns about each of them, mostly because the scope of each of these EIPs contains many project-specific or market-specific details. Since many EIPs are coming from the respective backing companies, they capture many niche requirements that are excessive for a general case.</p> <p>For instance, ERC-1411 uses dependency on <a rel="external" href="https://github.com/ethereum/eips/issues/1410">ERC-1410</a> but it falls out of the "security tokens" scope. Also its dependency on <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> will block the adoption for a quite period of time before ERC-777 is finalized, but the integration guidelines for existing ERC-20 workflows are not described in that EIP, yet. Another attempt to make a much simpler base standard <a rel="external" href="https://github.com/ethereum/EIPs/issues/1404">ERC-1404</a> is missing a few important points, specifically it doesn't provide enough granularity to distinguish between different ERC-20 transfer functions such as <code>transfer</code> and <code>transferFrom</code>. It also doesn't provide a way to bind legal documentation to the issued tokens.</p> <p>What we propose in this EIP is a simple and very modular solution for creating a base security token for the widest possible scope of applications, so it can be used by other issuers to build upon. The issuers should be able to add more restrictions and policies to the token, using the functions and implementation proposed below, but they must not be limited in any way while using this ERC.</p> <h2 id="specification">Specification</h2> <p>The ERC-20 token provides the following basic features:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> spender</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable"> spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> spender</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This will be extended as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> BaseSecurityToken</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC-20 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Checking functions</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkTransferAllowed</span><span> (</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkTransferFromAllowed</span><span> (</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkMintAllowed</span><span> (</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkBurnAllowed</span><span> (</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Documentation functions</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> attachDocument</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _name</span><span>,</span><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _uri</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _contentHash</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lookupDocument</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _name</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span>,</span><span class="z-support"> bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="transfer-checking-functions">Transfer Checking Functions</h3> <p>We introduce four new functions that should be used to check that the actions are allowed for the provided inputs. The implementation details of each function are left for the token issuer, it is the issuer's responsibility to add all necessary checks that will validate an operation in accordance with KYC/AML policies and legal requirements set for a specific token asset.</p> <p>Each function must return a status code from the common set of Ethereum status codes (ESC), according to <a href="https://wg-eips.ritovision.com/1066/">ERC-1066</a>. Localization of these codes is out of the scope of this proposal and may be optionally solved by adopting <a href="https://wg-eips.ritovision.com/1444/">ERC-1444</a> on the application level. If the operation is allowed by a checking function, the return status code must be <code>0x11</code> (Allowed) or an issuer-specific code with equivalent but more precise meaning. If the operation is not allowed by a checking function, the status must be <code>0x10</code> (Disallowed) or an issuer-specific code with equivalent but more precise meaning. Upon an internal error, the function must return the most relevant code from the general code table or an issuer-specific equivalent, example: <code>0xF0</code> (Off-Chain Failure).</p> <p><strong>For <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> based tokens,</strong></p> <ul> <li>It is required that transfer function must be overridden with logic that checks the corresponding checkTransferAllowed return status code.</li> <li>It is required that <code>transferFrom</code> function must be overridden with logic that checks the corresponding <code>checkTransferFromAllowed</code> return status code.</li> <li>It is required that <code>approve</code> function must be overridden with logic that checks the corresponding <code>checkTransferFromAllowed</code> return status code.</li> <li>Other functions such as <code>mint</code> and <code>burn</code> must be overridden, if they exist in the token implementation, they should check <code>checkMintAllowed</code> and <code>checkBurnAllowed</code> status codes accordingly.</li> </ul> <p><strong>For <a href="https://wg-eips.ritovision.com/777/">ERC-777</a> based tokens,</strong></p> <ul> <li>It is required that <code>send</code> function must be overridden with logic that checks the corresponding return status codes: <ul> <li><code>checkTransferAllowed</code> return status code, if transfer happens on behalf of the tokens owner;</li> <li><code>checkTransferFromAllowed</code> return status code, if transfer happens on behalf of an operator (i.e. delegated transfer).</li> </ul> </li> <li>It is required that <code>burn</code> function must be overridden with logic that checks the corresponding <code>checkBurnAllowed</code> return status code.</li> <li>Other functions, such as <code>mint</code> must be overridden, if they exist in the token implementation, e.g. if the security token is mintable. <code>mint</code> function must call <code>checkMintAllowed</code> ad check it return status code.</li> </ul> <p>For both cases,</p> <ul> <li>It is required for guaranteed compatibility with ERC-20 and ERC-777 wallets that each checking function returns <code>0x11</code> (Allowed) if not overridden with the issuer's custom logic.</li> <li>It is required that all overridden checking functions must revert if the action is not allowed or an error occurred, according to the returned status code.</li> </ul> <p>Inside checker functions the logic is allowed to use any feature available on-chain: perform calls to registry contracts with whitelists/blacklists, use built-in checking logic that is defined on the same contract, or even run off-chain queries through an oracle.</p> <h3 id="documentation-functions">Documentation Functions</h3> <p>We also introduce two new functions that should be used for document management purposes. Function <code>attachDocument</code> adds a reference pointing to an off-chain document, with specified name, URI and contents hash. The hashing algorithm is not specified within this standard, but the resulting hash must not be longer than 32 bytes. Function <code>lookupDocument</code> gets the referenced document by its name.</p> <ul> <li>It is not required to use documentation functions, they are optional and provided as a part of a legal framework.</li> <li>It is required that if <code>attachDocument</code> function has been used, the document reference must have a unique name, overwriting the references under same name is not allowed. All implementations must check if the reference under the given name is already existing.</li> </ul> <h2 id="rationale">Rationale</h2> <p>This EIP targets both ERC-20 and ERC-777 based tokens, although the most emphasis is given to ERC-20 due to its widespread adoption. However, this extension is designed to be compatible with the forthcoming ERC-777 standard, as well.</p> <p>All checking functions are named with prefixes <code>check</code> since they return check status code, not booleans, because that is important to facilitate the debugging and tracing process. It is responsibility of the issuer to implement the logic that will handle the return codes appropriately. Some handlers will simply throw errors, other handlers would log information for future process mining. More rationale for status codes can be seen in <a href="https://wg-eips.ritovision.com/1066/">ERC-1066</a>.</p> <p>We require two different transfer validation functions: <code>checkTransferAllowed</code> and <code>checkTransferFromAllowed</code> since the corresponding <code>transfer</code> and <code>transferFrom</code> are usually called in different contexts. Some token standards such as <a href="https://wg-eips.ritovision.com/1450/">ERC-1450</a> explicitly disallow use of <code>transfer</code>, while allowing only <code>transferFrom</code>. There might be also different complex scenarios, where <code>transfer</code> and <code>transferFrom</code> should be treated differently. ERC-777 is relying on its own <code>send</code> for transferring tokens, so it is reasonable to switch between checker functions based on its call context. We decided to omit the <code>checkApprove</code> function since it would be used in exactly the same context as <code>checkTransferFromAllowed</code>. In many cases it is required not only regulate securities transfers, but also restrict burn and <code>mint</code> operations, and additional checker functions have been added for that.</p> <p>The documentation functions that we propose here are a must-have tool to create dual-bindings with off-chain legal documents, a great example of this can be seen in <a rel="external" href="https://medium.com/@ZoeAdamovicz/37376fd0384a">Neufund's Employee Incentive Options Plan</a> legal framework that implements full legal enforceability: the smart contract refers to printed ESOP Terms &amp; Conditions Document, which itself refers back to smart contract. This is becoming a widely adopted practice even in cases where there are no legal requirements to reference the documents within the security token. However they're almost always required, and it's a good way to attach useful documentation of various types.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully backwards compatible as its implementation extends the functionality of ERC-20 and ERC-777 tokens.</p> <h2 id="implementation">Implementation</h2> <ul> <li>https://github.com/AtlantPlatform/BaseSecurityToken</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-09-26T00:00:00+00:00 2026-02-11T14:49:27+00:00 Felix Langehttps://github.com/fjl Péter Szilágyihttps://github.com/karalabe https://wg-eips.ritovision.com/1459/

Scheme for authenticated updateable Ethereum node lists via DNS.

<h2 id="abstract">Abstract</h2> <p>This document describes a scheme for authenticated, updateable Ethereum node lists retrievable via DNS.</p> <h2 id="motivation">Motivation</h2> <p>Many Ethereum clients contain hard-coded bootstrap node lists. Updating those lists requires a software update. The current lists are small, giving the client little choice of initial entry point into the Ethereum network. We would like to maintain larger node lists containing hundreds of nodes, and update them regularly.</p> <p>The scheme described here is a replacement for client bootstrap node lists with equivalent security and many additional benefits. Large lists populated by traversing the node discovery DHT can serve as a fallback option for nodes which can't join the DHT due to restrictive network policy. DNS-based node lists may also be useful to Ethereum peering providers because their customers can configure the client to use the provider's list.</p> <h2 id="specification">Specification</h2> <p>A 'node list' is a list of 'node records' <a href="https://wg-eips.ritovision.com/778/">as defined by EIP-778</a> of arbitrary length. Lists may refer to other lists using links. The entire list is signed using a secp256k1 private key. The corresponding public key must be known to the client in order to verify the list.</p> <p>To refer to a DNS node list, clients use a URL with 'enrtree' scheme. The URL contains the DNS name on which the list can be found as well as the public key that signed the list. The public key is contained in the username part of the URL and is the base32 encoding (RFC-4648) of the compressed 32-byte binary public key.</p> <p>Example:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>enrtree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@nodes.example.org</span></span></code></pre> <p>This URL refers to a node list at the DNS name 'nodes.example.org' and is signed by the public key <code>0x049f88229042fef9200246f49f94d9b77c4e954721442714e85850cb6d9e5daf2d880ea0e53cb3ac1a75f9923c2726a4f941f7d326781baa6380754a360de5c2b6</code></p> <h3 id="dns-record-structure">DNS Record Structure</h3> <p>The nodes in a list are encoded as a merkle tree for distribution via the DNS protocol. Entries of the merkle tree are contained in DNS TXT records. The root of the tree is a TXT record with the following content:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>enrtree-root:v1 e=&lt;enr-root&gt; l=&lt;link-root&gt; seq=&lt;sequence-number&gt; sig=&lt;signature&gt;</span></span></code></pre> <p>where</p> <ul> <li><code>enr-root</code> and <code>link-root</code> refer to the root hashes of subtrees containing nodes and links subtrees.</li> <li><code>sequence-number</code> is the tree's update sequence number, a decimal integer.</li> <li><code>signature</code> is a 65-byte secp256k1 EC signature over the keccak256 hash of the record content, excluding the <code>sig=</code> part, encoded as URL-safe base64 (RFC-4648).</li> </ul> <p>Further TXT records on subdomains map hashes to one of three entry types. The subdomain name of any entry is the base32 encoding of the (abbreviated) keccak256 hash of its text content.</p> <ul> <li><code>enrtree-branch:&lt;h₁&gt;,&lt;h₂&gt;,...,&lt;hₙ&gt;</code> is an intermediate tree entry containing hashes of subtree entries.</li> <li><code>enrtree://&lt;key&gt;@&lt;fqdn&gt;</code> is a leaf pointing to a different list located at another fully qualified domain name. Note that this format matches the URL encoding. This type of entry may only appear in the subtree pointed to by <code>link-root</code>.</li> <li><code>enr:&lt;node-record&gt;</code> is a leaf containing a node record. The node record is encoded as a URL-safe base64 string. Note that this type of entry matches the canonical ENR text encoding. It may only appear in the <code>enr-root</code> subtree.</li> </ul> <p>No particular ordering or structure is defined for the tree. Whenever the tree is updated, its sequence number should increase. The content of any TXT record should be small enough to fit into the 512 byte limit imposed on UDP DNS packets. This limits the number of hashes that can be placed into an <code>enrtree-branch</code> entry.</p> <p>Example in zone file format:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>; name ttl class type content</span></span> <span class="giallo-l"><span>@ 60 IN TXT enrtree-root:v1 e=JWXYDBPXYWG6FX3GMDIBFA6CJ4 l=C7HRFPF3BLGF3YR4DY5KX3SMBE seq=1 sig=o908WmNp7LibOfPsr4btQwatZJ5URBr2ZAuxvK4UWHlsB9sUOTJQaGAlLPVAhM__XJesCHxLISo94z5Z2a463gA</span></span> <span class="giallo-l"><span>C7HRFPF3BLGF3YR4DY5KX3SMBE 86900 IN TXT enrtree://AM5FCQLWIZX2QFPNJAP7VUERCCRNGRHWZG3YYHIUV7BVDQ5FDPRT2@morenodes.example.org</span></span> <span class="giallo-l"><span>JWXYDBPXYWG6FX3GMDIBFA6CJ4 86900 IN TXT enrtree-branch:2XS2367YHAXJFGLZHVAWLQD4ZY,H4FHT4B454P6UXFD7JCYQ5PWDY,MHTDO6TMUBRIA2XWG5LUDACK24</span></span> <span class="giallo-l"><span>2XS2367YHAXJFGLZHVAWLQD4ZY 86900 IN TXT enr:-HW4QOFzoVLaFJnNhbgMoDXPnOvcdVuj7pDpqRvh6BRDO68aVi5ZcjB3vzQRZH2IcLBGHzo8uUN3snqmgTiE56CH3AMBgmlkgnY0iXNlY3AyNTZrMaECC2_24YYkYHEgdzxlSNKQEnHhuNAbNlMlWJxrJxbAFvA</span></span> <span class="giallo-l"><span>H4FHT4B454P6UXFD7JCYQ5PWDY 86900 IN TXT enr:-HW4QAggRauloj2SDLtIHN1XBkvhFZ1vtf1raYQp9TBW2RD5EEawDzbtSmlXUfnaHcvwOizhVYLtr7e6vw7NAf6mTuoCgmlkgnY0iXNlY3AyNTZrMaECjrXI8TLNXU0f8cthpAMxEshUyQlK-AM0PW2wfrnacNI</span></span> <span class="giallo-l"><span>MHTDO6TMUBRIA2XWG5LUDACK24 86900 IN TXT enr:-HW4QLAYqmrwllBEnzWWs7I5Ev2IAs7x_dZlbYdRdMUx5EyKHDXp7AV5CkuPGUPdvbv1_Ms1CPfhcGCvSElSosZmyoqAgmlkgnY0iXNlY3AyNTZrMaECriawHKWdDRk2xeZkrOXBQ0dfMFLHY4eENZwdufn1S1o</span></span></code></pre><h3 id="client-protocol">Client Protocol</h3> <p>To find nodes at a given DNS name, say "mynodes.org":</p> <ol> <li>Resolve the TXT record of the name and check whether it contains a valid "enrtree-root=v1" entry. Let's say the <code>enr-root</code> hash contained in the entry is "CFZUWDU7JNQR4VTCZVOJZ5ROV4".</li> <li>Verify the signature on the root against the known public key and check whether the sequence number is larger than or equal to any previous number seen for that name.</li> <li>Resolve the TXT record of the hash subdomain, e.g. "CFZUWDU7JNQR4VTCZVOJZ5ROV4.mynodes.org" and verify whether the content matches the hash.</li> <li>The next step depends on the entry type found: <ul> <li>for <code>enrtree-branch</code>: parse the list of hashes and continue resolving them (step 3).</li> <li>for <code>enr</code>: decode, verify the node record and import it to local node storage.</li> </ul> </li> </ol> <p>During traversal, the client must track hashes and domains which are already resolved to avoid going into an infinite loop. It's in the client's best interest to traverse the tree in random order.</p> <p>Client implementations should avoid downloading the entire tree at once during normal operation. It's much better to request entries via DNS when-needed, i.e. at the time when the client is looking for peers.</p> <h2 id="rationale">Rationale</h2> <h3 id="why-dns">Why DNS?</h3> <p>We have chosen DNS as the distribution medium because it is always available, even under restrictive network conditions. The protocol provides low latency and answers to DNS queries can be cached by intermediate resolvers. No custom server software is needed. Node lists can be deployed to any DNS provider such as CloudFlare DNS, dnsimple, Amazon Route 53 using their respective client libraries.</p> <h3 id="why-is-this-a-merkle-tree">Why is this a merkle tree?</h3> <p>Being a merkle tree, any node list can be authenticated by a single signature on the root. Hash subdomains protect the integrity of the list. At worst intermediate resolvers can block access to the list or disallow updates to it, but cannot corrupt its content. The sequence number prevents replacing the root with an older version.</p> <p>Synchronizing updates on the client side can be done incrementally, which matters for large lists. Individual entries of the tree are small enough to fit into a single UDP packet, ensuring compatibility with environments where only basic UDP DNS is available. The tree format also works well with caching resolvers: only the root of the tree needs a short TTL. Intermediate entries and leaves can be cached for days.</p> <h3 id="why-does-the-link-subtree-exist">Why does the link subtree exist?</h3> <p>Links between lists enable federation and web-of-trust functionality. The operator of a large list can delegate maintenance to other list providers. If two node lists link to each other, users can use either list and get nodes from both.</p> <p>The link subtree is separate from the tree containing ENRs. This is done to enable client implementations to sync these trees independently. A client wanting to get as many nodes as possible will sync the link tree first and add all linked names to the sync horizon.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Discovery via DNS is less secure than via DHT, because it relies on a trusted party to publish the records regularly. The actor could easily eclipse bootstrapping nodes by only publishing node records that it controls.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-09-25T00:00:00+00:00 2026-02-11T14:48:25+00:00 John Shiplehttps://github.com/johnshiple Howard Markshoward@startengine.com David Zhangdavid@startengine.com https://wg-eips.ritovision.com/1450/ <h1 id="erc-1450-a-compatible-security-token-for-issuing-and-trading-sec-compliant-securities">ERC-1450 - A compatible security token for issuing and trading SEC-compliant securities</h1> <h2 id="simple-summary">Simple Summary</h2> <p><code>ERC-1450</code> is an <code>ERC-20</code> compatible token that enables issuing tokens representing securities that are required to comply with one or more of the following <a rel="external" href="https://www.sec.gov/smallbusiness/exemptofferings">Securities Act Regulations: Regulation Crowdfunding, Regulation D, and Regulation A</a>.</p> <h2 id="abstract">Abstract</h2> <p><code>ERC-1450</code> facilitates the recording of ownership and transfer of securities sold in compliance with the <a rel="external" href="https://www.sec.gov/smallbusiness/exemptofferings">Securities Act Regulations CF, D and A</a>. The issuance and trading of securities is subject to the Securities Exchange Commission (SEC) and specific U.S. state blue sky laws and regulations.</p> <p><code>ERC-1450</code> manages securities ownership during issuance and trading. The Issuer is the only role that should create a <code>ERC-1450</code> and assign the RTA. The RTA is the only role that is allowed to execute <code>ERC-1450</code>’s <code>mint</code>, <code>burnFrom</code>, and <code>transferFrom</code> functions. No role is allowed to execute <code>ERC-1450</code>’s <code>transfer</code> function.</p> <h2 id="motivation">Motivation</h2> <p>With the advent of the <a rel="external" href="https://www.sec.gov/spotlight/jobs-act.shtml">JOBS Act</a> in 2012 and the launch of Regulation Crowdfunding and the amendments to Regulation A and Regulation D in 2016, there has been an expansion in the exemptions available to Issuers and Investors to sell and purchase securities that have not been "registered" with the SEC under the Securities Act of 1933.</p> <p>There are currently no token standards that expressly facilitate conformity to securities law and related regulations. ERC-20 tokens do not support the regulated roles of Funding Portal, Broker Dealer, RTA, and Investor and do not support the <a rel="external" href="https://www.occ.treas.gov/topics/compliance-bsa/bsa/index-bsa.html">Bank Secrecy Act/USA Patriot Act KYC and AML requirements</a>. Other improvements (notably <a rel="external" href="https://github.com/ethereum/EIPs/issues/1404">EIP-1404 (Simple Restricted Token Standard)</a> have tried to tackle KYC and AML regulatory requirement. This approach is novel because the RTA is solely responsible for performing KYC and AML and should be solely responsible for <code>transferFrom</code>, <code>mint</code>, and <code>burnFrom</code>.</p> <h2 id="specification">Specification</h2> <p><code>ERC-1450</code> extends <code>ERC-20</code>.</p> <h3 id="erc-1450"><code>ERC-1450</code></h3> <p><code>ERC-1450</code> requires that only the Issuer can create a token representing the security that only the RTA manages. Instantiating the <code>ERC-1450</code> requires the <code>Owned</code> and <code>IssuerControlled</code> modifiers, and only the Issuer should execute the <code>ERC-1450</code> constructor for a compliant token. <code>ERC-1450</code> extends the general <code>Ownable</code> modifier to describe a specific subset of owners that automate and decentralize compliance through the contract modifiers <code>Owned</code> and <code>IssuerControlled</code> and the function modifiers <code>onlyOwner</code> and <code>onlyIssuerTransferAgent</code>. The <code>Owned</code> contract modifier instantiates the <code>onlyOwner</code> modifier for functions. The <code>IssuerControlled</code> modifier instantiates the <code>onlyIssuerTransferAgent</code> modifier for functions.</p> <p><code>ERC-1450</code> must prevent anyone from executing the <code>transfer</code>, <code>allowance</code>, and <code>approve</code> functions and/or implement these functions to always fail. <code>ERC-1450</code> updates the <code>transferFrom</code>, <code>mint</code>, and <code>burnFrom</code> functions. <code>transferFrom</code>, <code>mint</code>, and <code>burnFrom</code> may only be executed by the RTA and are restricted with the <code>onlyIssuerTransferAgent</code> modifier. Additionally, <code>ERC-1450</code> defines the functions <code>transferOwnership</code>, <code>setTransferAgent</code>, <code>setPhysicalAddressOfOperation</code>, and <code>isTransferAgent</code>. Only the issuer may call the <code>transferOwnership</code>, <code>setTransferAgent</code>, and <code>setPhysicalAddressOfOperation</code> functions. Anyone may call the <code>isTransferAgent</code> function.</p> <h3 id="issuers-and-rtas">Issuers and RTAs</h3> <p>For compliance reasons, the <code>ERC-1450</code> constructor must specify the issuer (the <code>owner</code>), the RTA (<code>transferAgent</code>), the security’s <code>name</code>, and the security’s <code>symbol</code>.</p> <h4 id="issuer-owned">Issuer Owned</h4> <p><code>ERC-1450</code> must specify the <code>owner</code> in its constructor, apply the <code>Owned</code> modifier, and instantiate the <code>onlyOwner</code> modifier to enable specific functions to permit only the Issuer’s <code>owner</code> address to execute them. <code>ERC-1450</code> also defines the function <code>transferOwnership</code> which transfers ownership of the Issuer to the new <code>owner</code>’s address and can only be called by the <code>owner</code>. <code>transferOwnership</code> triggers the <code>OwnershipTransferred</code> event.</p> <h4 id="issuer-controlled">Issuer Controlled</h4> <p><code>IssuerControlled</code> maintains the Issuer’s ownership of their securities by owning the contract and enables the Issuer to set and update the RTA for the Issuer’s securities. <code>ERC-1450</code>‘s constructor must have an <code>IssuerControlled</code> modifier with the issuer specified in its <code>ERC-1450</code> constructor. <code>IssuerControlled</code> instantiates the <code>onlyIssuerTransferAgent</code> modifier for <code>ERC-1450</code> to enable specific functions (<code>setPhysicalAddressOfOperation</code> and <code>setTransferAgent</code>) to permit only the Issuer to execute these functions.</p> <h4 id="register-transfer-agent-controlled">Register Transfer Agent Controlled</h4> <p><code>ERC-1450</code> defines the <code>setTransferAgent</code> function (to change the RTA) and <code>setPhysicalAddressOfOperation</code> function (to change the Issuer’s address) and must restrict execution to the Issuer’s owner with the <code>onlyOwner</code> modifier. <code>setTransferAgent</code> must emit the <code>TransferAgentUpdated</code> event. <code>setPhysicalAddressOfOperation</code> must emit the <code>PhysicalAddressOfOperationUpdated</code> event.</p> <p><code>ERC-1450</code> must specify the <code>transferAgent</code> in its constructor and instantiate the <code>onlyIssuerTransferAgent</code> modifier to enable specific functions (<code>transferFrom</code>, <code>mint</code>, and <code>burnFrom</code>) to permit only the Issuer’s <code>transferAgent</code> address to execute them. <code>ERC-1450</code> also defines the public function <code>isTransferAgent</code> to lookup and identify the Issuer’s RTA.</p> <h4 id="securities">Securities</h4> <p><code>ERC-1450</code> updates the <code>transferFrom</code>, <code>mint</code>, and <code>burnFrom</code> functions by applying the <code>onlyIssuerTransferAgent</code> to enable the issuance, re-issuance, and trading of securities.</p> <h3 id="erc-20-extension">ERC-20 Extension</h3> <p><code>ERC-20</code> tokens provide the following functionality:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable"> who</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> spender</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable"> from</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable"> spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> spender</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>ERC-20</code> is extended as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * ERC-1450 is an ERC-20 compatible token that facilitates compliance with one or more of Securities Act Regulations CF, D and A. </span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * Implementations of the ERC-1450 standard must define the following optional ERC-20</span></span> <span class="giallo-l"><span class="z-comment"> * fields:</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * name - The name of the security</span></span> <span class="giallo-l"><span class="z-comment"> * symbol - The symbol of the security</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Implementations of the ERC-1450 standard must specify the following constructor</span></span> <span class="giallo-l"><span class="z-comment"> * arguments:</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * _owner - the address of the owner</span></span> <span class="giallo-l"><span class="z-comment"> * _transferAgent - the address of the transfer agent</span></span> <span class="giallo-l"><span class="z-comment"> * _name - the name of the security</span></span> <span class="giallo-l"><span class="z-comment"> * _symbol - the symbol of the security</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Implementations of the ERC-1450 standard must implement the following contract</span></span> <span class="giallo-l"><span class="z-comment"> * modifiers:</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Owned - Only the address of the security’s issuer is permitted to execute the</span></span> <span class="giallo-l"><span class="z-comment"> * token’s constructor. This modifier also sets up the onlyOwner function modifier.</span></span> <span class="giallo-l"><span class="z-comment"> * IssuerControlled - This modifier sets up the onlyIssuerTransferAgent function modifier.</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Implementations of the ERC-1450 standard must implement the following function</span></span> <span class="giallo-l"><span class="z-comment"> * modifiers:</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * onlyOwner - Only the address of the security’s issuer is permitted to execute the</span></span> <span class="giallo-l"><span class="z-comment"> * functions transferOwnership, setTransferAgent, and setPhysicalAddressOfOperation.</span></span> <span class="giallo-l"><span class="z-comment"> * onlyIssuerTransferAgent - Only the address of the issuer’s Registered Transfer</span></span> <span class="giallo-l"><span class="z-comment"> * Agent is permitted to execute the functions transferFrom, mint, and burnFrom.</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Implementations of the ERC-1450 standard must implement the following required ERC-20</span></span> <span class="giallo-l"><span class="z-comment"> * event to always fail:</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Approval - Should never be called as the functions that emit this event must be</span></span> <span class="giallo-l"><span class="z-comment"> * implemented to always fail. </span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Implementations of the ERC-1450 standard must implement the following required</span></span> <span class="giallo-l"><span class="z-comment"> * ERC-20 functions to always fail:</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * transfer - Not a legal, regulated call for transferring securities because</span></span> <span class="giallo-l"><span class="z-comment"> * the token holder initiates the token transfer. The function must be implemented to</span></span> <span class="giallo-l"><span class="z-comment"> * always fail.</span></span> <span class="giallo-l"><span class="z-comment"> * allowance - Not a legal, regulated call for transferring securities because</span></span> <span class="giallo-l"><span class="z-comment"> * the token holder may not allow third parties to initiate token transfers. The</span></span> <span class="giallo-l"><span class="z-comment"> * function must be implemented to always fail.</span></span> <span class="giallo-l"><span class="z-comment"> * approve - Not a legal, regulated call for transferring securities because</span></span> <span class="giallo-l"><span class="z-comment"> * the token holder may not allow third parties to initiate token transfers. The</span></span> <span class="giallo-l"><span class="z-comment"> * function must be implemented to always fail.</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Implementations of the ERC-1450 standard must implement the following optional</span></span> <span class="giallo-l"><span class="z-comment"> * ERC-20 function:</span></span> <span class="giallo-l"><span class="z-comment"> * decimals - Must return &#39;0&#39; because securities are indivisible entities.</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * Implementations of the ERC-1450 standard must implement the following functions:</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> * mint - Only the address of the issuer&#39;s Registered Transfer Agent may create new</span></span> <span class="giallo-l"><span class="z-comment"> * securities.</span></span> <span class="giallo-l"><span class="z-comment"> * burnFrom - Only the address of the issuer’s Registered Transfer Agent may burn or </span></span> <span class="giallo-l"><span class="z-comment"> * destroy securities.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Contract ERC</span><span class="z-keyword">-</span><span class="z-constant">1450</span><span> is Owned</span><span>,</span><span> IssuerControlled </span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * The constructor must implement a modifier (Owned) that creates the onlyOwner modifier</span></span> <span class="giallo-l"><span class="z-comment"> * to allow only the address of the issuer (the owner) to execute the transferOwnership,</span></span> <span class="giallo-l"><span class="z-comment"> * setTransferAgent, and setPhysicalAddressOfOperation functions. The construct must also</span></span> <span class="giallo-l"><span class="z-comment"> * implement a modifier (TransferAgentControlled) that creates the onlyIssuerTransferAgent</span></span> <span class="giallo-l"><span class="z-comment"> * modifier to allow only the address of the issuer’s Registered Transfer Agent to execute</span></span> <span class="giallo-l"><span class="z-comment"> * the functions transferFrom, mint, and burnFrom).</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _transferAgent</span><span>,</span><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _name</span><span>,</span><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _symbol</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> Owned</span><span>(</span><span>_issuer) </span><span class="z-entity z-name">TransferAgentControlled</span><span>(</span><span>_transferAgent) </span><span class="z-storage z-type">public</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Specify that only the </span><span class="z-entity z-name">owner</span><span> (</span><span>issuer) may execute a function.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * onlyOwner requires the msg.sender to be the owner’s address.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> modifier </span><span class="z-entity z-name">onlyOwner</span><span>(</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Specify that only the issuer’s transferAgent may execute a function.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * onlyIssuerTransferAgent requires the msg.sender to be the transferAgent’s address.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> modifier </span><span class="z-entity z-name">onlyIssuerTransferAgent</span><span>(</span><span>);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Transfer ownership of a security from one issuer to another issuer.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * transferOwnership must implement the onlyOwner modifier to only allow the</span></span> <span class="giallo-l"><span> * address of the issuer’s owner to transfer ownership.</span></span> <span class="giallo-l"><span> * transferOwnership requires the _newOwner address to be the address of the new</span></span> <span class="giallo-l"><span> * issuer.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function </span><span class="z-entity z-name">transferOwnership</span><span>(</span><span>address _newOwner) </span><span class="z-storage z-type">public</span><span> onlyOwner;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Triggered after transferOwnership is executed.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event </span><span class="z-entity z-name">OwnershipTransferred</span><span>(</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Sets the transfer agent for the security.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * setTransferAgent must implement the onlyOwner modifier to only allow the</span></span> <span class="giallo-l"><span> * address of the issuer’s specify the security’s transfer agent.</span></span> <span class="giallo-l"><span> * setTransferAgent requires the _newTransferAgent address to be the address of the</span></span> <span class="giallo-l"><span> * new transfer agent.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function </span><span class="z-entity z-name">setTransferAgent</span><span>(</span><span>address _newTransferAgent) </span><span class="z-storage z-type">public</span><span> onlyOwner;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Triggered after setTransferAgent is executed.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event </span><span class="z-entity z-name">TransferAgentUpdated</span><span>(</span><span>address indexed previousTransferAgent, address indexed</span></span> <span class="giallo-l"><span> newTransferAgent);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Sets the issuers physical address of operation.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * setPhysicalAddressOfOperation must implement the onlyOwner modifier to only allow</span></span> <span class="giallo-l"><span> * the address of the issuer’s owner to transfer ownership.</span></span> <span class="giallo-l"><span> * setPhysicalAddressOfOperation requires the _newPhysicalAddressOfOperation address</span></span> <span class="giallo-l"><span> * to be the new address of the issuer.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function </span><span class="z-entity z-name">setPhysicalAddressOfOperation</span><span>(</span><span>string _newPhysicalAddressOfOperation) </span><span class="z-storage z-type">public</span></span> <span class="giallo-l"><span> onlyOwner;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Triggered after setPhysicalAddressOfOperation is executed.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event </span><span class="z-entity z-name">PhysicalAddressOfOperationUpdated</span><span>(</span><span>string previousPhysicalAddressOfOperation,</span></span> <span class="giallo-l"><span> string newPhysicalAddressOfOperation);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Look up the security’s transfer agent.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * isTransferAgent is a </span><span class="z-storage z-type">public</span><span> function.</span></span> <span class="giallo-l"><span> * isTransferAgent requires the _lookup address to determine if that address</span></span> <span class="giallo-l"><span> * is the security’s transfer agent.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function </span><span class="z-entity z-name">isTransferAgent</span><span>(</span><span>address _lookup) </span><span class="z-storage z-type">public</span><span> view </span><span class="z-entity z-name">returns</span><span> (</span><span>bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * transfer is not a legal, regulated call and must be implemented to always fail.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> transfer</span><span>(</span><span>address to, uint tokens) </span><span class="z-storage z-type">public</span><span class="z-entity z-name"> returns</span><span> (</span><span>bool success);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Approval does not have to be implemented. This event should never be triggered as</span></span> <span class="giallo-l"><span> * the functions that emit this even are not legal, regulated calls.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event </span><span class="z-entity z-name">Approval</span><span>(</span><span>address indexed tokenOwner, address indexed spender, uint tokens);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * allowance is not a legal, regulated call and must be implemented to always fail.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> allowance</span><span>(</span><span>address tokenOwner, address spender) </span><span class="z-storage z-type">public</span><span> constant </span><span class="z-entity z-name">returns</span><span> (</span><span>uint remaining);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * approve is not a legal, regulated call and must be implemented to always fail.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> approve</span><span>(</span><span>address spender, uint tokens) </span><span class="z-storage z-type">public</span><span class="z-entity z-name"> returns</span><span> (</span><span>bool success);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Transfer securities.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * transferFrom must implement the onlyIssuerTransferAgent modifier to only allow the</span></span> <span class="giallo-l"><span> * address of the issuer’s Registered Transfer Agent to transfer `ERC-1450`s.</span></span> <span class="giallo-l"><span> * transferFrom requires the _from address to have _value tokens.</span></span> <span class="giallo-l"><span> * transferFrom requires that the _to address must not be 0 because securities must</span></span> <span class="giallo-l"><span> * not destroyed in this manner.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function </span><span class="z-entity z-name">transferFrom</span><span>(</span><span>address _from, address _to, uint256 _value) </span><span class="z-storage z-type">public</span></span> <span class="giallo-l"><span> onlyIssuerTransferAgent </span><span class="z-entity z-name">returns</span><span> (</span><span>bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Create new securities.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * mint must implement the onlyIssuerTransferAgent modifier to only allow the address</span></span> <span class="giallo-l"><span> * of the issuer’s Registered Transfer Agent to mint `ERC-1450` tokens.</span></span> <span class="giallo-l"><span> * mint requires that the _to address must not be 0 because securities must</span></span> <span class="giallo-l"><span> * not destroyed in this manner.</span></span> <span class="giallo-l"><span> * mint must add _value tokens to the _to address and increase the totalSupply by</span></span> <span class="giallo-l"><span> * _value.</span></span> <span class="giallo-l"><span> * mint must emit the Transfer event.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function </span><span class="z-entity z-name">mint</span><span>(</span><span>address _to, uint256 _value) </span><span class="z-storage z-type">public</span><span> onlyIssuerTransferAgent returns</span></span> <span class="giallo-l"><span> (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Burn or destroy securities.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * burnFrom must implement the onlyIssuerTransferAgent modifier to only allow the</span></span> <span class="giallo-l"><span> * address of the issuer’s Registered Transfer Agent to burn `ERC-1450`s.</span></span> <span class="giallo-l"><span> * burnFrom requires the _from address to have _value tokens.</span></span> <span class="giallo-l"><span> * burnFrom must subtract _value tokens from the _from address and decrease the</span></span> <span class="giallo-l"><span> * totalSupply by _value.</span></span> <span class="giallo-l"><span> * burnFrom must emit the Transfer event.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function </span><span class="z-entity z-name">burnFrom</span><span>(</span><span>address _who, uint256 _value) </span><span class="z-storage z-type">public</span><span> onlyIssuerTransferAgent returns</span></span> <span class="giallo-l"><span> (bool);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="securities-exchange-commission-requirements">Securities Exchange Commission Requirements</h3> <p>The SEC has very strict requirements as to the specific roles that are allowed to perform specific actions. Specifically, only the RTA may <code>mint</code> and <code>transferFrom</code> securities.</p> <p>Implementers must maintain off-chain services and databases that record and track the Investor’s name, physical address, Ethereum address, and security ownership amount. The implementers and the SEC must be able to access the Investor’s private information on an as needed basis. Issuers and the RTA must be able to produce a current list of all Investors, including the names, addresses, and security ownership levels for every security at any given moment. Issuers and the RTA must be able to re-issue securities to Investors for a variety of regulated reasons.</p> <p>Private Investor information must never be publicly exposed on a public blockchain.</p> <h3 id="managing-investor-information">Managing Investor Information</h3> <p>Special care and attention must be taken to ensure that the personally identifiable information of Investors is never exposed or revealed to the public.</p> <h3 id="issuers-who-lost-access-to-their-address-or-private-keys">Issuers who lost access to their address or private keys</h3> <p>There is no recourse if the Issuer loses access to their address to an existing instance of their securities. Special care and efforts must be made by the Issuer to secure and safely store their address and associated private key. The Issuer can reassign ownership to another Issuer but not in the case where the Issuer loses their private key.</p> <p>If the Issuer loses access, the Issuer’s securities must be rebuilt using off-chain services. The Issuer must create (and secure) a new address. The RTA can read the existing Issuer securities, and the RTA can <code>mint</code> Investor securities accordingly under a new <code>ERC-1450</code> smart contract.</p> <h3 id="registered-transfer-agents-who-lost-access-to-their-address-or-private-keys">Registered Transfer Agents who lost access to their address or private keys</h3> <p>If the RTA loses access, the RTA can create a new Ethereum address, and the Issuer can execute the <code>setTransferAgent</code> function to reassign the RTA.</p> <h3 id="handling-investors-security-owners-who-lost-access-to-their-addresses-or-private-keys">Handling Investors (security owners) who lost access to their addresses or private keys</h3> <p>Investors may “lose” their credentials for a number of reasons: they simply “lost” their credentials, they were hacked or the victim of fraud, they committed securities-related fraud, or a life event (like death) occurred. Because the RTA manages the Issuer’s securities, the RTA may authorize ownership related changes of securities (as long as they are properly notarized and verified).</p> <p>If an Investor (or, say, the Investor’s heir) loses their credentials, the Investor must go through a notarized process to notify the RTA of the situation and supply a new Investor address. From there, the RTA can <code>mint</code> the “lost” securities to the new Investor address and <code>burnFrom</code> the old Investor address (because the RTA knows all Investors’ addresses).</p> <h2 id="rationale">Rationale</h2> <p>The are currently no token standards that facilitate compliance with SEC regulations. The closest token is <a href="https://wg-eips.ritovision.com/884/">ERC-884 (Delaware General Corporations Law (DGCL) compatible share token)</a> which states that SEC requirements are out of scope. <a rel="external" href="https://github.com/ethereum/EIPs/issues/1404">EIP-1404 (Simple Restricted Token Standard)</a> does not go far enough to address SEC requirements around re-issuing securities to Investors.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p><code>ERC-1450</code> maintains compatibility with ERC-20 tokens with the following stipulations:</p> <ul> <li><code>function allowance(address tokenOwner, address spender) public constant returns (uint remaining);</code> <ul> <li>Must be implemented to always fail because allowance is not a legal, regulated call for a security.</li> </ul> </li> <li><code>function transfer(address to, uint tokens) public returns (bool success);</code> <ul> <li>As the token holder initiates the transfer, must be implemented to always fail because transfer is not a legal, regulated call for a security.</li> </ul> </li> <li><code>function approve(address spender, uint tokens) public returns (bool success);</code> <ul> <li>Must be implemented to always fail because approve is not a legal, regulated call for a security</li> </ul> </li> <li><code>function transferFrom(address from, address to, uint tokens) public returns (bool success);</code> <ul> <li>Must be implemented so that only the Issuer’s RTA can perform this action</li> </ul> </li> <li><code>event Approval(address indexed tokenOwner, address indexed spender, uint tokens);</code> <ul> <li>Does not have to be implemented. Approval should never be called as the functions that emit this event must be implemented to always fail</li> </ul> </li> </ul> <h2 id="test-cases">Test Cases</h2> <p>Test cases are available at <a rel="external" href="https://github.com/StartEngine/ldgr_smart_contracts/tree/master/test">https://github.com/StartEngine/ldgr_smart_contracts/tree/master/test</a>.</p> <h2 id="implementations">Implementations</h2> <p>A reference implementation is available at <a rel="external" href="https://github.com/StartEngine/ldgr_smart_contracts">https://github.com/StartEngine/ldgr_smart_contracts</a>.</p> <h2 id="copyright-waiver">Copyright Waiver</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-09-23T00:00:00+00:00 2026-02-11T14:48:26+00:00 Brooklyn Zelenkahttps://github.com/expede Jennifer Cooperhttps://github.com/jenncoop https://wg-eips.ritovision.com/1444/ <h2 id="simple-summary">Simple Summary</h2> <p>A method of converting machine codes to human-readable text in any language and phrasing.</p> <h2 id="abstract">Abstract</h2> <p>An on-chain system for providing user feedback by converting machine-efficient codes into human-readable strings in any language or phrasing. The system does not impose a list of languages, but rather lets users create, share, and use the localizated text of their choice.</p> <h2 id="motivation">Motivation</h2> <p>There are many cases where an end user needs feedback or instruction from a smart contract. Directly exposing numeric codes does not make for good UX or DX. If Ethereum is to be a truly global system usable by experts and lay persons alike, systems to provide feedback on what happened during a transaction are needed in as many languages as possible.</p> <p>Returning a hard-coded string (typically in English) only serves a small segment of the global population. This standard proposes a method to allow users to create, register, share, and use a decentralized collection of translations, enabling richer messaging that is more culturally and linguistically diverse.</p> <p>There are several machine efficient ways of representing intent, status, state transition, and other semantic signals including booleans, enums and <a href="https://wg-eips.ritovision.com/1066/">ERC-1066 codes</a>. By providing human-readable messages for these signals, the developer experience is enhanced by returning easier to consume information with more context (ex. <code>revert</code>). End user experience is enhanced by providing text that can be propagated up to the UI.</p> <h2 id="specification">Specification</h2> <h3 id="contract-architecture">Contract Architecture</h3> <p>Two types of contract: <code>LocalizationPreferences</code>, and <code>Localization</code>s.</p> <p>The <code>LocalizationPreferences</code> contract functions as a proxy for <code>tx.origin</code>.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> +--------------+</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> +------&gt; | Localization |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | +--------------+</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span>+-----------+ +-------------------------+ | +--------------+</span></span> <span class="giallo-l"><span>| | | | &lt;------+ | |</span></span> <span class="giallo-l"><span>| Requestor | &lt;------&gt; | LocalizationPreferences | &lt;-------------&gt; | Localization |</span></span> <span class="giallo-l"><span>| | | | &lt;------+ | |</span></span> <span class="giallo-l"><span>+-----------+ +-------------------------+ | +--------------+</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> |</span></span> <span class="giallo-l"><span> | +--------------+</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> +------&gt; | Localization |</span></span> <span class="giallo-l"><span> | |</span></span> <span class="giallo-l"><span> +--------------+</span></span></code></pre><h3 id="localization"><code>Localization</code></h3> <p>A contract that holds a simple mapping of codes to their text representations.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> Localization</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> textFor</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _code</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _text</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="textfor"><code>textFor</code></h4> <p>Fetches the localized text representation.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> textFor</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _code</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _text</span><span>)</span><span>;</span></span></code></pre><h3 id="localizationpreferences"><code>LocalizationPreferences</code></h3> <p>A proxy contract that allows users to set their preferred <code>Localization</code>. Text lookup is delegated to the user's preferred contract.</p> <p>A fallback <code>Localization</code> with all keys filled MUST be available. If the user-specified <code>Localization</code> has not explicitly set a loalization (ie. <code>textFor</code> returns <code>""</code>), the <code>LocalizationPreferences</code> MUST redelegate to the fallback <code>Localization</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> LocalizationPreferences</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> set</span><span>(</span><span class="z-storage z-type">Localization</span><span class="z-variable z-parameter z-function"> _localization</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> textFor</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _code</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable z-parameter z-function"> _wasFound</span><span>,</span><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _text</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="set"><code>set</code></h4> <p>Registers a user's preferred <code>Localization</code>. The registering user SHOULD be considered <code>tx.origin</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> set</span><span>(</span><span class="z-storage z-type">Localization</span><span class="z-variable z-parameter z-function"> _localization</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span></code></pre><h4 id="textfor-1"><code>textFor</code></h4> <p>Retrieve text for a code found at the user's preferred <code>Localization</code> contract.</p> <p>The first return value (<code>bool _wasFound</code>) represents if the text is available from that <code>Localization</code>, or if a fallback was used. If the fallback was used in this context, the <code>textFor</code>'s first return value MUST be set to <code>false</code>, and is <code>true</code> otherwise.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> textFor</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _code</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable z-parameter z-function"> _wasFound</span><span>,</span><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _text</span><span>)</span><span>;</span></span></code></pre><h3 id="string-format">String Format</h3> <p>All strings MUST be encoded as <a rel="external" href="https://www.ietf.org/rfc/rfc3629.txt">UTF-8</a>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-string">&quot;Špeĉiäl chârãçtérs are permitted&quot;</span></span> <span class="giallo-l"><span class="z-string">&quot;As are non-Latin characters: アルミ缶の上にあるみかん。&quot;</span></span> <span class="giallo-l"><span class="z-string">&quot;Emoji are legal: 🙈🙉🙊🎉&quot;</span></span> <span class="giallo-l"><span class="z-string">&quot;Feel free to be creative: (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧&quot;</span></span></code></pre><h3 id="templates">Templates</h3> <p>Template strings are allowed, and MUST follow the <a rel="external" href="https://pubs.opengroup.org/onlinepubs/009696799/utilities/printf.html">ANSI C <code>printf</code></a> conventions.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-string">&quot;Satoshi&#39;s true identity is %s&quot;</span></span></code></pre> <p>Text with 2 or more arguments SHOULD use the POSIX parameter field extension.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-string">&quot;Knock knock. Who&#39;s there? %1$s. %1$s who? %2$s!&quot;</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="bytes32-keys"><code>bytes32</code> Keys</h3> <p><code>bytes32</code> is very efficient since it is the EVM's base word size. Given the enormous number of elements (card(A) &gt; 1.1579 × 10⁷⁷), it can embed nearly any practical signal, enum, or state. In cases where an application's key is longer than <code>bytes32</code>, hashing that long key can map that value into the correct width.</p> <p>Designs that use datatypes with small widths than <code>bytes32</code> (such as <code>bytes1</code> in <a href="https://wg-eips.ritovision.com/1066/">ERC-1066</a>) can be directly embedded into the larger width. This is a trivial one-to-one mapping of the smaller set into the larger one.</p> <h3 id="local-vs-globals-and-singletons">Local vs Globals and Singletons</h3> <p>This spec has opted to not <em>force</em> a single global registry, and rather allow any contract and use case deploy their own system. This allows for more flexibility, and does not restrict the community for opting to use singleton <code>LocalizationPreference</code> contracts for common use cases, share <code>Localization</code>s between different proxys, delegate translations between <code>Localization</code>s, and so on.</p> <p>There are many practical uses of agreed upon singletons. For instance, translating codes that aim to be fairly universal and integrated directly into the broader ecosystem (wallets, frameworks, debuggers, and the like) will want to have a single <code>LocalizationPreference</code>.</p> <p>Rather the dispersing several <code>LocalizationPreference</code>s for different use cases and codes, one could imagine a global "registry of registries". While this approach allows for a unified lookups of all translations in all use cases, it is antithetical to the spirit of decentralization and freedom. Such a system also increases the lookup complexity, places an onus on getting the code right the first time (or adding the overhead of an upgradable contract), and need to account for use case conflicts with a "unified" or centralized numbering system. Further, lookups should be lightweight (especially in cases like looking up revert text).</p> <p>For these reasons, this spec chooses the more decentralized, lightweight, free approach, at the cost of on-chain discoverability. A registry could still be compiled, but would be difficult to enforce, and is out of scope of this spec.</p> <h3 id="off-chain-storage">Off Chain Storage</h3> <p>A very viable alternative is to store text off chain, with a pointer to the translations on-chain, and emit or return a <code>bytes32</code> code for another party to do the lookup. It is difficult to guarantee that off-chain resources will be available, and requires coordination from some other system like a web server to do the code-to-text matching. This is also not compatible with <code>revert</code> messages.</p> <h3 id="ascii-vs-utf-8-vs-utf-16">ASCII vs UTF-8 vs UTF-16</h3> <p>UTF-8 is the most widely used encoding at time of writing. It contains a direct embedding of ASCII, while providing characters for most natural languages, emoji, and special characters.</p> <p>Please see the <a rel="external" href="https://utf8everywhere.org/">UTF-8 Everywhere Manifesto</a> for more information.</p> <h3 id="when-no-text-is-found">When No Text is Found</h3> <p>Returning a blank string to the requestor fully defeats the purpose of a localization system. The two options for handling missing text are:</p> <ol> <li>A generic "text not found" message in the preferred language</li> <li>The actual message, in a different language</li> </ol> <h4 id="generic-option">Generic Option</h4> <p>This designed opted to not use generic fallback text. It does not provide any useful information to the user other than to potentially contact the <code>Localization</code> maintainer (if one even exists and updating is even possible).</p> <h4 id="fallback-option">Fallback Option</h4> <p>The design outlined in this proposal is to providing text in a commonly used language (ex. English or Mandarin). First, this is the language that will be routed to if the user has yet to set a preference. Second, there is a good chance that a user may have <em>some</em> proficiency with the language, or at least be able to use an automated translation service.</p> <p>Knowing that the text fell back via <code>textFor</code>s first return field boolean is <em>much</em> simpler than attempting language detection after the fact. This information is useful for certain UI cases. for example where there may be a desire to explain why localization fell back.</p> <h3 id="decentralized-text-crowdsourcing">Decentralized Text Crowdsourcing</h3> <p>In order for Ethereum to gain mass adoption, users must be able to interact with it in the language, phrasing, and level of detail that they are most comfortable with. Rather than imposing a fixed set of translations as in a traditional, centralized application, this EIP provides a way for anyone to create, curate, and use translations. This empowers the crowd to supply culturally and linguistically diverse messaging, leading to broader and more distributed access to information.</p> <h3 id="printf-style-format-strings"><code>printf</code>-style Format Strings</h3> <p>C-style <code>printf</code> templates have been the de facto standard for some time. They have wide compatibility across most languages (either in standard or third-party libraries). This makes it much easier for the consuming program to interpolate strings with low developer overhead.</p> <h4 id="parameter-fields">Parameter Fields</h4> <p>The POSIX parameter field extension is important since languages do not share a common word order. Parameter fields enable the reuse and rearrangement of arguments in different localizations.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>(</span><span class="z-string">&quot;%1$s is an element with the atomic number %2$d!&quot;</span><span>,</span><span class="z-string"> &quot;Mercury&quot;</span><span>,</span><span class="z-constant"> 80</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> =&gt; &quot;Mercury is an element with the atomic number 80!&quot;</span></span></code></pre><h4 id="simplified-localizations">Simplified Localizations</h4> <p>Localization text does not require use of all parameters, and may simply ignore values. This can be useful for not exposing more technical information to users that would otherwise find it confusing.</p> <pre class="giallo z-code"><code data-lang="ruby"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment">!/usr/bin/env ruby</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">sprintf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">%1$s é um elemento</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Mercurio</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-constant"> 80</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> =&gt; &quot;Mercurio é um elemento&quot;</span></span></code></pre><pre class="giallo z-code"><code data-lang="clojure"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#!</span><span class="z-comment">/usr/bin/env clojure</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>(</span><span class="z-entity z-name">format</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Element #%2$s</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Mercury</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant"> 80</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">;</span><span class="z-comment">; =&gt; Element #80</span></span></code></pre><h3 id="interpolation-strategy">Interpolation Strategy</h3> <p>Please note that it is highly advisable to return the template string <em>as is</em>, with arguments as multiple return values or fields in an <code>event</code>, leaving the actual interpolation to be done off chain.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> AtomMessage</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> templateCode</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> atomCode</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> atomicNumber</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#!</span><span class="z-comment">/usr/bin/env node</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">var</span><span class="z-variable z-other"> printf</span><span class="z-keyword"> =</span><span class="z-entity z-name"> require</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">printf</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span> {</span><span class="z-variable"> returnValues</span><span>:</span><span> {</span><span class="z-variable z-other z-constant"> templateCode</span><span>,</span><span class="z-variable z-other z-constant"> atomCode</span><span>,</span><span class="z-variable z-other z-constant"> atomicNumber</span><span> }</span><span> }</span><span class="z-keyword"> =</span><span class="z-variable z-other"> eventResponse</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> template</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> AppText</span><span>.</span><span class="z-entity z-name">textFor</span><span>(</span><span class="z-variable z-other">templateCode</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> =&gt; &quot;%1$s ist ein Element mit der Ordnungszahl %2$d!&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> atomName</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> PeriodicTableText</span><span>.</span><span class="z-entity z-name">textFor</span><span>(</span><span class="z-variable z-other">atomCode</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> =&gt; &quot;Merkur&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name">printf</span><span>(</span><span class="z-variable z-other">template</span><span>,</span><span class="z-variable z-other"> atomName</span><span>,</span><span class="z-constant"> 80</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> =&gt; &quot;Merkur ist ein Element mit der Ordnungszahl 80!&quot;</span></span></code></pre><h3 id="unspecified-behaviour">Unspecified Behaviour</h3> <p>This spec does not specify:</p> <ul> <li>Public or private access to the default <code>Localization</code></li> <li>Who may set text <ul> <li>Deployer</li> <li><code>onlyOwner</code></li> <li>Anyone</li> <li>Whitelisted users</li> <li>and so on</li> </ul> </li> <li>When text is set <ul> <li><code>constructor</code></li> <li>Any time</li> <li>Write to empty slots, but not overwrite existing text</li> <li>and so on</li> </ul> </li> </ul> <p>These are intentionally left open. There are many cases for each of these, and restricting any is fully beyond the scope of this proposal.</p> <h2 id="implementation">Implementation</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.4.25</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Localization</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">bytes32</span><span class="z-keyword"> =&gt;</span><span class="z-support"> string</span><span>)</span><span class="z-storage z-type"> private</span><span> dictionary_</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Currently overwrites anything</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> set</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _code</span><span>,</span><span class="z-support"> string</span><span class="z-variable z-parameter z-function"> _message</span><span>)</span><span class="z-storage z-type"> external</span><span> {</span></span> <span class="giallo-l"><span> dictionary_</span><span>[</span><span>_code</span><span>]</span><span class="z-keyword"> =</span><span> _message</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> textFor</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _code</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _message</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> dictionary_</span><span>[</span><span>_code</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> LocalizationPreference</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span> Localization</span><span>)</span><span class="z-storage z-type"> private</span><span> registry_</span><span>;</span></span> <span class="giallo-l"><span> Localization </span><span class="z-storage z-type">public</span><span> defaultLocalization</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> private</span><span> empty_ </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span class="z-string">&quot;&quot;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> constructor</span><span>(</span><span class="z-storage z-type">Localization</span><span class="z-variable z-parameter z-function"> _defaultLocalization</span><span>)</span><span class="z-storage z-type"> public</span><span> {</span></span> <span class="giallo-l"><span> defaultLocalization </span><span class="z-keyword">=</span><span> _defaultLocalization</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> set</span><span>(</span><span class="z-storage z-type">Localization</span><span class="z-variable z-parameter z-function"> _localization</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> registry_</span><span>[</span><span class="z-variable z-language">tx</span><span>.</span><span>origin</span><span>]</span><span class="z-keyword"> =</span><span> _localization</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> get</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _code</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>,</span><span class="z-support"> string</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> get</span><span>(</span><span>_code</span><span>,</span><span class="z-variable z-language"> tx</span><span>.</span><span>origin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> Primarily for testing</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> get</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _code</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _who</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>,</span><span class="z-support"> string</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-storage z-type"> memory</span><span> text </span><span class="z-keyword">=</span><span class="z-entity z-name"> getLocalizationFor</span><span>(</span><span>_who</span><span>)</span><span>.</span><span class="z-entity z-name">textFor</span><span>(</span><span>_code</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-support">keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>text</span><span>)</span><span>)</span><span class="z-keyword"> !=</span><span> empty_</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-constant">true</span><span>,</span><span> text</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-constant">false</span><span>,</span><span> defaultLocalization</span><span>.</span><span class="z-entity z-name">textFor</span><span>(</span><span>_code</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getLocalizationFor</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _who</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-storage z-type">Localization</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-entity z-name">Localization</span><span>(</span><span>registry_</span><span>[</span><span>_who</span><span>]</span><span>)</span><span class="z-keyword"> ==</span><span class="z-entity z-name"> Localization</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> Localization</span><span>(</span><span>defaultLocalization</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> Localization</span><span>(</span><span>registry_</span><span>[</span><span class="z-variable z-language">tx</span><span>.</span><span>origin</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-09-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jet Limhttps://github.com/Nitro888 https://wg-eips.ritovision.com/1438/ <h2 id="simple-summary">Simple Summary</h2> <p>Contracts are open source based. And most developers use the public contracts at the start of the project to modify or simply include them. This is project-oriented centralized development and I think it is a waste of resources. Therefore, we propose to make dApp or contracts component-ready for use in other services.</p> <h2 id="abstract">Abstract</h2> <p>There have been suggestions for modified tokens based on erc20, but since many tokens have already been built on erc20, it is necessary to increase the utilization of already developed erc20 tokens. Therefore, we propose a universal wallet that can use erc20 tokens universally. We also propose a component dApp that allows you to create and save your avatar (&amp; social badge system), and use it immediately in other services. All of the dApps suggested in this document are based on decentralized development and use that anyone can create and participate in.</p> <h2 id="motivation">Motivation</h2> <p>While many projects are under development in an open source way, they are simply adding and deploy with open sources to their projects. This means that you are developing a centralized service that uses your own dApp-generated information on your own. In order to improve the block chain ecosystem, all resources created by dApp and placed in the public block chain must be reusable in another dApp. This means that you can enhance your service by exchanging the generated information with other dApp. Likewise, ERC20 Tokens require Universal Wallet standards to be easy to use for direct transactions.</p> <h3 id="seeds-for-improvement-of-the-blockchain-ecosystem">Seeds for improvement of the blockchain ecosystem.</h3> <ul> <li>Synergy - With other dApps and resources.</li> <li>Enhanced interface - For ERC20 tokens.</li> <li>Easy &amp; Decentralized - Everyone should be able to add to their services easily, without censorship.</li> </ul> <h4 id="the-following-avatar-store-badge-system-and-universal-wallet-are-kind-of-examples-about-component-dapp">The following avatar store, badge system, and universal wallet are kind of examples about component dApp.</h4> <p><img src="https://wg-eips.ritovision.com/1438/./assets/intro.png" alt="intro" /></p> <h2 id="specification">Specification</h2> <h3 id="1-avatar">1. Avatar</h3> <h4 id="1-1-avatar-shop">1.1. Avatar Shop</h4> <ul> <li>The avatar store is created after ERC20 currency is set.</li> <li>You can customize asset category &amp; viewer script.</li> </ul> <h4 id="1-2-upload-asset-user-data">1.2. Upload asset &amp; user data</h4> <p>The avatar's information &amp; assets are stored in the event log part of the block chain.</p> <ul> <li>Assets are SVG format. (compressed with gzip)</li> <li>avatar information data is json (compressed with msgpack)</li> </ul> <p><img src="https://wg-eips.ritovision.com/1438/./assets/avatar.png" alt="avatar" /> ** The avatar assets from <a rel="external" href="https://github.com/fangpenlin/avataaars">Avataaars</a> developed by <a rel="external" href="https://twitter.com/fangpenlin">Fang-Pen Lin</a>, the original avatar is designed by <a rel="external" href="https://twitter.com/pablostanley">Pablo Stanley</a>.</p> <h3 id="2-universal-wallet">2. Universal Wallet</h3> <p><img src="https://wg-eips.ritovision.com/1438/./assets/wallet.png" alt="wallet" /></p> <h4 id="2-1-erc20-interface">2.1. ERC20 interface</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> ERC20Interface</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> tokenOwner</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span class="z-variable"> balance</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> tokenOwner</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> spender</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span class="z-variable"> remaining</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokens</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> spender</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokens</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> from</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokens</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> from</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> tokenOwner</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> spender</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="2-2-fixed-erc20-contract-for-receive-approval-and-execute-function-in-one-call">2.2. Fixed ERC20 contract for receive approval and execute function in one call</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approveAndCall</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> spender</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokens</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> allowed</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span>[</span><span class="z-variable z-other">spender</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> tokens</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> spender</span><span>,</span><span class="z-variable z-other"> tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> ApproveAndCallFallBack</span><span>(</span><span class="z-variable z-other">spender</span><span>)</span><span>.</span><span class="z-entity z-name">receiveApproval</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> tokens</span><span>,</span><span class="z-variable z-language"> this</span><span>,</span><span class="z-variable z-other"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="2-3-and-approveandcallfallback-contract-for-fixed-erc20">2.3. And ApproveAndCallFallBack contract for Fixed ERC20.</h4> <p>However, many ERC20 tokens are not prepared.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> ApproveAndCallFallBack</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> receiveApproval</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> from</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> tokens</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> token</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> data</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="2-4-universal-wallet">2.4. Universal Wallet</h4> <p>We propose a Universal Wallet to solve this problem.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> UniversalWallet</span><span class="z-variable z-other"> is</span><span class="z-variable z-other"> _Base</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> constructor</span><span>(</span><span class="z-variable z-other">bytes</span><span class="z-variable z-other"> _msgPack</span><span>)</span><span class="z-entity z-name"> _Base</span><span>(</span><span class="z-variable z-other">_msgPack</span><span>)</span><span class="z-variable z-other"> public</span><span> {</span><span>}</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span> (</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span> {</span><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">-------------------------------------------------------</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> erc20 interface</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">-------------------------------------------------------</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span class="z-variable"> balance</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>.</span><span class="z-variable z-other">balance</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _to</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> _tokens</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">_tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> _to</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span class="z-variable z-other">_tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> else</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span class="z-variable z-other">_to</span><span>,</span><span class="z-variable z-other">_tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _spender</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> _tokens</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword"> !=</span><span class="z-entity z-name"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span class="z-variable z-other">_spender</span><span>,</span><span class="z-variable z-other">_tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">-------------------------------------------------------</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> pay interface</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">-------------------------------------------------------</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pay</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _store</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> _tokens</span><span>,</span><span class="z-variable"> uint256</span><span>[</span><span>]</span><span class="z-variable"> _options</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> erc20</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _ApproveAndCallFallBack</span><span>(</span><span class="z-variable z-other">_store</span><span>)</span><span>.</span><span class="z-entity z-name">erc20</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> spender</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _ApproveAndCallFallBack</span><span>(</span><span class="z-variable z-other">_store</span><span>)</span><span>.</span><span class="z-entity z-name">spender</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">erc20</span><span class="z-keyword"> ==</span><span class="z-entity z-name"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable z-other">erc20</span><span>,</span><span class="z-variable z-other">spender</span><span>,</span><span class="z-variable z-other">_tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _ApproveAndCallFallBack</span><span>(</span><span class="z-variable z-other">_store</span><span>)</span><span>.</span><span class="z-entity z-name">receiveApproval</span><span>(</span><span class="z-variable z-other">_options</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _ERC20Interface</span><span>(</span><span class="z-variable z-other">erc20</span><span>)</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span class="z-variable z-other">spender</span><span>,</span><span class="z-variable z-other">_tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _ApproveAndCallFallBack</span><span>(</span><span class="z-variable z-other">_store</span><span>)</span><span>.</span><span class="z-entity z-name">receiveApproval</span><span>(</span><span class="z-variable z-other">_options</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pay</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _store</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> _tokens</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> _msgPack</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> erc20</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _ApproveAndCallFallBack</span><span>(</span><span class="z-variable z-other">_store</span><span>)</span><span>.</span><span class="z-entity z-name">erc20</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> spender</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _ApproveAndCallFallBack</span><span>(</span><span class="z-variable z-other">_store</span><span>)</span><span>.</span><span class="z-entity z-name">spender</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">erc20</span><span class="z-keyword"> ==</span><span class="z-entity z-name"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable z-other">erc20</span><span>,</span><span class="z-variable z-other">spender</span><span>,</span><span class="z-variable z-other">_tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _ApproveAndCallFallBack</span><span>(</span><span class="z-variable z-other">_store</span><span>)</span><span>.</span><span class="z-entity z-name">receiveApproval</span><span>(</span><span class="z-variable z-other">_msgPack</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _ERC20Interface</span><span>(</span><span class="z-variable z-other">erc20</span><span>)</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span class="z-variable z-other">spender</span><span>,</span><span class="z-variable z-other">_tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _ApproveAndCallFallBack</span><span>(</span><span class="z-variable z-other">_store</span><span>)</span><span>.</span><span class="z-entity z-name">receiveApproval</span><span>(</span><span class="z-variable z-other">_msgPack</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="test-cases">Test Cases</h2> <ul> <li>https://www.nitro888.com</li> <li>https://github.com/Nitro888/nitro888.github.io</li> <li>https://github.com/Nitro888/dApp-Alliance</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-09-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Gerhard Wagnerhttps://github.com/thec00n https://wg-eips.ritovision.com/1470/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP proposes a classification scheme for security weaknesses in Ethereum smart contracts.</p> <h2 id="abstract">Abstract</h2> <p>The SWC is a smart contract specific software weakness classification scheme for developers, tool vendors and security practitioners. The SWC is loosely aligned to the terminologies and structure used in the <a rel="external" href="https://cwe.mitre.org">Common Weakness Enumeration - CWE</a> scheme while overlaying a wide range of weakness variants that are specific to smart contracts.</p> <p>The goals of the SWC scheme are as follows:</p> <ul> <li>Provide a straightforward way to classify weaknesses in smart contract systems.</li> <li>Provide a straightforward way to identify the weakness(es) that lead to a vulnerability in a smart contract system.</li> <li>Define a common language for describing weaknesses in smart contract systems' architecture, design and code.</li> <li>Train and increase the performance of smart contract security analysis tools.</li> </ul> <h2 id="motivation">Motivation</h2> <p>In the software security industry, it is a widely accepted practice to use a common terminology and to classify security related bugs and errors with a standardized scheme. While this has not stopped vulnerabilities from appearing in software, it has helped communities focusing on web applications, network protocols, IOT devices and various other fields to educate users and developers to understand the nature of security related issues in their software. It has also allowed the security community to quickly understand vulnerabilities that occur in production systems to perform root cause analysis or triage findings from various security analysis sources. In recent years various organizations and companies also published vulnerability data to find the most widespread security issues based on collected vulnerability data. Two examples that are widely used and referred to are the <a rel="external" href="https://www.sans.org/top25-software-errors">SANS TOP 25 Most Dangerous Software Errors</a> and the <a rel="external" href="https://www.owasp.org/index.php/Top_10-2017_Top_10">OWASP TOP 10</a>. None of those publications would have been possible without a common classification scheme.</p> <p>At present no such weakness classification scheme exists for weaknesses specific to Ethereum Smart Contracts. Common language and awareness of security weaknesses is mostly derived from academic papers, best practice guides and published articles. Findings from audit reports and security tool analysis add to the wide range of terminologies that is used to describe the discovered weaknesses. It is often time consuming to understand the technical root cause and the risk associated to findings from different sources even for security experts.</p> <h2 id="rationale">Rationale</h2> <p>While recognizing the current gap, the SWC does not aim to reinvent the wheel in regards to classification of security weaknesses. It rather proposes to build on top of what has worked well in other parts of the software security community - specifically the Common Weakness Enumeration (CWE), a list of software vulnerability types that stands out in terms of adoption and breadth of coverage. While CWE does not describe any weaknesses specific to smart contracts, it does describe related weaknesses at higher abstraction layers. This EIP proposes to create smart contract specific variants while linking back to the larger spectrum of software errors and mistakes listed in the CWE that different platforms and technologies have in common.</p> <h2 id="specification">Specification</h2> <p>Before discussing the SWC specification it is important to describe the terminology used:</p> <ul> <li>Weakness: A software error or mistake that in the right conditions can by itself or coupled with other weaknesses lead to a vulnerability.</li> <li>Vulnerability: A weakness or multiple weaknesses which directly or indirectly lead to an undesirable state in a smart contract system.</li> <li>Variant: A specific weakness that is described in a very low detail specific to Ethereum smart contracts. Each variant is assigned a unique SWC ID.</li> <li>Relationships: CWE has a wide range of <em>Base</em> and <em>Class</em> types that group weaknesses on higher abstraction layers. The CWE uses <em>Relationships</em> to link SWC smart contract weakness variants to existing <em>Base</em> or <em>Class</em> CWE types. <em>Relationships</em> are used to provide context on how SWCs are linked to the wider group of software security weaknesses and to be able to generate useful visualisations and insights through issue data sets. In its current revision it is proposed to link a SWC to its closest parent in the CWE.</li> <li>SWC ID: A numeric identifier linked to a variant (e.g. SWC-101).</li> <li>Test Case: A test case constitutes a micro-sample or real-world smart contract that demonstrates concrete instances of one or multiple SWC variants. Test cases serve as the basis for meaningful weakness classification and are useful to security analysis tool developers.</li> </ul> <p>The SWC in its most basic form links a numeric identifier to a weakness variant. For example the identifier <em>SWC-101</em> is linked to the <em>Integer Overflow and Underflow</em> variant. While a list with the weakness title and a unique id is useful by itself, it would also be ambiguous without further details. Therefore the SWC recommends to add a definition and test cases to any weakness variant.</p> <p><strong>SWC definition</strong></p> <p>A SWC definition is formatted in markdown to allow good readability and tools to process them easily. It consists of the following attributes.</p> <ul> <li>Title: A name for the weakness that points to the technical root cause.</li> <li>Relationships: Links a CWE <em>Base</em> or <em>Class</em> type to its CWE variant. The <em>Integer Overflow and Underflow</em> variant for example is linked to <a rel="external" href="https://cwe.mitre.org/data/definitions/682.html">CWE-682 - Incorrect Calculation</a>.</li> <li>Description: Describes the nature and potential impact of the weakness on the contract system.</li> <li>Remediation: Describes ways on how to fix the weakness.</li> <li>References: Links to external references that contain relevant additional information on the weakness.</li> </ul> <p><strong>Test cases</strong></p> <p>Test cases include crafted as well as real-world samples of vulnerable smart contracts. A single test case consists of three components:</p> <ol> <li>Source code of a smart contract sample; e.g. Solidity, Vyper, etc.</li> <li>Compiled asset from an EVM compiler in machine readable format; e.g. JSON or ethPM.</li> <li>Test result configuration that describes which and how many instances of a weakness variant can be found in a given sample. The YAML schema for the proposed test case configuration is listed below.</li> </ol> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span class="z-entity z-name z-tag">t</span><span class="z-entity z-name z-tag">itle</span><span>:</span><span class="z-string"> S</span><span class="z-string">WC config</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag">t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> o</span><span class="z-string">bject</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag">r</span><span class="z-entity z-name z-tag">equired</span><span>:</span></span> <span class="giallo-l"><span>-</span><span class="z-string"> d</span><span class="z-string">escription</span></span> <span class="giallo-l"><span>-</span><span class="z-string"> i</span><span class="z-string">ssues</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag">p</span><span class="z-entity z-name z-tag">roperties</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> d</span><span class="z-entity z-name z-tag">escription</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> s</span><span class="z-string">tring</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">ssues</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">itle</span><span>:</span><span class="z-string"> I</span><span class="z-string">ssues</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">rray</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">tems</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">itle</span><span>:</span><span class="z-string"> I</span><span class="z-string">ssue</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> o</span><span class="z-string">bject</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> r</span><span class="z-entity z-name z-tag">equired</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-string"> i</span><span class="z-string">d</span></span> <span class="giallo-l"><span> -</span><span class="z-string"> c</span><span class="z-string">ount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> p</span><span class="z-entity z-name z-tag">roperties</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">d</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> s</span><span class="z-string">tring</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> c</span><span class="z-entity z-name z-tag">ount</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> n</span><span class="z-string">umber</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> l</span><span class="z-entity z-name z-tag">ocations</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">tems</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> b</span><span class="z-entity z-name z-tag">ytecode_offsets</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> o</span><span class="z-string">bject</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> l</span><span class="z-entity z-name z-tag">ine_numbers</span><span>:</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> o</span><span class="z-string">bject</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>The Smart Contract Weakness Classification registry located in this <a rel="external" href="https://github.com/SmartContractSecurity/SWC-registry">GitHub repository</a> uses the SWC scheme proposed in this EIP. A GitHub Pages rendered version is also available <a rel="external" href="https://smartcontractsecurity.github.io/SWC-registry/">here</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-09-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chaitanya Pottihttps://github.com/chaitanyapotti Partha Bhattacharyahttps://github.com/pb25193 https://wg-eips.ritovision.com/1417/ <h2 id="note-to-readers">Note to Readers</h2> <ol> <li>We have created a couple of implementations of polls for varied use cases. Please refer to them <a rel="external" href="https://github.com/chaitanyapotti/Voting">here</a></li> </ol> <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for Polls to be used with EIP-1261 (MVT).</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for polls to be used with MVTs (refer <a href="https://wg-eips.ritovision.com/1261/">EIP-1261</a>). The standard provides basic functionality to vote, unvote, tally votes, get voter turnout, and a lot more. The poll standard attempts to modularize blockchain voting by breaking down a poll into 4 crucial building blocks: voterbase qualification, vote weight calculation, vote consequences, and vote tallying. By creating a common interface for polls that have different kinds of building blocks, the poll standard makes it possible to make interactive front end applications which can seamlessly get data from a poll contract in order to bring transparency into consensus and decision making on the blockchain.</p> <p>We considered the usage of polls with MVTs because MVTs serve as a permissioning mechanism. The manual permissioning of polls allows for vote weightage functions to take up several shapes and forms. Hence the voterbase function applies several logical checks on the vote sender to confirm that they are member(see EIP 1261) of a certain entity or combination of entities. For the specification of the nature of voting, we define the vote weight function. The vote weight function decides how much of vote share each voter will receive and this can be based on several criteria, some of which are listed below in this article. There are certain kinds of polls that enforce certain consequences on the voter, for example a poll may require a voter to lock in a certain amount of tokens, or require the voter to pay a small fee. These on-chain consequences can be coded into the consequence module of the poll standard. Finally, the last module is where the votes are added. A ballot for each candidate is updated whenever relevant, depending on the vote value, and the corresponding NoV count(number of voters). This module is common for most polls, and is the most straightforward. Polls may be time bound, ie. having a finish time, after which no votes are recorded, or be unbound, such that there is no finish time. The following are some examples of specific polls which leverage the flexibility of the poll standard, and it is possible to come up with several others:</p> <ul> <li>Plurality Voting: The simplest form of voting is when you want all eligible voters to have one vote per person. This is the simplest to code, as the vote weight is 1, and there is no vote consequence. The only relevant module here is the voterbase, which can be categorized by one or more MVT contracts.</li> <li>Token proportional voting: This kind of a poll is actually possible without the use of a voterbase function, because the vote weight function having token proportionality automatically rules out addresses which don't hold the appropriate ERC - 20/ ERC - 777 token. However the voterbase function may be leveraged to further permission the system and give voting rights only to a fixed subset of token holders.</li> <li>Capped Token Proportional Voting: This is a modified version of the previous example, where each voter is given proportional vote share only until a certain limit of token ownership. After exceeding that limit, holding more coins does not add more vote share. This format leverages the voterbase module effectively, disallowing people from spreading their coins across multiple addresses by allowing the admin to control which addresses can vote.</li> <li>Delegated Voting: Certain polls may allow voters to delegate their votes to other voters. This is known as delegated voting or liquid democracy. For such a poll, a complicated vote weight function is needed, and a data structure concerning the voterbase is also required. A consequence of voting here would be that a user cannot delegate, and a consequence of delegating is that a user cannot vote. Sample implementation of polls contains an example of this vote scheme.</li> <li>Karma Based Voting: A certain form of poll may be based on weightage from digital respect. This digital respect would be like a simple upvote from one member of voterbase to another. A mapping of mappings along with an appropriate vote weight function can serve this purpose. Sample implementation has an example.</li> <li>Quadratic voting: A system where each vote is associated with a fee, and the fee is proportional to the square of the vote weight that the voter wants. This can be designed by applying a vote weight based on the transaction message, and then charging a fee in the vote consequence module.</li> </ul> <p>The poll standard is intended to be a smart contract standard that makes poll deployment flexible, transparent and accessible.</p> <h2 id="motivation">Motivation</h2> <p>A standard interface allows any user or applications to work with any Poll contract on Ethereum. We provide for simple ERC-1417 smart contracts. Additional applications are discussed below.</p> <p>This standard is inspired by the lack of governance tools in the blockchain space. Whenever there is a consensus collection exercise, someone goes ahead and deploys some kind of poll, and there is no standard software for accessing the data on the poll. For an end user who is not a developer, this is a real problem. The poll, which might be fully transparent, appears to be completely opaque to a common user who does not understand blockchain. In order for developers to build applications for interacting with and accessing poll data, and for poll deployers to have ready application level support, there must be a standardization of poll interfaces.</p> <p>This realization happened while conducting market research on DAICOs. The first ever DAICO, Abyss, had far from optimal user experience, and abysmal transparency. Since then, we have been working on a poll standard. During the process, we came across EIP 1202, the voting standard, and found that the discussion there had already diverged from our thoughts to an extent that it made sense to publish a separate proposal altogether. Some of the benefits brought by the poll standard - EIP 1417 aims to offer some additional benefits.</p> <ol> <li> <p>Modularization: EIP 1417 modularizes the code present in the poll standard into 4 major building blocks based on functionality. These are: voterbase logic, vote weight calculation, vote consequence processing, and tallying module. This makes it easy for developers to change parts of a poll without disrupting other parts, and also helps people understand better, code written in the same format by other people.</p> </li> <li> <p>Permissioning: Permissioning is an important aspect of polls, and is missing in most poll proposals so far, on the blockchain. For some reason, most blockchain based polls seem to consider token holding as the only way to permission a poll. However this hampers flexibility, and hence our poll standard is leveraging EIP 1261 in order to clear the permissioning hurdle. Not only does it allow for more creative poll structures in terms of vote weightage, but even improves the flexibility in permissioning by allowing developers to combine several entities and read attributes from entities.</p> </li> <li> <p>Flexibility: The vote weight module of the poll standard can be used effectively to design various kinds of poll contracts which function differently and are suited to different environments. Some examples are quadratic voting, karma voting, delegated voting, token based voting, and one person one vote systems. These schemes are possible due to the separation of voterbase creation and vote weight calculation.</p> </li> <li> <p>NoV Counts: Several weighted polls have struggled to provide proper transparency because they only show the final result without enough granularity. This is because they do not store the number of voters that have voted for each proposal, and only store the total accrued vote for each option. EIP 1417 solves this by additionally recording number of voters(NoV) in each proposal. This NoV count is redundant in the case of one person one vote, but elsewhere, it is helpful in figuring out concentration of power. This ensures that malicious parties can be traced to a larger extent.</p> </li> <li> <p>Event Logging: The poll standard logs an event during a successful vote, unsuccessful vote, and a successful unvote. This is being done so that in the event of a malicious admin removing real members or adding fake members, communities can build tools in order to perform advanced audits and simulate results in the absence of the malicious attack. Such advanced features are completely absent in most polls, and hence, it is hard to investigate such polls.</p> </li> <li> <p>Pollscan.io: The Electus foundation is working on a web based application for accessing and interacting with poll data on the blockchain, it will be deployed on the domain name www.pollscan.io in the coming months.</p> </li> </ol> <p>All that being said, we are very excited to share our proposal with the community and open up to suggestions in this space.</p> <h3 id="benefits">Benefits</h3> <ol> <li>Building applications (pollscan.io) on top of a standardized voting interface enables transparency and encourage more DAO/DAICO's to act responsibly in terms of governance</li> <li>Create Action contracts which take actions programmatically based on the result of a poll</li> <li>Allow the compatibility with token standard such as <a href="https://wg-eips.ritovision.com/20/">ERC-20</a> or (./00777.md)) and membership standard such as <a href="https://wg-eips.ritovision.com/1261/">EIP-1261</a></li> <li>Flexibility allows for various voting schemes including but not limited to modern schemes such as PLCR Voting</li> </ol> <h3 id="use-cases">Use-cases:</h3> <p>Polls are useful in any context of collective decision making, which include but aren't limited to:</p> <ol> <li>Governing public resources, like ponds, playgrounds, streets etc</li> <li>Maintaining fiscal policy in a transparent consensus driven manner</li> <li>Governing crowdfunded projects - refer DAICO, Vitalik Buterin</li> <li>Implementation of Futarchy</li> <li>Decision making in political parties, and municipal corporations</li> <li>Governing expenditure of a cryptocurrency community</li> </ol> <h2 id="specification">Specification</h2> <p>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> <p><strong>Every ERC-1417 compliant contract must implement the <code>ERC1417</code> and <code>ERC165</code> interfaces</strong> (subject to "caveats" below):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-1417 Poll Standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See https://github.com/ethereum/EIPs/blob/master/EIPS/./01417.md</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x4fad898b.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IPoll</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a person tries to vote without permissions. Useful for auditing purposes.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> E.g.: To prevent an admin to revoke permissions; calculate the result had they not been removed.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> User who tried to vote</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> the index of the proposal he voted to</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> voteWeight</span><span class="z-comment"> the weight of his vote</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> TriedToVote</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">uint8</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> voteWeight</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a person votes successfully</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> User who successfully voted</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> the index of the proposal he voted to</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> voteWeight</span><span class="z-comment"> the weight of his vote</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> CastVote</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">uint8</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> voteWeight</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a person revokes his vote</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> User who successfully unvoted</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> the index of the proposal he unvoted</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> voteWeight</span><span class="z-comment"> the weight of his vote</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RevokedVote</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">uint8</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> voteWeight</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Handles the vote logic</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> updates the appropriate data structures regarding the vote.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> stores the proposalId against the user to allow for unvote</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _proposalId</span><span class="z-comment"> the index of the proposal in the proposals array</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> vote</span><span>(</span><span class="z-support">uint8</span><span class="z-variable z-parameter z-function"> _proposalId</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Handles the unvote logic</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> updates the appropriate data structures regarding the unvote</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeVote</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the proposal names</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> limit the proposal count to 32 (for practical reasons), loop and generate the proposal list</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> list of names of proposals</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getProposals</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>[</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> returns a boolean specifying whether the user can vote</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> implement logic to enable checks to determine whether the user can vote</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> if using eip-1261, use protocol addresses and interface (IERC1261) to enable checking with attributes</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> the person who can vote/not</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> a</span><span class="z-comment"> boolean as to whether the user can vote</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canVote</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the vote weight of the proposalId</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> returns the current cumulative vote weight of a proposal</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _proposalId</span><span class="z-comment"> the index of the proposal in the proposals array</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> cumulative vote weight of the specified proposal</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getVoteTally</span><span>(</span><span class="z-support">uint</span><span class="z-variable z-parameter z-function"> _proposalId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the no. of voters who voted for the proposal</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> use a struct to keep a track of voteWeights and voterCount</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _proposalId</span><span class="z-comment"> the index of the proposal in the proposals array</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> voter count of the people who voted for the specified proposal</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getVoterCount</span><span>(</span><span class="z-support">uint</span><span class="z-variable z-parameter z-function"> _proposalId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> calculates the vote weight associated with the person `_to`</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> use appropriate logic to determine the vote weight of the individual</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> For sample implementations, refer to end of the eip</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> the person whose vote weight is being calculated</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> vote weight of the individual</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> calculateVoteWeight</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the leading proposal at the current time</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> calculate the leading proposal at the current time</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> For practical reasons, limit proposal count to 32.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> index of the proposal which is leading</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> winningProposal</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint8</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the name of the poll e.g.: &quot;Admin Election for Autumn 2018&quot;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Set the name in the constructor of the poll</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> name of the poll</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getName</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the type of the Poll e.g.: Token (XYZ) weighted poll</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Set the poll type in the constructor of the poll</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> type of the poll</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getPollType</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the logic to be used in a poll&#39;s `canVote` function</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> e.g.: &quot;XYZ Token | US &amp; China(attributes in erc-1261) | Developers(attributes in erc-1261)&quot;</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Set the Voterbase logic in the constructor of the poll</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> voterbase logic</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getVoterBaseLogic</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the start time for the poll</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Set the start time in the constructor of the poll as Unix Standard Time</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> start</span><span class="z-comment"> time as Unix Standard Time</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getStartTime</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the end time for the poll</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Set the end time in the constructor of the poll as Unix Time or specify duration in constructor</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> end</span><span class="z-comment"> time as Unix Standard Time</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getEndTime</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> returns the list of entity addresses (eip-1261) used for perimissioning purposes.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> addresses list can be used along with IERC1261 interface to define the logic inside `canVote()` function</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> list of addresses of entities</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getProtocolAddresses</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the vote weight against all proposals</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> limit the proposal count to 32 (for practical reasons), loop and generate the vote tally list</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> list of vote weights against all proposals</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getVoteTallies</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>[</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> gets the no. of people who voted against all proposals</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> limit the proposal count to 32 (for practical reasons), loop and generate the vote count list</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> the</span><span class="z-comment"> list of voter count against all proposals</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getVoterCounts</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>[</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> For single proposal polls, returns the total voterbase count.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> For multi proposal polls, returns the total vote weight against all proposals</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> this is used to calculate the percentages for each proposal</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> limit the proposal count to 32 (for practical reasons), loop and generate the voter base denominator</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> an</span><span class="z-comment"> integer which specifies the above mentioned amount</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getVoterBaseDenominator</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="caveats">Caveats</h3> <p>The 0.4.24 Solidity interface grammar is not expressive enough to document the ERC-1417 standard. A contract which complies with ERC-1417 MUST also abide by the following:</p> <ul> <li>Solidity issue #3412: The above interfaces include explicit mutability guarantees for each function. Mutability guarantees are, in order weak to strong: <code>payable</code>, implicit nonpayable, <code>view</code>, and <code>pure</code>. Your implementation MUST meet the mutability guarantee in this interface and you MAY meet a stronger guarantee. For example, a <code>payable</code> function in this interface may be implemented as nonpayble (no state mutability specified) in your contract. We expect a later Solidity release will allow your stricter contract to inherit from this interface, but a workaround for version 0.4.24 is that you can edit this interface to add stricter mutability before inheriting from your contract.</li> <li>Solidity issue #2330: If a function is shown in this specification as <code>external</code> then a contract will be compliant if it uses <code>public</code> visibility. As a workaround for version 0.4.24, you can edit this interface to switch to <code>public</code> before inheriting from your contract.</li> </ul> <p><em>If a newer version of Solidity allows the caveats to be expressed in code, then this EIP MAY be updated and the caveats removed, such will be equivalent to the original specification.</em></p> <h2 id="rationale">Rationale</h2> <p>As the poll standard is built with the intention of creating a system that allows for more transparency and accessibility of governance data, the design choices in the poll standard are driven by this motivator. In this section we go over some of the major design choices, and why these choices were made:</p> <ol> <li> <p>Event logging: The logic behind maintaining event logs in the cases of:</p> <ul> <li>Cast Vote</li> <li>Unvote</li> <li>Failed Vote is to ensure that in the event of a manipulated voterbase, simple off chain checks can be performed to audit the integrity of the poll result.</li> </ul> </li> <li> <p>No poll finish trigger: There was a consideration of adding functions in the poll which execute after completion of the poll to carry out some pre-decided logic. However this was deemed to be unnecessary - because such an action can be deployed in a separate contract which simply reads the result of a given poll, and against the spirit of modularity, because no actions can be created after the poll has been deployed. Also, such functions would not be able to combine the results of polls, and definitely would not fit into polls that do not have an end time.</p> </li> <li> <p>Allow for unbound polls: The poll standard, unlike other voting standard proposals, does not force polls to have an end time. This becomes relevant in some cases where the purpose of a poll is to have a live register of ongoing consensus. Some other use cases come into picture when you want to deploy a set of action contracts which read from the poll, and want to be able to execute the action contract whenever a poll reaches a certain threshold, rather than waiting for the end of the poll.</p> </li> <li> <p>Modularization: There have been opinions in the Ethereum community that there cannot exist a voting standard, because voting contracts can be of various types, and have several shapes and forms. However we disagree, and make the case that modularization is the solution. While different polls may need different logic, they all need consistent end points. All polls need to give out results along with headcounts, all polls should have event logs, all polls should be examinable with frontend tools, and so on. The poll standard is not a statement saying “all polls should be token based” or any such specific system. However the poll standard is a statement saying that all polls should have a common access and modification protocol - this will enable more apps to include governance without having to go through the trouble of making customers start using command line.</p> </li> </ol> <p>Having explained our rationale, we are looking forward to hearing from the community some thoughts on how this can be made more useful or powerful.</p> <p><strong>Gas and Complexity</strong> (regarding the enumeration for proposal count)</p> <p>This specification contemplates implementations that contain a sample of 32 proposals (max up to blockgaslimit). If your application is able to grow and needs more than 32 proposals, then avoid using for/while loops in your code. These indicate your contract may be unable to scale and gas costs will rise over time without bound</p> <p><strong>Privacy</strong></p> <p>Personal information: The standard does not put any personal information on to the blockchain, so there is no compromise of privacy in that respect.</p> <p><strong>Community Consensus</strong></p> <p>We have been very inclusive in this process and invite anyone with questions or contributions into our discussion. However, this standard is written only to support the identified use cases which are listed herein.</p> <h2 id="test-cases">Test Cases</h2> <p>Voting Standard includes test cases written using Truffle.</p> <h2 id="implementations">Implementations</h2> <p>Voting Standard -- a reference implementation</p> <ul> <li>MIT licensed, so you can freely use it for your projects</li> <li>Includes test cases</li> <li>Also available as a npm package - npm i electusvoting</li> </ul> <h2 id="references">References</h2> <p><strong>Standards</strong></p> <ul> <li><a href="https://wg-eips.ritovision.com/20/">EIP-20: ERC-20 Token Standard (a.k.a. ERC-20)</a></li> <li><a href="https://wg-eips.ritovision.com/165/">EIP-165: Standard Interface Detection</a></li> <li><a href="https://wg-eips.ritovision.com/721/">EIP-721: Non-Fungible Token Standard(a.k.a. ERC-721)</a></li> <li><a href="https://wg-eips.ritovision.com/1261/">ERC-1261 MV Token Standard</a></li> <li><a rel="external" href="https://www.ietf.org/rfc/rfc2119.txt">RFC 2119 Key words for use in RFCs to Indicate Requirement Levels</a></li> </ul> <p><strong>Issues</strong></p> <ol> <li>The Original ERC-1417 Issue. https://github.com/ethereum/eips/issues/1417</li> <li>Solidity Issue #2330 -- Interface Functions are Axternal. https://github.com/ethereum/solidity/issues/2330</li> <li>Solidity Issue #3412 -- Implement Interface: Allow Stricter Mutability. https://github.com/ethereum/solidity/issues/3412</li> <li>Solidity Issue #3419 -- Interfaces Can't Inherit. https://github.com/ethereum/solidity/issues/3419</li> </ol> <p><strong>Discussions</strong></p> <ol> <li>ERC-1417 (announcement of first live discussion). https://github.com/ethereum/eips/issues/1417</li> </ol> <p><strong>Voting Implementations and Other Projects</strong></p> <ul> <li><a rel="external" href="https://github.com/chaitanyapotti/Voting">Voting Implementations</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-09-16T00:00:00+00:00 2026-02-11T14:49:28+00:00 William Entrikenhttps://github.com/fulldecent https://wg-eips.ritovision.com/1418/

At each block, deduct value from every account based on the quantity of storage used by that account.

<h2 id="abstract">Abstract</h2> <p>At each block, deduct an amount of value ("rent") from every account based on the quantity of storage used by that account.</p> <h2 id="motivation">Motivation</h2> <p>Ethereum is a public utility and we are underpricing the long-term costs of storage. Storage cost can be approximately modeled as bytes × time.</p> <h2 id="specification">Specification</h2> <p><strong>Updated transaction type</strong></p> <p>A new transaction type is introduced. Whereas <a href="https://wg-eips.ritovision.com/1559/">EIP-1559</a> introduced warm access for contract state, this new type introduces warm access for contract code.</p> <p><strong>New state variables (per account)</strong></p> <ul> <li><strong>σ[a]_rent</strong> -- an amount of value, in Wei, this is a signed value</li> <li><strong>σ[a]_storageWords</strong> -- number of words in storage</li> </ul> <p><strong>New constants</strong></p> <ul> <li><strong><code>RENT_WORD_COST</code></strong> -- The rent cost, in Wei, paid for each word-block</li> <li><strong><code>RENT_ACCOUNT_COST</code></strong> -- The rent cost, in Wei, paid for each account-block</li> <li><strong><code>FORK_BLOCK</code></strong> – When implementation starts</li> </ul> <p><strong>New opcodes</strong></p> <ul> <li><strong><code>RENTBALANCE(address)</code></strong> -- G_BALANCE -- Similar to <code>BALANCE</code> <ul> <li>This returns the logical <code>σ[a]_rent</code> value which is defined to reduce each block. It is possible for the implementation to calculate this value using the recommended implementation variables, rather than storing and updating <code>σ[a]_rent</code> every block for every account.</li> </ul> </li> <li><strong><code>SENDRENT(address, amount)</code></strong> -- G_BASE -- Convert value to rent and send to account <ol> <li><code>σ[account]_rent</code> += amount</li> <li><code>σ[msg.sender]_balance</code> -= amount</li> </ol> </li> </ul> <p><strong>Updated opcodes</strong></p> <p>A new subroutine, paying for rent, is established as such:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PAYRENT(account)</span></span> <span class="giallo-l"><span> blocks_to_pay = NUMBER - σ[account]_rentLastPaid</span></span> <span class="giallo-l"><span> cost_per_block = RENT_ACCOUNT_COST + RENT_WORD_COST * (⌈∥σ[account]_code∥ / 32⌉ + * σ[a]_storageWords)</span></span> <span class="giallo-l"><span> rent_to_pay = blocks_to_pay * cost_per_block</span></span> <span class="giallo-l"><span> σ[account]_rent -= rent_to_pay</span></span> <span class="giallo-l"><span> if σ[account]_rent &lt; 0</span></span> <span class="giallo-l"><span> σ[account]_value += σ[account]_rent</span></span> <span class="giallo-l"><span> σ[account]_rent = 0</span></span> <span class="giallo-l"><span> end</span></span> <span class="giallo-l"><span> if σ[account]_value &lt; 0</span></span> <span class="giallo-l"><span> σ[account]_rent = σ[account]_value</span></span> <span class="giallo-l"><span> σ[account]_value = 0</span></span> <span class="giallo-l"><span> end</span></span> <span class="giallo-l"><span> σ[account]_rentLastPaid = NUMBER</span></span> <span class="giallo-l"><span> σ[account]_rentEvictBlock = NUMBER + ⌊σ[account]_rent / cost_per_block⌋</span></span> <span class="giallo-l"><span>END PAYRENT</span></span></code></pre> <ul> <li><strong><code>SSTORE(account, key, value)</code></strong> <ul> <li>Perform PAYRENT(account)</li> <li>If <code>account</code> is evicted (i.e. <code>NUMBER</code> &gt; <code>σ[account]_rentEvictBlock</code>) then transaction fails unless using the new transaction type and sufficient proofs are included to validate the old storage root and calculate the new root.</li> <li>Do normal SSTORE operation</li> <li>If the old value was zero for this [account, key] and the new value is non-zero, then <code>σ[account]_storageWords++</code></li> <li>If the old value was non-zero for this [account, key] and the new value is zero, then <code>σ[account]_storageWords--</code>, and if the result is negative then set to zero</li> </ul> </li> <li><strong><code>SLOAD(account, key)</code></strong> <ul> <li>If <code>account</code> is evicted (i.e. <code>NUMBER</code> &gt; <code>σ[account]_rentEvictBlock</code>) then transaction fails unless using the new transaction type and sufficient proofs are included to validate the existing storage root and the existing storage value.</li> <li>Do normal SLOAD operation.</li> </ul> </li> <li><strong><code>CALL (and derivatives)</code></strong> <ul> <li>If the target block is evicted (i.e. <code>NUMBER</code> &gt; <code>σ[account]_rentEvictBlock</code>) then transaction fails unless using the new transaction type and sufficient proof is included to validate the existing code.</li> <li>Do normal CALL operation</li> </ul> </li> <li><strong><code>CREATE</code></strong> <ul> <li>Set σ[account]_rentLastPaid = NUMBER</li> <li>Do normal CREATE operation</li> <li><code>σ[account]_storageWord = 0</code></li> <li>Note: it is possible there is a pre-existing rent balance here</li> </ul> </li> </ul> <p><strong>New built-in contract</strong></p> <ul> <li><code>PAYRENT(address, amount)</code> -- Calls <code>PAYRENT</code> opcode <ul> <li>This is a convenience for humans to send Ether from their accounts and turn it into rent. Note that simple accounts (CODESIZE == 0) cannot call arbitrary opcodes, they can only call CREATE or CALL.</li> <li>The gas cost of PAYRENT will be 10,000 or lower if possible.</li> </ul> </li> </ul> <p><strong>Calculating <code>σ[account]_storageWord</code> for existing accounts</strong></p> <p>DRAFT...</p> <p>It is not an acceptable upgrade if on the fork block it is necessary for only archive nodes to participate which know the full storage amount for each account.</p> <p>An acceptable upgrade will be if the required <code>σ[account]_storageWord</code> can be calculated (or estimated) incrementally based on new transaction activity.</p> <p>DRAFT: I think it is possible to make such an acceptable upgrade using an unbiased estimator</p> <ul> <li>add one bit of storage per <code>SSTORE</code> for legacy accounts on the first access of a given key</li> <li>add log(n) bits for each trie level</li> <li>assume that storage keys are a random variable</li> </ul> <p>To think more about...</p> <p><strong>No changes to current opcode gas costs.</strong></p> <h2 id="rationale">Rationale</h2> <p><strong>No call</strong></p> <p>A contract will not know or react to the receipt of rent. This is okay. Workaround: if a contract really needed to know who provided rent payments then it could create a function in its ABI to attribute these payments. It is already possible to send payments to a contract without attribution by using <code>SELFDESTRUCT</code>. Other blockchains like TRON allow to transfer value to a contract without performing a call.</p> <p><strong>Eviction responsibility / lazy evaluation</strong></p> <p>The specification gives responsibility for eviction to the consensus clients. This is the most predictable behavior because it happens exactly when it should. Also there need not be any incentive mechanism (refund gas, bounty) for outside participants (off-chain) to monitor accounts and request removal.</p> <p>It is possible that an arbitrary number of accounts will be evicted in one block. That doesn't matter. Client implementations do not need to track which accounts are evicted, consensus is achieved just by agreeing on the conditions under which an account would be evicted.</p> <p><strong>No converting rent to value</strong></p> <p>Ether converted to rent cannot be converted back. Anybody that works in accounting and knows about gifts cards should tell you this is a good idea. It makes reasoning about the system much easier.</p> <p><strong>Accounts pay rent</strong></p> <p>Yes, they pay rent. It costs resources to account for their balances so we charge them rent.</p> <p><strong>Why do you need a separate rent account?</strong></p> <p>Because anybody/everybody can contribute to the rent account. If you depend on a contract, you should contribute to its rent.</p> <p>But the contract can spend all of its value.</p> <p>By maintaining a separate rent and value balance, this allows people to contribute to the rent while being confident that this is allowing the contract to stay around.</p> <p>NOTE: cloning. With this EIP, it may become feasible to allow storage cloning. Yes really. Because the new clone will be paying rent. See other EIP, I think made by Augur team.</p> <h3 id="economics-constants">Economics &amp; constants</h3> <p>An <code>SSTORE</code> executed in 2015 cost 20,000 gas and has survived about 6 million blocks. The gas price has been around 1 ~ 50 Gwei. So basically 4,000 Wei per block per word so far. Maybe storing an account is 10 times more intensive than storing a word. But actually <code>G_transaction</code> is 21,000 and <code>G_sstore</code> is 20,000 so these are similar and they can both create new accounts / words.</p> <p>How about:</p> <ul> <li><code>RENT_WORD_COST</code> -- 4,000 Wei</li> <li><code>RENT_ACCOUNT_COST</code> -- 4,000 Wei</li> <li><code>FORK_BLOCK</code> – when implementation starts</li> </ul> <p>The rent is priced in cold, hard Ether. It is not negotiated by clients, it is not dynamic.</p> <p>A future EIP may change this pricing to be dynamic. For example to notarize a block, notaries may be required to prove they have the current storage dataset (excluding evictions). Additionally, they may also prove they have the dataset plus evictions to earn an additional fee. The relative storage of the evicted accounts, and the other accounts versus the value of the additional fee may be used as a feedback mechanism to set a market price for storage.</p> <p>FYI, there are about 15B words in the Ethereum Mainnet dataset and about 100M total Ether mined. This means if all Ether was spent on storage at current proposed prices it would be 400 terabyte-years of storage. I'm not sure if it is helpful to look at it that way.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>EIP-1559 already introduces a mechanism for nodes to participate without recording the full network state and for clients to warm cache with storage data in their type 2 transactions.</p> <p>Users will need to be educated.</p> <p>Many smart contracts allow anybody to use an arbitrary amount of storage in them. This can limit the usefulness of deploying this proposal on an existing chain.</p> <p><strong>Recommended implementation variables (per account)</strong></p> <ul> <li> <p><strong>σ[a]_rentLastPaid</strong> -- a block number that is set when:</p> <ul> <li>Value is transferred into an account (<code>CREATE</code>, <code>CALL</code>, <code>SELFDESTRUCT</code>)</li> <li>Code is set for an account (<code>CREATE</code>)</li> <li>An account's storage is updated (<code>SSTORE</code>)</li> <li>This begins with a logical value of <code>FORK_BLOCK</code> for all accounts</li> </ul> </li> <li> <p><strong>σ[a]_rentEvictBlock</strong> -- the block number when this account will be evicted</p> </li> </ul> <p><strong>Storage note</strong></p> <p>For every account that is evicted, clients may choose to delete that storage from disk. A future EIP may make an incentive to keep this extra data for a fee. A future EIP may create a mechanism for clients to exchange information about these storage states.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Many smart contracts allow anybody to use an arbitrary amount of storage in them.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via CC0.</p> <!-- ## TODO To discuss: - Can/should an evicted account be allowed to be un-evicted when paying past due rent? --> 2018-09-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Michael Connormichael.connor@uk.ey.com Chaitanya Kondachaitanya.konda@uk.ey.com Duncan Westlandduncan.westland@uk.ey.com https://wg-eips.ritovision.com/1922/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for "Verifier" contracts which verify zk-SNARKs.</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard contract API for the verification of zk-SNARKs ("Zero-Knowledge Succinct Non-Interactive Arguments of Knowledge"), also known as "proofs", "arguments", or "commitments".</p> <p>This standard provides basic functionality to load all necessary parameters for the verification of any zk-SNARK into a verifier contract, so that the proof may ultimately return a <code>true</code> or <code>false</code> response; corresponding to whether it has been verified or not verified.</p> <h2 id="motivation">Motivation</h2> <p>zk-SNARKs are a promising area of interest for the Ethereum community. Key applications of zk-SNARKs include:</p> <ul> <li>Private transactions</li> <li>Private computations</li> <li>Improved transaction scaling through proofs of "bundled" transactions</li> </ul> <p>A standard interface for verifying all zk-SNARKs will allow applications to more easily implement private transactions, private contracts, and scaling solutions; and to extract and interpret the limited information which gets emitted during zk-SNARK verifications.</p> <p>This standard was initially proposed by EY, and was inspired in particular by the requirements of businesses wishing to keep their agreements, transactions, and supply chain activities confidential—all whilst still benefiting from the commonly cited strengths of blockchains and smart contracts.</p> <p>:warning: TODO: Explain the benefits to and perspective of a consumer of information. I.e. the thing that interfaces with the standard verifier.</p> <h2 id="specification">Specification</h2> <p>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> <p>Terminology in this specification is used consistently with libsnark, as provided in that project's README.</p> <ul> <li>Adhering Contract — A Verifier contract which adheres to this specification.</li> <li>Arithmetic circuit: An abstraction of logical statements into addition and multiplication gates.</li> <li>Public Inputs: often denoted as a vector 'x' in zk-SNARKs literature, and denoted <code>inputs</code> in this interface. An arithmetic circuit can be thought of as taking two parameters; the Public Inputs, 'x', and a secret 'witness', 'w'. This interface standardises functions which can load the <code>inputs</code> into an Adhering Contract.</li> <li>Proof: A 'prover' who wants to 'prove' knowledge of some secret witness 'w' (which satisfies an arithmetic circuit), generates a <code>proof</code> from: the circuit's Proving Key; their secret witness 'w'; and its corresponding Public Inputs 'x'. Together, a pair <code>(proof, inputs)</code> of satisfying <code>inputs</code> and their corresponding <code>proof</code> forms a zk-SNARK.</li> <li>Verification Key: A 'trusted setup' calculation creates both a public 'Proving Key' and a public 'Verification Key' from an arithmetic circuit. This interface does not provide a method for loading a Verification Key onto the blockchain. An Adhering Contract SHALL be able to accept arguments of knowledge (<code>(proof, inputs)</code> pairs) for at least one Verification Key. We shall call such Verification Keys 'in-scope' Verification Keys. An Adhering Contract MUST be able to interpret unambiguously a unique <code>verificationKeyId</code> for each of its 'in-scope' Verification Keys.</li> </ul> <p><strong>Every ERC-XXXX compliant verifier contract must implement the <code>ERCXXXX</code> and <code>ERC165</code> interfaces</strong> (subject to "caveats" below):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-keyword">pragma</span><span class="z-entity z-name z-tag"> solidity</span><span class="z-constant"> ^0.5.6</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> EIP-XXXX zk-SNARK Verifier Standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See https://github.com/EYBlockchain/zksnark-verifier-standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0xXXXXXXXX.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> ⚠️ </span><span class="z-keyword">TODO</span><span class="z-comment">: Calculate interface identifier</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> EIPXXXX</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Checks the arguments of Proof, through elliptic curve</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> pairing functions.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST return `true` if Proof passes all checks (i.e. the Proof is</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> valid).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> MUST return `false` if the Proof does not pass all checks (i.e. if the</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Proof is invalid).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> proof</span><span class="z-comment"> A zk-SNARK.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> inputs</span><span class="z-comment"> Public inputs which accompany Proof.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> verificationKeyId</span><span class="z-comment"> A unique identifier (known to this verifier</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> contract) for the Verification Key to which Proof corresponds.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> result</span><span class="z-comment"> The result of the verification calculation. True</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> if Proof is valid; false otherwise.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verify</span><span>(</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> proof</span><span>,</span><span class="z-support"> uint256</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> inputs</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable"> verificationKeyId</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> result</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="interface">Interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Query if a contract implements an interface</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> interfaceID</span><span class="z-comment"> The interface identifier, as specified in ERC-165</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface identification is specified in ERC-165. This function</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> uses less than 30,000 gas.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-comment"> `true` if the contract implements `interfaceID` and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `interfaceID` is not 0xffffffff, `false` otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="taxonomy">Taxonomy</h3> <p>⚠️ TODO: Add a specific reference to libsnark here, explaining the choice of variable names.</p> <p>:warning: TODO: Explain how <em>C</em> may not necessarily be a satisfiable arithmetic circuit of logical statements. As current, this is a limitation to certain kinds of SNARKS. Whereas the source references also mention polynomials, and other applications.</p> <p><em>C</em> — A satisfiable arithmetic circuit abstraction of logical statements.</p> <p><em>lambda​</em> - A random number, generated at the 'setup' phase - commonly referred to as 'toxic waste', because knowledge of <em>lambda​</em> would allow an untrustworthy party to create 'false' proofs which would verify as 'true'. <em>lambda​</em> must be destroyed.</p> <p><em>pk​</em> - The proving key for a particular circuit <em>C​</em>.</p> <p><em>vk</em> - The verification key for a particular circuit <em>C</em>.</p> <p>Both <em>pk​</em> and <em>vk​</em> are generated as a pair by some function <em>G​</em>: <em>(pk, vk) = G(lambda, C)​</em></p> <p>Note: <em>C</em> can be represented unambiguously by either of <em>pk</em> or <em>vk</em>. In zk-SNARK constructions, <em>vk</em> is much smaller in size than <em>pk</em>, so as to enable succinct verification on-chain. Hence, <em>vk</em> is the representative of <em>C</em> that is 'known' to the contract. Therefore, we can identify each circuit uniquely through some <code>verificationKeyId</code>, where <code>verificationKeyId</code> serves as a more succinct mapping to <em>vk</em>.</p> <p><em>w</em> - A 'private witness' string. A private argument to the circuit <em>C</em> known only to the prover, which, when combined with the <code>inputs</code> argument <em>x</em>, comprises an argument of knowledge which satisfies the circuit <em>C</em>.</p> <p><em>x</em> or <code>inputs</code> - A vector of 'Public Inputs'. A public argument to the circuit <em>C</em> which, when combined with the private witness string <em>w</em>, comprises an argument of knowledge which satisfies the circuit <em>C</em>.</p> <p><em>pi</em> or <code>proof</code> - an encoded vector of values which represents the 'prover's' 'argument of knowledge' of values <em>w</em> and <em>x</em> which satisfy the circuit <em>C</em>. <em>pi = P(pk, x, w)</em>.</p> <p>The ultimate purpose of a Verifier contract, as specified in this EIP, is to verify a proof (of the form <em>pi​</em>) through some verification function <em>V​</em>.</p> <p><em>V(vk, x, pi) = 1</em>, if there exists a <em>w</em> s.t. <em>C(x,w)=1</em>. <em>V(vk, x, pi) = 0</em>, otherwise.</p> <p>The <code>verify()</code> function of this specification serves the purpose of <em>V​</em>; returning either <code>true</code> (the proof has been verified to satisfy the arithmetic circuit) or <code>false</code> (the proof has not been verified).</p> <h3 id="functions">Functions</h3> <h4 id="verify"><code>verify</code></h4> <p>The <code>verify</code> function forms the crux this standard. The parameters are intended to be as generic as possible, to allow for verification of any zk-SNARK:</p> <ul> <li> <p><code>proof</code> Specified as <code>uint256[]</code>. <code>uint256</code> is the most appropriate type for elliptic curve operations over a finite field. Indeed, this type is used in the predominant 'Pairing library' implementation of zk-SNARKs by Christian Reitweissner. A one-dimensional dynamic array has been chosen for several reasons:</p> <ul> <li>Dynamic: There are several possible methods for producing a zk-SNARK proof, including PGHR13, G16, GM17, and future methods might be developed in future. Although each method may produce differently sized proof objects, a dynamic array allows for these differing sizes.</li> <li>Array: An array has been chosen over a 'struct' object, because it is currently easier to pass dynamic arrays between functions in Solidity. Any proof 'struct' can be 'flattened' to an array and passed to the <code>verify</code> function. Interpretation of that flattened array is the responsibility of the implemented body of the function. Example implementations demonstrate that this can be achieved.</li> <li>One-dimensional: A one-dimensional array has been chosen over multi-dimensional array, because it is currently easier to work with one-dimensional arrays in Solidity. Any proof can be 'flattened' to a one-dimensional array and passed to the <code>verify</code> function. Interpretation of that flattened array is the responsibility of the implemented body of the Adhering Contract. Example implementations demonstrate that this can be achieved.</li> </ul> </li> <li> <p><code>inputs</code> Specified as <code>uint256[]</code>. <code>uint256</code> is the most appropriate type for elliptic curve operations over a finite field. Indeed, this type is used in the predominant 'Pairing library' implementation of zk-SNARKs by Christian Reitweissner. The number of inputs will vary in size, depending on the number of 'public inputs' of the arithmetic circuit being verified against. In a similar vein to the <code>proof</code> parameter, a one-dimensional dynamic array is general enough to cope with any set of inputs to a zk-SNARK.</p> </li> <li> <p><code>verificationKeyId</code> A verification key (referencing a particular arithmetic circuit) only needs to be stored on-chain once. Any proof (relating to the underlying arithmetic circuit) can then be verified against that verification key. Given this, it would be unnecessary (from a 'gas cost' point of view) to pass a duplicate of the full verification key to the <code>verify</code> function every time a new <code>(proof, inputs)</code> pair is passed in. We do however need to tell the Adhering Verifier Contract which verification key corresponds to the <code>(proof, inputs)</code> pair being passed in. A <code>verificationKeyId</code> serves this purpose - it uniquely represents a verification key as a <code>bytes32</code> id. A method for uniquely assigning a <code>verificationKeyId</code> to a verification key is the responsibility of the implemented body of the Adhering Contract.</p> </li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <ul> <li>At the time this EIP was first proposed, there was one implementation on the Ethereum main net - deployed by <a rel="external" href="https://www.ey.com">EY</a>. This was compiled with Solidity 0.4.24 for compatibility with <a rel="external" href="https://github.com/trufflesuite/truffle">Truffle</a> but otherwise compatible with this standard, which is presented at the latest current version of Solidity.</li> <li>Dr Christian Reitwiessner's excellent <a rel="external" href="https://gist.github.com/chriseth/f9be9d9391efc5beb9704255a8e2989d">example</a> of a Verifier contract and elliptic curve pairing library has been instrumental in the Ethereum community's experimentation and development of zk-SNARK protocols. Many of the naming conventions of this EIP have been kept consistent with his example.</li> <li>Existing zk-SNARK compilers such as <a rel="external" href="https://github.com/Zokrates/ZoKrates">ZoKrates</a>, which produce 'Verifier.sol' contracts, do not currently produce Verifier contracts which adhere to this EIP specification. <ul> <li>:warning: TODO: Provide a converter contract or technique which allows ZoKrates verifier.sol contracts to adhere with this EIP.</li> </ul> </li> </ul> <h2 id="test-cases">Test Cases</h2> <p>Truffle tests of example implementations are included in the test case repository.</p> <p>⚠️ TODO: Reference specific test cases because there are many currently in the repository.</p> <h2 id="implementations">Implementations</h2> <p>Detailed example implementations and Truffle tests of these example implementations are included in this repository.</p> <p>:warning: TODO: Update referenced verifier implementations so that they are ready-to-deploy or reference deployed versions of those implementations. At current, the referenced code specifically states "DO NOT USE THIS IN PRODUCTION".</p> <p>:warning: TODO: Provide reference to an implementation which interrogates a standard verifier contract that implements this standard.</p> <h2 id="references">References</h2> <p>:warning: TODO: Update references and confirm that each reference is cited (parenthetical documentation not necessary) in the text.</p> <p><strong>Standards</strong></p> <ol> <li> <p>ERC-20 Token Standard. ./00020.md</p> </li> <li> <p>ERC-165 Standard Interface Detection. ./00165.md</p> </li> <li> <p>ERC-173 Contract Ownership Standard (DRAFT). ./00173.md</p> </li> <li> <p>ERC-196 Precompiled contracts for addition and scalar multiplication on the elliptic curve alt_bn128. ./00196.md</p> </li> <li> <p>ERC-197 Precompiled contracts for optimal ate pairing check on the elliptic curve alt_bn128. ./00197.md</p> </li> <li> <p>Ethereum Name Service (ENS). https://ens.domains</p> </li> <li> <p>RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. https://www.ietf.org/rfc/rfc2119.txt</p> </li> </ol> <h5 id="educational-material-zk-snarks">Educational material: zk-SNARKs</h5> <ol> <li>Zcash. What are zk-SNARKs? https://z.cash/technology/zksnarks.html</li> <li>Vitalik Buterin. zk-SNARKs: Under the Hood. https://medium.com/@VitalikButerin/zk-snarks-under-the-hood-b33151a013f6</li> <li>Christian Reitweissner. zk-SNARKs in a Nutshell. https://blog.ethereum.org/2016/12/05/zksnarks-in-a-nutshell/</li> <li>Ben-Sasson, Chiesa, Tromer, et. al. Succinct Non-Interactive Zero Knowledge for a von Neumann Architecture. https://eprint.iacr.org/2013/879.pdf</li> </ol> <h5 id="notable-applications-of-zk-snarks">Notable applications of zk-SNARKs</h5> <ol> <li>EY. Implementation of a business agreement through Token Commitment transactions on the Ethereum mainnet. https://github.com/EYBlockchain/ZKPChallenge</li> <li>Zcash. https://z.cash</li> <li>Zcash. How Transactions Between Shielded Addresses Work. https://blog.z.cash/zcash-private-transactions/</li> </ol> <h5 id="notable-projects-relating-to-zk-snarks">Notable projects relating to zk-SNARKs</h5> <ol> <li>libsnark: A C++ Library for zk-SNARKs ("project README)". https://github.com/scipr-lab/libsnark</li> <li>ZoKrates: Scalable Privacy-Preserving Off-Chain Computations. https://www.ise.tu-berlin.de/fileadmin/fg308/publications/2018/2018_eberhardt_ZoKrates.pdf</li> <li>ZoKrates Project Repository. https://github.com/JacobEberhardt/ZoKrates</li> <li>Joseph Stockermans. zkSNARKs: Driver's Ed. https://github.com/jstoxrocky/zksnarks_example</li> <li>Christian Reitweissner - snarktest.solidity. https://gist.github.com/chriseth/f9be9d9391efc5beb9704255a8e2989d</li> </ol> <h5 id="notable-alternatives-to-zk-snarks-areas-of-ongoing-zero-knowledge-proof-research">Notable 'alternatives' to zk-SNARKs - areas of ongoing zero-knowledge proof research</h5> <ol> <li>Vitalik Buterin. STARKs. https://web.archive.org/web/20230425101334/https://vitalik.ca/general/2017/11/09/starks_part_1.html</li> <li>Bu ̈nz, Bootle, Boneh, et. al. Bulletproofs. https://eprint.iacr.org/2017/1066.pdf</li> <li>Range Proofs. https://www.cosic.esat.kuleuven.be/ecrypt/provpriv2012/abstracts/canard.pdf</li> <li>Apple. Secure Enclaves. https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/storing_keys_in_the_secure_enclave</li> <li>Intel Software Guard Extensions. https://software.intel.com/en-us/sgx</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-09-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Weiwu Zhanga@colourful.land James Sangallij.l.sangalli@gmail.com https://wg-eips.ritovision.com/1386/ <h3 id="introduction">Introduction</h3> <p>Very often, we will need to use Attestations like "Alice lives in Australia" on the blockchain; that is issued by a valid issuer off chain for privacy reasons and is revokable inside a smart contract.</p> <p>An issuer can create a smart contract where he revokes multiple attestations in one go by building a bloom filter of all the hashes of the revoked attestations.</p> <p>An issuer can also put the validation method in their smart contract that can be called by other smart contracts who need to validate attestations issued by them. This allows each attestor to update their attestation format separately.</p> <h3 id="purpose">Purpose</h3> <p>This ERC provides an interface for attestation issuers to manage their attestation signing keys and the attestations that are issued off chain for actions such as revocation and validation.</p> <p>In our draft implementation we include functions to hold cryptographic attestations, change the issuing contracts of attestations, revoke attestations and verify the authenticity of a cryptographic attestation.</p> <h3 id="example-use-cases">Example use cases</h3> <p>Let's say that our friend, Alice, wants to buy a bottle of wine to consume with her friends. She wants to do the order online and have it delivered to her home address whilst paying for it with Ether.</p> <p>Alice has a cryptographic attestation from her local road and maritime services who attests to her age, date of birth, country of residence and ability to drive.</p> <p>Alice is able to split up this attestation (see merkle tree attestations ERC <a rel="external" href="https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/lib/MerkleTreeAttestation.sol">here</a>) and provides only the leaf that states she is over the age of 21.</p> <p>Alice goes to buy the wine through the wine vendors smart contract and feeds in the merkle tree attestation proving that she is above 21 and can thus buy the wine, whilst attaching the appropriate amount of ether to complete the purchase.</p> <p>The issuer smart contract is able to validate her attestation, check that the issuer contract is valid and capable of performing such an attestation to her age. In this case it would have to be from someone like a driver's licence authority, as attestations to age from a school ID are not of a high enough capacity.</p> <p>The wine vendors smart contract validates the attestation, checks the payment amount is correct and credits Alice with the wine tokens she needs to complete the sale and deliver the wine.</p> <p>When the wine vendor shows up to her apartment with the wine, there is no need to prove her age again.</p> <h3 id="draft-interface">Draft interface</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/*</span><span class="z-comment"> each attestation issuer should provide their own verify() for the</span></span> <span class="giallo-l"><span class="z-comment"> * attestations they issued. There are two reasons for this. First, we</span></span> <span class="giallo-l"><span class="z-comment"> * need to leave room for new attestation methods other than the</span></span> <span class="giallo-l"><span class="z-comment"> * Merkle Tree format we are recommending. Second, the validity of the</span></span> <span class="giallo-l"><span class="z-comment"> * attestation may depend on the context that only the attestor</span></span> <span class="giallo-l"><span class="z-comment"> * knows. For example, a ticket as an attestation issued on a</span></span> <span class="giallo-l"><span class="z-comment"> * successful redemption of an American Express credit </span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Issuer</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Attestation</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> merklePath</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> valid</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> v</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> r</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> s</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> attestor</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> recipient</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> salt</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> key</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> val</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>`</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> Verify the authenticity of an attestation </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> verify</span><span>(</span><span class="z-storage z-type">Attestation</span><span class="z-variable"> attestation</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addattestorKey</span><span>(</span><span class="z-support">address</span><span class="z-variable"> newAttestor</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> capacity</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> expiry</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> this should call the revoke first </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> replaceKey</span><span>(</span><span class="z-support">address</span><span class="z-variable"> attestorToReplace</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> capacity</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> expiry</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> newAttestor</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> this revokes a single key </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeKey</span><span>(</span><span class="z-support">address</span><span class="z-variable"> attestor</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> if the key exists with such capacity and isn&#39;t revoked or expired </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validateKey</span><span>(</span><span class="z-support">address</span><span class="z-variable"> attestor</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> capacity</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> revoke an attestation by replace the bloom filter, this helps preserve privacy </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeAttestations</span><span>(</span><span class="z-storage z-type">Bloomfilter</span><span class="z-variable"> b</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Please click <a rel="external" href="https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/example-james-squire/james-squire.sol">here</a> to see a draft implementation of this interface</p> <h3 id="related-erc-s">Related ERC's</h3> <p>#1388 #1387</p> 2018-09-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Weiwu Zhanga@colourful.land James Sangallij.l.sangalli@gmail.com https://wg-eips.ritovision.com/1387/ <h3 id="introduction">Introduction</h3> <p>It's often needed that an Ethereum smart contract must verify a claim (I live in Australia) attested by a valid attester.</p> <p>For example, an ICO contract might require that the participant, Alice, lives in Australia before she participates. Alice's claim of residency could come from a local Justice of the Peace who could attest that "Alice is a resident of Australia in NSW".</p> <p>Unlike previous attempts, we assume that the attestation is signed and issued off the blockchain in a Merkle Tree format. Only a part of the Merkle tree is revealed by Alice at each use. Therefore we avoid the privacy problem often associated with issuing attestations on chain. We also assume that Alice has multiple signed Merkle Trees for the same factual claim to avoid her transactions being linkable.</p> <h2 id="purpose">Purpose</h2> <p>This ERC provides an interface and reference implementation for smart contracts that need users to provide an attestation and validate it.</p> <h3 id="draft-implementation">Draft implementation</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> MerkleTreeAttestationInterface</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> Attestation</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span> merklePath</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span> valid</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> v</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> r</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> s</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> attester</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> recipient</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> salt</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> key</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> val</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> validate</span><span>(</span><span class="z-storage z-type">Attestation</span><span class="z-variable"> attestation</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span></code></pre><h3 id="relevant-implementation-examples">Relevant implementation examples</h3> <p><a rel="external" href="https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/lib/MerkleTreeAttestation.sol">Here</a> is an example implementation of the MerkleTreeAttestationInterface <a rel="external" href="https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/example-james-squire/james-squire.sol">Here</a> is an example service which would use such a merkle tree attestation</p> <h3 id="related-erc-s">Related ERC's</h3> <p>#1388 #1386</p> 2018-09-08T00:00:00+00:00 2026-02-11T14:48:25+00:00 Weiwu Zhanga@colourful.land James Sangallij.l.sangalli@gmail.com https://wg-eips.ritovision.com/1388/ <h3 id="introduction">Introduction</h3> <p>In smart contracts, we will need methods to handle cryptographic attestations to a users identifier or abilities. Let's say we have a real estate agent, KiwiRealtors, that provides an "expression of interest" function though a smart contract and requires the users to provide an attestation that they are a resident of New Zealand or Australia, as a legal requirement. This has actually happened in the New Zealand property market and it is the perfect example of a need to handle such attestations.</p> <p>However, it is not practical for a smart contract to explicitly trust an attestation issuer. There are multiple issuers who can provide an attestation to a person's residency - a local Justice of the Peace, the land title office, local police, passport authority etc. We envision a model where the effort to manage the list of qualified issuers is practically outsourced to a list.</p> <p>Anyone can publish a list of issuers. Only the most trusted and carefully maintained lists gets popular use.</p> <h3 id="purpose">Purpose</h3> <p>This ERC provides a smart contract interface for anyone to manage a list of attestation issuers. A smart contract would explicitly trust a list, and therefore all attestations issued by the issuers on the list.</p> <h3 id="draft-implementation">Draft implementation</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> The purpose of this contract is to manage the list of attestation</span></span> <span class="giallo-l"><span class="z-comment"> * issuer contracts and their capacity to fulfill requirements</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> contract</span><span class="z-entity z-name"> ManagedListERC</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> a manager is the steward of a list. Only he/she/it can change the</span></span> <span class="giallo-l"><span class="z-comment"> * list by removing/adding attestation issuers to the list.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> * An issuer in the list is represented by their contract</span></span> <span class="giallo-l"><span class="z-comment"> * addresses, not by the attestation signing keys managed by such a</span></span> <span class="giallo-l"><span class="z-comment"> * contract.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> struct</span><span class="z-entity z-name"> List</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> name</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> description</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> short description of what the list entails</span></span> <span class="giallo-l"><span class="z-support"> string</span><span> capacity</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> serves as a filter for the attestation signing keys</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> if a smart contract specifies a list, only attestation issued</span></span> <span class="giallo-l"><span class="z-comment"> * by issuers on that list is accepted. Furthermore, if that</span></span> <span class="giallo-l"><span class="z-comment"> * list has a non-empty capacity, only attestations signed by a</span></span> <span class="giallo-l"><span class="z-comment"> * signing key with that capacity is accepted. </span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support"> address</span><span>[</span><span>]</span><span> issuerContracts</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> all these addresses are contracts, no signing capacity</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> expiry</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> find which list the sender is managing, then add an issuer to it</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addIssuer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> issuerContractAddress</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">return false if the list identified by the sender doesn&#39;t have this issuer in the list</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> removeIssuer</span><span>(</span><span class="z-support">address</span><span class="z-variable"> issuerContractAddress</span><span>,</span><span class="z-storage z-type"> List</span><span class="z-variable"> listToRemoveIssuerFrom</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> called by services, e.g. Kiwi Properties or James Squire </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> loop through all issuer&#39;s contract and execute validateKey() on</span></span> <span class="giallo-l"><span class="z-comment"> * every one of them in the hope of getting a hit, return the</span></span> <span class="giallo-l"><span class="z-comment"> * contract address of the first hit. </span><span class="z-keyword">Note</span><span class="z-comment"> that there is an attack</span></span> <span class="giallo-l"><span class="z-comment"> * method for one issuer to claim to own the key of another which</span></span> <span class="giallo-l"><span class="z-comment"> * is mitigated by later design. </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">loop through the issuers array, calling validate on the signingKeyOfAttestation</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getIssuerCorrespondingToAttestationKey</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> list_id</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> signingKeyOfAttestation</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> for simplicity we use sender&#39;s address as the list ID,</span></span> <span class="giallo-l"><span class="z-comment"> * accepting these consequences: a) if one user wish to maintain</span></span> <span class="giallo-l"><span class="z-comment"> * several lists with different capacity, he or she must use a</span></span> <span class="giallo-l"><span class="z-comment"> * different sender address for each. b) if the user replaced the</span></span> <span class="giallo-l"><span class="z-comment"> * sender&#39;s key, either because he or she suspects the key is</span></span> <span class="giallo-l"><span class="z-comment"> * compromised or that it is lost and reset through special means,</span></span> <span class="giallo-l"><span class="z-comment"> * then the list is still identified by the first sender&#39;s</span></span> <span class="giallo-l"><span class="z-comment"> * address.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createList</span><span>(</span><span class="z-storage z-type">List</span><span class="z-variable"> list</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-comment"> replace list manager&#39;s key with the new key </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> replaceListIndex</span><span>(</span><span class="z-storage z-type">List</span><span class="z-variable"> list</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> manager</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>Click <a rel="external" href="https://github.com/alpha-wallet/blockchain-attestation/blob/master/ethereum/trustlist/ManagedList.sol">here</a> to see an example implementation of this ERC</p> <h3 id="related-erc-s">Related ERC's</h3> <p>#1387 #1386</p> 2018-08-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Jacques Wagenerhttps://github.com/jacqueswww https://wg-eips.ritovision.com/1380/ <h2 id="abstract">Abstract</h2> <p>Reduce the gas cost for call instructions, when the goal is to run a new instance of the currently loaded contract.</p> <h2 id="motivation">Motivation</h2> <p>The current gas cost of 700 for all call types (<code>CALL</code>, <code>DELEGATECALL</code>, <code>CALLCODE</code> and <code>STATICCALL</code>) does not take into account that a call to a contract itself does not need to perform additional I/O operations, because the current contract code has already been loaded into memory.</p> <p>Reducing the call-to-self gas cost would greatly benefit smart contract languages, such as Solidity and Vyper, who would then be able to utilise <code>CALL</code> instead of <code>JUMP</code> opcodes for internal function calls. While languages can already utilise <code>CALL</code> for internal function calls, they are discouraged to do so due to the gas costs associated with it.</p> <p>Using <code>JUMP</code> comes at a considerable cost in complexity to the implementation of a smart contract language and/or compiler. The context (including stack and memory) must be swapped in and out of the calling functions context. A desired feature is having <em>pure</em> functions, which do not modify the state of memory, and realising them through <code>JUMP</code> requires a bigger effort from the compiler as opposed to being able to use <code>CALL</code>s.</p> <p>Using call-to-self provides the guarantee that when making an internal call the function can rely on a clear reset state of memory or context, benefiting both contract writers and contract consumers against potentially undetected edge cases were memory could poison the context of the internal function.</p> <p>Because of the <code>JUMP</code> usage for internal functions a smart contract languages are also at risk of reaching the stack depth limit considerably faster, if nested function calls with many in and/or outputs are required.</p> <p>Reducing the gas cost, and thereby incentivising of using call-to-self instead of <code>JUMP</code>s for the internal function implementation will also benefit static analyzers and tracers.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= FORK_BLKNUM</code>, then decrease the cost of <code>CALL</code>, <code>DELEGATECALL</code>, <code>CALLCODE</code> and <code>STATICCALL</code> from 700 to 40, if and only if, the destination address of the call equals to the address of the caller.</p> <h2 id="rationale">Rationale</h2> <p>EIP150 has increased the cost of these instructions from 40 to 700 to more fairly charge for loading new contracts from disk, e.g. to reflect the I/O charge more closely. By assuming that 660 is the cost of loading a contract from disk, one can assume that the original 40 gas is a fair cost of creating a new VM instance of an already loaded contract code.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This should pose no risk to backwards compatibility. Currently existing contracts should not notice the difference, just see cheaper execution. With EIP150 contract (and language) developers had a lesson that relying on strict gas costs is not feasible as costs may change. The impact of this EIP is even less that of EIP150 because the costs are changing downwards and not upwards.</p> <h2 id="test-cases">Test Cases</h2> <p>TBA</p> <h2 id="implementation">Implementation</h2> <p>TBA</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-08-13T00:00:00+00:00 2026-02-11T14:48:26+00:00 Piper Merriampiper@ethereum.org Christopher Geweckechristophergewecke@gmail.com g. nicholas d'andreanick.dandrea@consensys.net Nick Gheorghitahttps://github.com/njgheorghita https://wg-eips.ritovision.com/1319/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for smart contract package registries.</p> <h2 id="abstract">Abstract</h2> <p>This EIP specifies an interface for publishing to and retrieving assets from smart contract package registries. It is a companion EIP to <a href="https://wg-eips.ritovision.com/1123/">1123</a> which defines a standard for smart contract package manifests.</p> <h2 id="motivation">Motivation</h2> <p>The goal is to establish a framework that allows smart contract publishers to design and deploy code registries with arbitrary business logic while exposing a set of common endpoints that tooling can use to retrieve assets for contract consumers.</p> <p>A clear standard would help the existing EthPM Package Registry evolve from a centralized, single-project community resource into a decentralized multi-registry system whose constituents are bound together by the proposed interface. In turn, these registries could be ENS name-spaced, enabling installation conventions familiar to users of <code>npm</code> and other package managers.</p> <p><strong>Examples</strong></p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> ethpm</span><span class="z-string"> install</span><span class="z-string"> packages.zeppelin.eth/Ownership</span></span></code></pre><pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> SimpleToken</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> web3</span><span>.</span><span class="z-variable z-other">packaging</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">registry</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">packages.ethpm.eth</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">getPackage</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">simple-token</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> .</span><span class="z-entity z-name">getVersion</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">^1.1.5</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span></code></pre><h2 id="specification">Specification</h2> <p>The specification describes a small read/write API whose components are mandatory. It allows registries to manage versioned releases using the conventions of <a rel="external" href="https://semver.org/">semver</a> without imposing this as a requirement. It assumes registries will share the following structure and conventions:</p> <ul> <li>a <strong>registry</strong> is a deployed contract which manages a collection of <strong>packages</strong>.</li> <li>a <strong>package</strong> is a collection of <strong>releases</strong></li> <li>a <strong>package</strong> is identified by a unique string name and unique bytes32 <strong>packageId</strong> within a given <strong>registry</strong></li> <li>a <strong>release</strong> is identified by a <code>bytes32</code> <strong>releaseId</strong> which must be unique for a given package name and release version string pair.</li> <li>a <strong>releaseId</strong> maps to a set of data that includes a <strong>manifestURI</strong> string which describes the location of an <a href="https://wg-eips.ritovision.com/1123/">EIP 1123 package manifest</a>. This manifest contains data about the release including the location of its component code assets.</li> <li>a <strong>manifestURI</strong> is a URI as defined by <a rel="external" href="https://tools.ietf.org/html/rfc3986">RFC3986</a> which can be used to retrieve the contents of the package manifest. In addition to validation against RFC3986, each <strong>manifestURI</strong> must also contain a hash of the content as specified in the <a href="https://wg-eips.ritovision.com/1123/">EIP-1123</a>.</li> </ul> <h3 id="examples">Examples</h3> <p><strong>Package Names / Release Versions</strong></p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">simple-token</span><span class="z-entity z-name">&quot;</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> package name</span></span> <span class="giallo-l"><span class="z-entity z-name">&quot;</span><span class="z-entity z-name">1.0.1</span><span class="z-entity z-name">&quot;</span><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> version string</span></span></code></pre> <p><strong>Release IDs</strong></p> <p>Implementations are free to choose any scheme for generating a <strong>releaseId</strong>. A common approach would be to hash the strings together as below:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Hashes package name and a release version string</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> generateReleaseId</span><span>(</span><span class="z-support">string</span><span class="z-variable"> packageName</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> version</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> releaseId</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>packageName</span><span>,</span><span> version</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>Implementations <strong>must</strong> expose this id generation logic as part of their public <code>read</code> API so tooling can easily map a string based release query to the registry's unique identifier for that release.</p> <p><strong>Manifest URIs</strong></p> <p>Any IPFS or Swarm URI meets the definition of <strong>manifestURI</strong>.</p> <p>Another example is content on GitHub addressed by its SHA-1 hash. The Base64 encoded content at this hash can be obtained by running:</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> curl</span><span class="z-string"> https://api.github.com/repos/:owner/:repo/git/blobs/:file_sha</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Example</span></span> <span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> curl</span><span class="z-string"> https://api.github.com/repos/rstallman/hello/git/blobs/ce013625030ba8dba906f756967f9e9ca394464a</span></span></code></pre> <p>The string "hello" can have its GitHub SHA-1 hash independently verified by comparing it to the output of:</p> <pre class="giallo z-code"><code data-lang="shellscript"><span class="giallo-l"><span class="z-entity z-name">$</span><span class="z-string"> printf</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">blob 6\000hello\n</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> |</span><span class="z-entity z-name"> sha1sum</span></span> <span class="giallo-l"><span class="z-keyword">&gt;</span><span> ce013625030ba8dba906f756967f9e9ca394464a</span></span></code></pre><h3 id="write-api-specification">Write API Specification</h3> <p>The write API consists of a single method, <code>release</code>. It passes the registry the package name, a version identifier for the release, and a URI specifying the location of a manifest which details the contents of the release.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> release</span><span>(</span><span class="z-support">string</span><span class="z-variable"> packageName</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> version</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> manifestURI</span><span>)</span><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> releaseId</span><span>)</span><span>;</span></span></code></pre><h3 id="events">Events</h3> <h4 id="versionrelease">VersionRelease</h4> <p>MUST be triggered when <code>release</code> is successfully called.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> VersionRelease</span><span>(</span><span class="z-support">string</span><span class="z-variable"> packageName</span><span>, </span><span class="z-support">string</span><span class="z-variable"> version</span><span>, </span><span class="z-support">string</span><span class="z-variable"> manifestURI</span><span>)</span></span></code></pre><h3 id="read-api-specification">Read API Specification</h3> <p>The read API consists of a set of methods that allows tooling to extract all consumable data from a registry.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Retrieves a slice of the list of all unique package identifiers in a registry.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> `offset` and `limit` enable paginated responses / retrieval of the complete set. (See </span><span class="z-keyword">note</span><span class="z-comment"> below)</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getAllPackageIds</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> offset</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> limit</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-variable"> packageIds</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> pointer</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Retrieves the unique string `name` associated with a package&#39;s id.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getPackageName</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> packageId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable"> packageName</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Retrieves the registry&#39;s unique identifier for an existing release of a package.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getReleaseId</span><span>(</span><span class="z-support">string</span><span class="z-variable"> packageName</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> version</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> releaseId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Retrieves a slice of the list of all release ids for a package.</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> `offset` and `limit` enable paginated responses / retrieval of the complete set. (See </span><span class="z-keyword">note</span><span class="z-comment"> below)</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getAllReleaseIds</span><span>(</span><span class="z-support">string</span><span class="z-variable"> packageName</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> offset</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> limit</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-variable"> releaseIds</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-variable"> pointer</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Retrieves package name, release version and URI location data for a release id.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getReleaseData</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> releaseId</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> packageName</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> version</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> string</span><span class="z-variable"> manifestURI</span></span> <span class="giallo-l"><span> )</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Retrieves the release id a registry *would* generate for a package name and version pair</span></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> when executing a release.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> generateReleaseId</span><span>(</span><span class="z-support">string</span><span class="z-variable"> packageName</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> version</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> releaseId</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Returns the total number of unique packages in a registry.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> numPackageIds</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> totalCount</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Returns the total number of unique releases belonging to the given packageName in a registry.</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> numReleaseIds</span><span>(</span><span class="z-support">string</span><span class="z-variable"> packageName</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> totalCount</span><span>)</span><span>;</span></span></code></pre> <p><strong>Pagination</strong></p> <p><code>getAllPackageIds</code> and <code>getAllReleaseIds</code> support paginated requests because it's possible that the return values for these methods could become quite large. The methods should return a <code>pointer</code> that points to the next available item in a list of all items such that a caller can use it to pick up from where the previous request left off. (See <a rel="external" href="https://mixmax.com/blog/api-paging-built-the-right-way">here</a> for a discussion of the merits and demerits of various pagination strategies.) The <code>limit</code> parameter defines the maximum number of items a registry should return per request.</p> <h2 id="rationale">Rationale</h2> <p>The proposal hopes to accomplish the following:</p> <ul> <li>Define the smallest set of inputs necessary to allow registries to map package names to a set of release versions while allowing them to use any versioning schema they choose.</li> <li>Provide the minimum set of getter methods needed to retrieve package data from a registry so that registry aggregators can read all of their data.</li> <li>Define a standard query that synthesizes a release identifier from a package name and version pair so that tooling can resolve specific package version requests without needing to query a registry about all of a package's releases.</li> </ul> <p>Registries may offer more complex <code>read</code> APIs that manage requests for packages within a semver range or at <code>latest</code> etc. This EIP is agnostic about how tooling or registries might implement these. It recommends that registries implement <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> and avail themselves of resources to publish more complex interfaces such as <a href="https://wg-eips.ritovision.com/926/">EIP-926</a>.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No existing standard exists for package registries. The package registry currently deployed by EthPM would not comply with the standard since it implements only one of the method signatures described in the specification.</p> <h2 id="implementation">Implementation</h2> <p>A reference implementation of this proposal is in active development at the EthPM organization on GitHub <a rel="external" href="https://github.com/ethpm/escape-truffle">here</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-08-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Brian Venturohttps://github.com/atlanticcrypto https://wg-eips.ritovision.com/1295/ <h2 id="simple-summary">Simple Summary</h2> <p>Network security and overall ecosystem maturity warrants the continued incentivization of Proof of Work participation but may allow for a reduction in ancillary ETH issuance and the delay of the Difficulty Bomb. This EIP proposes a reduction of Uncle and removal of Nephew rewards while delaying the Difficulty Bomb with the Constantinople hard fork.</p> <h2 id="abstract">Abstract</h2> <p>Starting with CNSTNTNPL_FORK_BLKNUM the client will calculate the difficulty based on a fake block number suggesting the client that the difficulty bomb is adjusting around 6 million blocks later than previously specified with the Homestead fork.</p> <p>Furthermore, Uncle rewards will be adjusted and Nephew rewards will be removed to eliminate excess ancillary ETH issuance. The current ETH block reward of 3 ETH will remain constant.</p> <h2 id="motivation">Motivation</h2> <p>Network scalability and security are at the forefront of risks to the Ethereum protocol. With great strides being made towards on and off chain scalability, the existence of an artificial throughput limiting device in the protocol is not warranted. Removing the risk of reducing throughput through the initialization of the Difficulty Bomb is "low-hanging-fruit" to ensure continued operation at a minimum of current throughput through the next major hard fork (scheduled for late 2019).</p> <p>The security layer of the Ethereum network is and should remain robust. Incentives for continued operation of the security of the growing ecosystem are paramount.</p> <p>At the same time, the ancillary issuance benefits of the Ethereum protocol can be adjusted to reduce the overall issuance profile. Aggressively adjusting Uncle and removing Nephew rewards will reduce the inflationary aspect of ETH issuance, while keeping the current block reward constant at 3 ETH will ensure top line incentives stay in place.</p> <h2 id="specification">Specification</h2> <h4 id="relax-difficulty-with-fake-block-number">Relax Difficulty with Fake Block Number</h4> <p>For the purposes of <code>calc_difficulty</code>, simply replace the use of <code>block.number</code>, as used in the exponential ice age component, with the formula:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>fake_block_number = max(0, block.number - 6_000_000) if block.number &gt;= CNSTNTNPL_FORK_BLKNUM else block.number</span></span></code></pre><h4 id="adjust-uncle-and-nephew-rewards">Adjust Uncle and Nephew rewards</h4> <p>If an uncle is included in a block for <code>block.number &gt;= CNSTNTNPL_FORK_BLKNUM</code> such that <code>block.number - uncle.number = k</code>, the uncle reward is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_uncle_reward = (3 - k) * new_block_reward / 8</span></span></code></pre> <p>This is the existing pre-Constantinople formula for uncle rewards, adjusted to reward 2 levels of Uncles at a reduced rate.</p> <p>The nephew reward for <code>block.number &gt;= CNSTNTNPL_FORK_BLKNUM</code> is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_nephew_reward = 0</span></span></code></pre> <p>This is a removal of all rewards for Nephew blocks.</p> <h2 id="rationale">Rationale</h2> <p>The security layer of the Ethereum network is and should remain robust. Incentives for continued operation of the growing ecosystem’s security are paramount.</p> <p>At the same time, the ancillary issuance benefits of the Ethereum protocol can be adjusted to reduce the overall issuance profile. Aggressively adjusting Uncle and removing Nephew rewards will reduce the inflationary aspect of ETH issuance, while keeping the current block reward constant at 3 ETH will ensure top line incentives stay in place.</p> <p>The Difficulty Bomb was instituted as a type of planned obsolescence to force the implementation of network upgrades with regular frequency. With the focus on scalability for the protocol, delaying a mechanism whereby the throughput of the network can be limited artificially, due to any circumstance, is a logical step to ensure continued minimum network operation at the current throughput level. We believe the existence of the Difficulty Bomb has allowed for the inclusion of protocol upgrades in forced hard-forks, and will continue to do so.</p> <p>Through August 4th, the 2018 year to date reward issued to Uncle blocks totaled over 635,000 ETH. The average reward per Uncle totals 2.27 ETH. The year to date average Uncle rate is 22.49%. Using the year to date metrics, the ongoing average ETH paid as an Uncle reward per block is 0.51 ETH plus the Uncle inclusion reward of 0.021 ETH (0.09375 ETH * .2249), total Uncle related reward per block being over 0.53 ETH. With total year to date block rewards totaling approximately 3,730,000 ETH, the network has paid an additional 17pct in Uncle rewards. This is issuance that can be reduced while still maintaining the overall integrity and incentivization of network security.</p> <p>Reducing the issuance of ETH in rewarding Uncle blocks (forked blocks caused by latency in propagation, a multi-faceted problem) should directly incentivize the investment in technologies and efficiencies to reduce block propagation latency which may lead to a reduction in Network wide Uncle rates, reducing ancillary issuance further.</p> <p>Reducing the Uncle rewards from the current specification to the proposed will yield two levels of ancillary ETH issuance for Uncles:</p> <p>Level 1 Uncle -&gt; 0.75 ETH</p> <p>Level 2 Uncle -&gt; 0.375 ETH</p> <p>These levels are sufficient to continue incentivizing decentralized participation, while also providing an immediate economic incentive for the upgrade of the Ethereum node network and its tangential infrastructure.</p> <p>We believe that the ETH network has been subsidizing transaction inclusion through the robust Uncle Reward structure since inception. We also believe that a removal of the set subsidy will create a dynamic response mechanism whereby Miners and transaction senders will minimize total costs of transaction inclusion. This dynamic response structure may limit unnecessary layer 1 transaction throughput while providing incentives for layer 2 scaling solutions.</p> <p>The Nephew reward structure should be entirely eliminated.</p> <p>Due to current market conditions, and the likelihood of a further USD denominated price decline (50%), we believe that any top line reduction to security incentives will put the Ethereum network at undue risk. Unlike the time of the Byzantium hard fork, current USD denominated economics for securing the Ethereum network threaten the participation of the most decentralized Miner community (at home miners), which we believe make up the largest proportion of the overall network hashrate. We believe eliminating this portion of the community will increase centralization and the probability of an organized network attack.</p> <p>For a technology so new and with so much potential, we find it extremely irresponsible to increase the likelihood of a network attack by reducing ETH Issuance past this proposal’s level.</p> <p>With a reduction to the Uncle and removal of the Nephew reward, ancillary ETH issuance should drop (under normal market conditions, i.e. 22.49% uncle rate) by over 75pct and total ETH issuance from the successful sealing and mining of valid blocks should drop over 10pct.</p> <p>Paired with the diffusal of the Difficulty Bomb, this proposal strikes a balance between ensuring status quo network throughput, reducing overall ETH issuance, and continuing top line incentives for investment in infrastructure and efficiencies to continue operating the Ethereum network’s security layer.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is not forward compatible and introduces backwards incompatibilities in the difficulty calculation, as well as the block, uncle and nephew reward structure. Therefore, it should be included in a scheduled hardfork at a certain block number. It's suggested to include this EIP in the second Metropolis hard-fork, Constantinople.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases shall be created once the specification is to be accepted by the developers or implemented by the clients.</p> <h2 id="implementation">Implementation</h2> <p>Forthcoming.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-08-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ben Kaufmanben@daostack.io Adam Leviadam@daostack.io https://wg-eips.ritovision.com/1285/ <h2 id="simple-summary">Simple Summary</h2> <p>Increase the <code>Gcallstipend</code> fee parameter in the <code>CALL</code> opcode from <code>2,300</code> to <code>3,500</code> gas units.</p> <h2 id="abstract">Abstract</h2> <p>Currently, the <code>CALL</code> opcode forwards a stipend of <code>2,300</code> gas units for a non zero value <code>CALL</code> operations where a contract is called. This stipend is given to the contract to allow execution of its <code>fallback</code> function. The stipend given is intentionally small in order to prevent the called contract from spending the call gas or performing an attack (like re-entrancy). While the stipend is small it should still give the sufficient gas required for some cheap opcodes like <code>LOG</code>, but it's not enough for some more complex and modern logics to be implemented. This EIP proposes to increase the given stipend from <code>2,300</code> to <code>3,500</code> to increase the usability of the <code>fallback</code> function.</p> <h2 id="motivation">Motivation</h2> <p>The main motivation behind this EIP is to allow simple fallback functions to be implemented for contracts following the <code>"Proxy"</code> pattern. Simply explained, a <code>"Proxy Contract"</code> is a contract which use <code>DELEGATECALL</code> in its <code>fallback</code> function to behave according to the logic of another contract and serve as an independent instance for the logic of the contract it points to. This pattern is very useful for saving gas per deployment (as Proxy contracts are very lean) and it opens the ability to experiment with upgradability of contracts. On average, the <code>DELEGATECALL</code> functionality of a proxy contract costs about <code>1,000</code> gas units. When a contract transfers ETH to a proxy contract, the proxy logic will consume about <code>1,000</code> gas units before the <code>fallback</code> function of the logic contract will be executed. This leaves merely about 1,300 gas units for the execution of the logic. This is a severe limitation as it is not enough for an average <code>LOG</code> operation (it might be enough for a <code>LOG</code> with one parameter). By slightly increasing the gas units given in the stipend we allow proxy contracts have proper <code>fallback</code> logic without increasing the attack surface of the calling contract.</p> <h2 id="specification">Specification</h2> <p>Increase the <code>Gcallstipend</code> fee parameter in the <code>CALL</code> opcode from <code>2,300</code> to <code>3,500</code> gas unit. The actual change to the Ethereum clients would be to change the <code>CallStipend</code> they store as a constant. For an implementation example you can find a Geth client implementation linked <a rel="external" href="https://github.com/ben-kaufman/go-ethereum/tree/eip-1285">here</a>. The actual change to the code can be found <a rel="external" href="https://github.com/ben-kaufman/go-ethereum/blob/eip-1285/params/protocol_params.go#L41">here</a>.</p> <h2 id="rationale">Rationale</h2> <p>The rational for increasing the <code>Gcallstipend</code> gas parameter by <code>1,200</code> gas units comes from the cost of performing <code>DELEGATECALL</code> and <code>SLOAD</code> with a small margin for some small additional operations. All while still keeping the stipend relatively small and insufficient for accessing the storage or changing the state.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a backwards incompatible change for the <code>Gcallstipend</code> gas parameter in the <code>CALL</code> opcode.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-08-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kevin Owockikevin@gitcoin.co Andrew Reddenandrew@blockcrushr.com Scott Burkescott@blockcrushr.com Kevin Seagravesk.s.seagraves@gmail.com Luka Kacilluka.kacil@gmail.com Štefan Šimecstefan.simec@gmail.com Piotr Kosińskihttps://github.com/kosecki123 ankit rajtradeninja7@gmail.com John Griffinjohn@atchai.com Nathan Creswellnathantr@gmail.com https://wg-eips.ritovision.com/1337/ <h2 id="simple-summary">Simple Summary</h2> <p>Monthly subscriptions are a key monetization channel for legacy web, and arguably they are the most healthy monetization channel for businesses on the legacy web (especially when compared to ad/surveillance) based models. They are arguably more healthy than a token based economic system (depending upon the vesting model of the ICO) because</p> <h5 id="for-a-user">For a user:</h5> <ul> <li>you don't have to read a complex whitepaper to use a dapps utility (as opposed to utility tokens)</li> <li>you don't have to understand the founder's vesting schedules</li> <li>you can cancel anytime</li> </ul> <h5 id="for-a-service-provider">For a Service Provider:</h5> <ul> <li>since you know your subscriber numbers, churn numbers, conversion rate, you get consistent cash flow, and accurate projections</li> <li>you get to focus on making your customers happy</li> <li>enables you to remove speculators from your ecosystem</li> </ul> <p>For these reasons, we think it's imperative to create a standard way to do 'subscriptions' on Ethereum.</p> <h2 id="abstract">Abstract</h2> <p>To enable replay-able transactions users sign a concatenated bytes hash that is composed of the input data needed to execute the transaction. This data is stored off chain by the recipient of the payment and is transmitted to the customers smart contract for execution alongside a provided signature.</p> <h2 id="motivation">Motivation</h2> <p>Recurring payments are the bedrock of SaSS and countless other businesses, a robust specification for defining this interaction will enable a broad spectrum of revenue generation and business models.</p> <h2 id="specification">Specification</h2> <h4 id="enum-contract">Enum Contract</h4> <p>EIP-1337 Contracts should be compiled with a contract that references all the enumerations that are required for operation</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> Enum - Collection of enums</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> Original concept from Richard Meissner - &lt;richard@gnosis.pm&gt; Gnosis safe contracts</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Enum</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> Operation</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Call</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> DelegateCall</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Create</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ERC20</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ERC20Approve</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> SubscriptionStatus</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> ACTIVE</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> PAUSED</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> CANCELLED</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> EXPIRED</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> enum</span><span class="z-entity z-name"> Period</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> INIT</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> DAY</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> WEEK</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> MONTH</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="eip-165">EIP-165</h4> <p>EIP-1337 compliant contracts support EIP-165 announcing what interfaces they support</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> Query if a contract implements an interface</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> interfaceID</span><span class="z-comment"> The interface identifier, as specified in ERC-165</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Interface identification is specified in ERC-165. This function</span></span> <span class="giallo-l"><span class="z-comment"> * uses less than 30,000 gas.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-comment"> `true` if the contract implements `interfaceID` and</span></span> <span class="giallo-l"><span class="z-comment"> * `interfaceID` is not 0xffffffff, `false` otherwise</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="public-view-functions">Public View Functions</h4> <h6 id="isvalidsubscription">isValidSubscription</h6> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Checks if the subscription is valid.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bytes</span><span class="z-comment"> subscriptionHash is the identifier of the customer&#39;s subscription with its relevant details.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> success</span><span class="z-comment"> is the result of whether the subscription is valid or not.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isValidSubscription</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subscriptionHash</span></span> <span class="giallo-l"><span> )</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> success</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h6 id="getsubscriptionstatus">getSubscriptionStatus</h6> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> returns the value of the subscription</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bytes</span><span class="z-comment"> subscriptionHash is the identifier of the customer&#39;s subscription with its relevant details.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> status</span><span class="z-comment"> is the enumerated status of the current subscription, 0 expired, 1 active, 2 paused, 3 cancelled</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getSubscriptionStatus</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subscriptionHash</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> status</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> nextWithdraw</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h6 id="getsubscriptionhash">getSubscriptionHash</h6> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> returns the hash of cocatenated inputs to the address of the contract holding the logic.,</span></span> <span class="giallo-l"><span class="z-comment"> * the owner would sign this hash and then provide it to the party for execution at a later date,</span></span> <span class="giallo-l"><span class="z-comment"> * this could be viewed like a cheque, with the exception that unless you specifically</span></span> <span class="giallo-l"><span class="z-comment"> * capture the hash on chain a valid signature will be executable at a later date, capturing the hash lets you modify the status to cancel or expire it.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> address</span><span class="z-comment"> recipient the address of the person who is getting the funds.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> value the value of the transaction</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bytes</span><span class="z-comment"> data the data the user is agreeing to</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> txGas the cost of executing one of these transactions in gas(probably safe to pad this)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> dataGas the cost of executing the data portion of the transaction(delegate calls etc)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint</span><span class="z-comment"> 256 gasPrice the agreed upon gas cost of Execution of this subscription(cost incurment is up to implementation, ie, sender or receiver)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> address</span><span class="z-comment"> gasToken address of the token in which gas will be compensated by, address(0) is ETH, only works in the case of an enscrow implementation)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bytes</span><span class="z-comment"> meta dynamic bytes array with 4 slots, 2 required, 2 optional // address refundAddress / uint256 period / uint256 offChainID / uint256 expiration (uinx timestamp)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> bytes32</span><span class="z-comment">, return the hash input arguments concatenated to the address of the contract that holds the logic.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getSubscriptionHash</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> recipient</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Enum</span><span>.</span><span class="z-support z-variable">Operation</span><span class="z-variable"> operation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> txGas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> dataGas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> gasPrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> gasToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> meta</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> subscriptionHash</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h6 id="getmodifystatushash">getModifyStatusHash</h6> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> returns the hash of concatenated inputs that the owners user would sign with their public keys</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> address</span><span class="z-comment"> recipient the address of the person who is getting the funds.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> value the value of the transaction</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> bytes32</span><span class="z-comment"> returns the hash of concatenated inputs with the address of the contract holding the subscription hash</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getModifyStatusHash</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> subscriptionHash</span></span> <span class="giallo-l"><span class="z-storage z-type"> Enum</span><span>.</span><span class="z-support z-variable">SubscriptionStatus</span><span class="z-variable"> status</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span></span> <span class="giallo-l"><span class="z-storage z-type"> view</span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-variable"> modifyStatusHash</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h4 id="public-functions">Public Functions</h4> <h6 id="modifystatus">modifyStatus</h6> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> modifys the current subscription status</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> subscriptionHash is the identifier of the customer&#39;s subscription with its relevant details.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> Enum</span><span class="z-comment">.SubscriptionStatus status the new status of the subscription</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bytes</span><span class="z-comment"> signatures of the requested method being called</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> success</span><span class="z-comment"> is the result of the subscription being paused</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> modifyStatus</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> subscriptionHash</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> Enum</span><span>.</span><span class="z-support z-variable">SubscriptionStatus</span><span class="z-variable"> status</span><span>,</span><span> </span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> signatures</span></span> <span class="giallo-l"><span> )</span><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> success</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h6 id="executesubscription">executeSubscription</h6> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">/**</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> returns the hash of cocatenated inputs to the address of the contract holding the logic.,</span></span> <span class="giallo-l"><span class="z-comment"> * the owner would sign this hash and then provide it to the party for execution at a later date,</span></span> <span class="giallo-l"><span class="z-comment"> * this could be viewed like a cheque, with the exception that unless you specifically</span></span> <span class="giallo-l"><span class="z-comment"> * capture the hash on chain a valid signature will be executable at a later date, capturing the hash lets you modify the status to cancel or expire it.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> address</span><span class="z-comment"> recipient the address of the person who is getting the funds.</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> value the value of the transaction</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bytes</span><span class="z-comment"> data the data the user is agreeing to</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> txGas the cost of executing one of these transactions in gas(probably safe to pad this)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint256</span><span class="z-comment"> dataGas the cost of executing the data portion of the transaction(delegate calls etc)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> uint</span><span class="z-comment"> 256 gasPrice the agreed upon gas cost of Execution of this subscription(cost incurment is up to implementation, ie, sender or receiver)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> address</span><span class="z-comment"> gasToken address of the token in which gas will be compensated by, address(0) is ETH, only works in the case of an enscrow implementation)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bytes</span><span class="z-comment"> meta dynamic bytes array with 4 slots, 2 required, 2 optional // address refundAddress / uint256 period / uint256 offChainID / uint256 expiration (uinx timestamp)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> bytes</span><span class="z-comment"> signatures signatures concatenated that have signed the inputs as proof of valid execution</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@return</span><span class="z-variable z-other"> bool</span><span class="z-comment"> success something to </span><span class="z-keyword">note</span><span class="z-comment"> that a failed execution will still pay the issuer of the transaction for their gas costs.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> executeSubscription</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> data</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> Enum</span><span>.</span><span class="z-support z-variable">Operation</span><span class="z-variable"> operation</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> txGas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> dataGas</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> gasPrice</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable"> gasToken</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> meta</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes</span><span class="z-variable"> signatures</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span class="z-storage z-type"> public</span><span> </span></span> <span class="giallo-l"><span class="z-keyword"> returns</span><span> (</span></span> <span class="giallo-l"><span class="z-support"> bool</span><span class="z-variable"> success</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>Merchants who accept credit-cards do so by storing a token that is retrieved from a third party processor(stripe, paypal, etc), this token is used to grant access to pull payment from the cx's credit card provider and move funds to the merchant account. Having users sign input data acts in a similliar fashion and enables that merchant to store the signature of the concatenated bytes hash and input data used to generate the hash and pass them off to the contract holding the subscription logic, thus enabling a workflow that is similliar to what exists in the present day legacy web.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>N/A</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-08-01T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Paweł Bylicahttps://github.com/chfast https://wg-eips.ritovision.com/1985/ <h2 id="abstract">Abstract</h2> <p>Introduce an explicit value range for certain EVM parameters (such as gas limit, block number, block timestamp, size field when returning/copying data within EVM). Some of these already have an implicit value range due to various (practical) reasons.</p> <h2 id="motivation">Motivation</h2> <p>Having such an explicit value range can help in creating compatible client implementations, in certain cases it can also offer minor speed improvements, and can reduce the effort needed to create consensus critical test cases by eliminating unrealistic edge cases.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= {FORK_BLOCK}</code>, the following value ranges are introduced. They restrict the results (i.e. values pushed to the stack) of the instructions listed below.</p> <ol> <li> <p><em>gas</em>, <em>gas limit</em>, <em>block gas limit</em> is a range between <code>0</code> and <code>0x7fffffffffffffff</code> (<code>2**63 - 1</code>, <code>9223372036854775807</code>). It affects the following instructions:</p> <ul> <li><code>GASLIMIT</code> (<code>0x45</code>),</li> <li><code>GAS</code> (<code>0x5a</code>).</li> </ul> </li> <li> <p><em>block number</em>, <em>timestamp</em> is a range between <code>0</code> and <code>0x7fffffffffffffff</code> (<code>2**63 - 1</code>, <code>9223372036854775807</code>). It affects the following instructions:</p> <ul> <li><code>TIMESTAMP</code> (<code>0x42</code>),</li> <li><code>NUMBER</code> (<code>0x43</code>).</li> </ul> </li> <li> <p><em>account address</em> is a range between <code>0</code> and <code>0xffffffffffffffffffffffffffffffffffffffff</code> (<code>2**160 - 1</code>, <code>1461501637330902918203684832716283019655932542975</code>) i.e. the address occupies the 160 low bits of the 256-bit value and the remaining top 96 bits must be zeros. It affects the following instructions:</p> <ul> <li><code>ADDRESS</code> (<code>0x30</code>),</li> <li><code>ORIGIN</code> (<code>0x32</code>),</li> <li><code>CALLER</code> (<code>0x33</code>),</li> <li><code>COINBASE</code> (<code>0x41</code>),</li> <li><code>CREATE</code> (<code>0xf0</code>),</li> <li><code>CREATE2</code> (<code>0xf5</code>).</li> </ul> </li> <li> <p><em>buffer size</em>, <em>code size</em>, <em>memory size</em> is a range between <code>0</code> and <code>0xffffffff</code> (<code>2**32 - 1</code>, <code>4294967295</code>). It affects the following instructions:</p> <ul> <li><code>CALLDATASIZE</code> (<code>0x36</code>),</li> <li><code>CODESIZE</code> (<code>0x38</code>),</li> <li><code>EXTCODESIZE</code> (<code>0x3b</code>),</li> <li><code>RETURNDATASIZE</code> (<code>0x3d</code>),</li> <li><code>MSIZE</code> (<code>0x59</code>),</li> <li><code>PC</code> (<code>0x58</code>).</li> </ul> </li> </ol> <h2 id="rationale">Rationale</h2> <p>These limits have been:</p> <ul> <li>proposed by <a rel="external" href="https://github.com/ethereum/evmc">EVMC</a></li> <li>implemented partially by certain clients, such as <a rel="external" href="https://github.com/ethereum/aleth">Aleth</a>, <a rel="external" href="https://github.com/ethereum/go-ethereum">geth</a>, <a rel="external" href="https://github.com/paritytech/parity-ethereum">Parity</a> and <a rel="external" href="https://github.com/ethereumjs">ethereumjs</a></li> <li>allowed by certain test cases in the <a rel="external" href="https://github.com/ethereum/tests">Ethereum testing suite</a></li> <li>and implicitly also allowed by certain assumptions, such as due to gas limits some of these values cannot grow past a certain limit</li> </ul> <p>Most of the limits proposed in this document have been previously explored and tested in <a rel="external" href="https://github.com/ethereum/evmc">EVMC</a>.</p> <p>Using the <code>2**63 - 1</code> constant to limit some of the ranges:</p> <ul> <li>allows using signed 64-bit integer type to represent it, what helps programming languages not having unsigned types,</li> <li>makes arithmetic simpler (e.g. checking out-of-gas conditions is simple as <code>gas_counter &lt; 0</code>).</li> </ul> <h3 id="timestamp">Timestamp</h3> <p>The <a rel="external" href="https://github.com/ethereum/yellowpaper">Yellow Paper</a> defines the timestamp in block as "A scalar value equal to the reasonable output of Unix’s time() at this block’s inception". IEEE Std 1003.1-2001 (POSIX.1) leaves that definition implementation defined.</p> <h3 id="addresses">Addresses</h3> <p>The size of addresses is specified in the <a rel="external" href="https://github.com/ethereum/yellowpaper">Yellow Paper</a> as 20 bytes. E.g. the <code>COINBASE</code> instruction is specified to return <em>H</em><sub>c</sub> ∈ 𝔹<sub>20</sub> which has 20 bytes.</p> <h3 id="memory-size">Memory size</h3> <p>Memory expansion cost is not linear and is determined by the following formula: cost = cost_per_word * number_of_words + (number_of_words ^ 2 / 512)</p> <p>Expanding to over <code>2^32 - 1</code> bytes would cost <code>35184774742016</code> gas. This number fits into the gas limit imposed above (<code>2 ^ 63 - 1</code>) and would cost around 35184 Ether in a transaction to exhaust, with a 1 GWei gas cost, which can be attained on mainnet.</p> <p>However, setting the limit <code>2^32 - 1</code> is beneficial from a VM design perspective and we believe limiting memory should be done via carefully selecting the block gas limit.</p> <h3 id="code-size">Code size</h3> <p><a href="https://wg-eips.ritovision.com/170/">EIP-170</a> has implemented a code size limit of 0x6000, however even before that, it was practically impossible to deploy a code blob exceeding <code>2**32 - 1</code> bytes in size.</p> <h3 id="comparing-current-implementations">Comparing current implementations</h3> <ul> <li>Timestamp is implemented as a 64-bit value in <a rel="external" href="https://github.com/ethereum/aleth">Aleth</a>, <a rel="external" href="https://github.com/ethereum/go-ethereum">geth</a> and <a rel="external" href="https://github.com/paritytech/parity-ethereum">Parity</a></li> <li>Block gas limit is implemented as a 64-bit in <a rel="external" href="https://github.com/ethereum/aleth">Aleth</a> and <a rel="external" href="https://github.com/ethereum/go-ethereum">geth</a></li> <li>Memory, buffer and code sizes are implemented as 64-bit values in <a rel="external" href="https://github.com/ethereum/go-ethereum">geth</a></li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>All of these limits are already enforced mostly through the block gas limit. Since the out of range case results in a transaction failure, there should not be a change in behaviour.</p> <h2 id="test-cases">Test Cases</h2> <p>TBA</p> <h2 id="implementation">Implementation</h2> <p>TBA</p> <h2 id="references">References</h2> <ul> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/92">EIP-92</a> proposed the transaction gas limit to be limited at <code>2**63 - 1</code> and had a lengthy discussion about other limits.</li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/106">EIP-106</a> proposed the block gas limit to be limited at <code>2**63 - 1</code>.</li> </ul> <h2 id="todo">TODO</h2> <ol> <li>Does the gas limit apply to the gas argument for call instructions?</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-07-31T00:00:00+00:00 2026-02-11T14:49:27+00:00 EOS Classichttps://github.com/eosclassicteam https://wg-eips.ritovision.com/1276/ <h2 id="simple-summary">Simple Summary</h2> <p>The average block times are increasing due to the factor of difficulty logic well known as difficulty bomb. This EIP proposes to eliminate the difficulty bomb forever and to reduce the block rewards with the Constantinople fork, the second part of the Metropolis fork.</p> <h2 id="abstract">Abstract</h2> <p>Starting with <code>CNSTNTNPL_FORK_BLKNUM</code> the client will calculate the difficulty without considering the current block number. Furthermore, block rewards will be adjusted to a base of 2 ETH, uncle and nephew rewards will be adjusted accordingly.</p> <h2 id="motivation">Motivation</h2> <p>Block time has been played a most important role on blockchain ecosystem, and it is being adjusted by the logic of mining difficulty calculation that is already implemented on the node client as a part of proof-of-work consensus. Last year, average block time rapidly increased due to the wrong design of difficulty logic that is meant to be changed on the part of Casper upgrade, however, implementation of casper has been delayed therefore it was inevitable to delay the difficulty bomb in order to prevent the significant delay of processing transactions on ethereum network.</p> <p>Despite of the successful hardfork to delay the activation of difficulty bomb, activation of the difficulty bomb is expected to happen again on the upcoming period before implementing casper protocol on ethereum network. Therefore, completely removing the difficulty bomb is the most proper way to response the block time increase instead of delaying it again.</p> <p>Also decreasing the block mining reward along with difficulty bomb removal is expected to help the growth of the stable ethereum ecosystem, right now ethereum dominates 92% of the total hashrate share of ethash based chains, and this corresponds to a tremendous level of energy consumption. As this energy consumption has a correlated environmental cost the network participants have an ethical obligation to ensure this cost is not higher than necessary. At this time, the most direct way to reduce this cost is to lower the block reward in order to limit the appeal of ETH mining. Unchecked growth in hashrate is also counterproductive from a security standpoint. Reducing the reward also decreases the likelihood of a miner driven chain split as Ethereum approaches proof-of-stake.</p> <h2 id="specification">Specification</h2> <h4 id="remove-exponential-component-of-difficulty-adjustment">Remove Exponential Component of Difficulty Adjustment</h4> <p>For the purposes of <code>calc_difficulty</code>, simply remove the exponential difficulty adjustment component, <code>epsilon</code>, i.e. the <code>int(2**((block.number // 100000) - 2))</code>.</p> <h4 id="adjust-block-uncle-and-nephew-rewards">Adjust Block, Uncle, and Nephew rewards</h4> <p>To ensure a constant Ether issuance, adjust the block reward to <code>new_block_reward</code>, where</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_block_reward = 2_000_000_000_000_000_000 if block.number &gt;= CNSTNTNPL_FORK_BLKNUM else block.reward</span></span></code></pre> <p>(2E18 wei, or 2,000,000,000,000,000,000 wei, or 2 ETH).</p> <p>Analogue, if an uncle is included in a block for <code>block.number &gt;= CNSTNTNPL_FORK_BLKNUM</code> such that <code>block.number - uncle.number = k</code>, the uncle reward is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_uncle_reward = (8 - k) * new_block_reward / 8</span></span></code></pre> <p>This is the existing pre-Constantinople formula for uncle rewards, simply adjusted with <code>new_block_reward</code>.</p> <p>The nephew reward for <code>block.number &gt;= CNSTNTNPL_FORK_BLKNUM</code> is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_nephew_reward = new_block_reward / 32</span></span></code></pre> <p>This is the existing pre-Constantinople formula for nephew rewards, simply adjusted with <code>new_block_reward</code>.</p> <h2 id="rationale">Rationale</h2> <p>This will completely remove the difficulty bomb on difficulty adjustment algorithm without delaying the difficulty bomb again, therefore it is possible to prevent network delay on the beginning of 2019.</p> <p>This EIP-1276 opposes directly the intent of <a href="https://wg-eips.ritovision.com/1234/">EIP-1234</a> which should be also considered in discussions.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is not forward compatible and introduces backwards incompatibilities in the difficulty calculation, as well as the block, uncle and nephew reward structure. Therefore, it should be included in a scheduled hardfork at a certain block number. It's suggested to include this EIP in the second Metropolis hard-fork, <em>Constantinople</em>.</p> <h2 id="test-cases">Test Cases</h2> <p>Test cases shall be created once the specification is to be accepted by the developers or implemented by the clients.</p> <h2 id="implementation">Implementation</h2> <p>The implementation shall be created once the specification is to be accepted by the developers or implemented by the clients.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-07-27T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/1352/ <h2 id="simple-summary">Simple Summary</h2> <p>Specify an Ethereum address range occupied by precompiles and future system contracts. Regular accounts and contracts cannot obtain such an address.</p> <h2 id="abstract">Abstract</h2> <p>The address range between 0x0000000000000000000000000000000000000000 and 0x000000000000000000000000000000000000ffff is reserved for precompiles and system contracts.</p> <h2 id="motivation">Motivation</h2> <p>This will simplify certain future features where unless this is implemented, several exceptions must be specified.</p> <h2 id="specification">Specification</h2> <p>The address range between 0x0000000000000000000000000000000000000000 and 0x000000000000000000000000000000000000ffff is reserved for precompiles and system contracts.</p> <p>Due to the extremely low probability (and lack of adequate testing possibilities) no explicit checks should be added to ensure that external transaction signing or the invoking of the <code>CREATE</code> instruction can result in a precompile address.</p> <h2 id="rationale">Rationale</h2> <p>N/A</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>No contracts on the main network have been created at the specified addresses. As a result it should pose no backwards compatibility problems.</p> <h2 id="test-cases">Test Cases</h2> <p>N/A</p> <h2 id="implementation">Implementation</h2> <p>N/A</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-07-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 SmeargleUsedFlyhttps://github.com/SmeargleUsedFly https://wg-eips.ritovision.com/1227/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP proposes to permanently disable the "difficulty bomb" and reset the block reward to pre-Byzantium levels.</p> <h2 id="abstract">Abstract</h2> <p>Starting with <code>FORK_BLKNUM</code> the client will calculate the difficulty without the additional exponential component. Furthermore, block rewards will be adjusted to a base of 5 ETH, uncle and nephew rewards will be adjusted accordingly.</p> <h2 id="motivation">Motivation</h2> <p>Due to the "difficulty bomb" (also known as the "ice age"), introduced in EIP <a href="https://wg-eips.ritovision.com/2/">#2</a>, an artificial exponential increase in difficulty until chain freeze, users may find it much more challenging to remain on the unforked chain after a hard-fork. This is a desirable effect of the ice age (in fact, its only stated purpose) in the case of a scheduled network upgrade, but is especially problematic when a hard-fork includes a controversial change.</p> <p>This situation has already been observed: during the Byzantium hard-fork users were given the "choice" of following the upgraded side of the chain or remaining on the original chain, the latter already experiencing block times greater than 30 seconds. In reality one will find that organizing a disperse and decentralized set of individuals to keep the original, soon-to-be-dead chain alive under such conditions impossible. This is exacerbated when a controversial change, such as EIP <a href="https://wg-eips.ritovision.com/649/">#649</a>, is merged in so close to the hard-fork date, as users cannot be organized to take an educated stance for or against the change on such short notice.</p> <p>Ultimately, the difficulty bomb serves but a single purpose: make it more difficult to keep the original chain alive after a hard-fork. This is unacceptable if the only way the community can make their voice heard is running/not running client software, and not through the EIP process, since they effectively have no choice and therefore no power. This EIP proposes to completely eliminate the difficulty bomb, returning some measure of power over Ethereum's governance process to the users, to the community.</p> <p>Given the controversy surrounding the directly relevant EIP <a href="https://wg-eips.ritovision.com/649/">#649</a>, the issuance should also be reset to pre-Byzantium levels. It may be reduced again at a later time via a new hard-fork, only this time users would actually have a meaningful choice in accepting the change or not. Note: the issuance reduction is not the focus of this proposal, and is optional; the defusing of the difficulty bomb is of primary concern.</p> <h2 id="specification">Specification</h2> <h4 id="remove-exponential-component-of-difficulty-adjustment">Remove Exponential Component of Difficulty Adjustment</h4> <p>For the purposes of <code>calc_difficulty</code>, simply remove the exponential difficulty adjustment component, <code>epsilon</code>, i.e. the <code>int(2**((block.number // 100000) - 2))</code>.</p> <h4 id="reset-block-uncle-and-nephew-rewards">Reset Block, Uncle, and Nephew rewards</h4> <p>To ensure a constant Ether issuance, adjust the block reward to <code>new_block_reward</code>, where</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_block_reward = 5_000_000_000_000_000_000 if block.number &gt;= FORK_BLKNUM else block.reward</span></span></code></pre> <p>(5E18 wei, or 5,000,000,000,000,000,000 wei, or 5 ETH).</p> <p>Analogue, if an uncle is included in a block for <code>block.number &gt;= FORK_BLKNUM</code> such that <code>block.number - uncle.number = k</code>, the uncle reward is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_uncle_reward = (8 - k) * new_block_reward / 8</span></span></code></pre> <p>This is the existing pre-Byzantium formula for uncle rewards, simply adjusted with <code>new_block_reward</code>.</p> <p>The nephew reward for <code>block.number &gt;= FORK_BLKNUM</code> is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>new_nephew_reward = new_block_reward / 32</span></span></code></pre> <p>This is the existing pre-Byzantium formula for nephew rewards, simply adjusted with <code>new_block_reward</code>.</p> <h2 id="rationale">Rationale</h2> <p>This will permanently, without further changes, disable the "ice age." It will also reset the block reward to pre-Byzantium levels. Both of these changes are specified similarly to EIP <a href="https://wg-eips.ritovision.com/649/">#649</a>, so they should require only minimal changes from client developers.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is not forward compatible and introduces backwards incompatibilities in the difficulty calculation, as well as the block, uncle and nephew reward structure. However, it may be controversial in nature among different sections of the userbase—the very problem this EIP is made to address. Therefore, it should not be included in a scheduled hardfork at a certain block number. It is suggested to implement this EIP in an isolated hard-fork before the second of the two Metropolis hard-forks.</p> <h2 id="test-cases">Test Cases</h2> <p>Forthcoming.</p> <h2 id="implementation">Implementation</h2> <p>Forthcoming.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-07-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Chaitanya Pottihttps://github.com/chaitanyapotti Partha Bhattacharyahttps://github.com/pb25193 https://wg-eips.ritovision.com/1261/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for Membership Verification Token(MVT).</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for Membership Verification Token within smart contracts(called entities). This standard provides basic functionality to track membership of individuals in certain on-chain ‘organizations’. This allows for several use cases like automated compliance, and several forms of governance and membership structures.</p> <p>We considered use cases of MVTs being assigned to individuals which are non-transferable and revocable by the owner. MVTs can represent proof of recognition, proof of membership, proof of right-to-vote and several such otherwise abstract concepts on the blockchain. The following are some examples of those use cases, and it is possible to come up with several others:</p> <ul> <li>Voting: Voting is inherently supposed to be a permissioned activity. So far, onchain voting systems are only able to carry out voting with coin balance based polls. This can now change and take various shapes and forms.</li> <li>Passport issuance, social benefit distribution, Travel permit issuance, Drivers licence issuance are all applications which can be abstracted into membership, that is belonging of an individual to a small set, recognized by some authority as having certain entitlements, without needing any individual specific information(right to welfare, freedom of movement, authorization to operate vehicles, immigration)</li> <li>Investor permissioning: Making regulatory compliance a simple on chain process. Tokenization of securities, that are streamlined to flow only to accredited addresses, tracing and certifying on chain addresses for AML purposes.</li> <li>Software licencing: Software companies like game developers can use the protocol to authorize certain hardware units(consoles) to download and use specific software(games)</li> </ul> <p>In general, an individual can have different memberships in their day to day life. The protocol allows for the creation of software that puts everything all at one place. Their identity can be verified instantly. Imagine a world where you don't need to carry a wallet full of identity cards (Passport, gym membership, SSN, Company ID etc) and organizations can easily keep track of all its members. Organizations can easily identify and disallow fake identities.</p> <p>Attributes are a huge part of ERC-1261 which help to store identifiable information regarding its members. Polls can make use of attributes to calculate the voterbase. E.g: Users should belong to USA entity and not belong to Washington state attribute to be a part of a poll.</p> <p>There will exist a mapping table that maps attribute headers to an array of all possible attributes. This is done in order to subdivide entities into subgroups which are exclusive and exhaustive. For example, header: blood group alphabet Array: [ o, a, b, ab ] header: blood group sign Array: [ +, - ]</p> <p>NOT an example of exclusive exhaustive: Header: video subscription Array: [ Netflix, HBO, Amazon ] Because a person is not necessitated to have EXACTLY one of the elements. He or she may have none or more than one.</p> <h2 id="motivation">Motivation</h2> <p>A standard interface allows any user, applications to work with any MVT on Ethereum. We provide for simple ERC-1261 smart contracts. Additional applications are discussed below.</p> <p>This standard is inspired from the fact that voting on the blockchain is done with token balance weights. This has been greatly detrimental to the formation of flexible governance systems on the blockchain, despite the tremendous governance potential that blockchains offer. The idea was to create a permissioning system that allows organizations to vet people once into the organization on the blockchain, and then gain immense flexibility in the kind of governance that can be carried out.</p> <p>We have also reviewed other Membership EIPs including EIP-725/735 Claim Registry. A significant difference between #735 claims and #1261 MVTs is information ownership. In #735 the Claim Holder owns any claims made about themselves. The problem with this is that there is no way for a Claim Issuer to revoke or alter a claim once it has been issued. While #735 does specify a removeClaim method, a malicious implementation could simply ignore that method call, because they own the claim.</p> <p>Imagine that SafeEmploy™, a background checking company, issues a claim about Timmy. The claim states that Timmy has never been convicted of any felonies. Timmy makes some bad decisions, and now that claim is no longer true. SafeEmploy™ executes removeClaim, but Timmy's #735 contract just ignores it, because Timmy wants to stay employed (and is crypto-clever). #1261 MVTs do not have this problem. Ownership of a badge/claim is entirely determined by the contract issuing the badges, not the one receiving them. The issuer is free to remove or change those badges as they see fit.</p> <p><strong>Trade-off between trustlessness and usability:</strong> To truly understand the value of the protocol, it is important to understand the trade-off we are treading on. The MVT contract allows the creator to revoke the token, and essentially confiscate the membership of the member in question. To some, this might seem like an unacceptable flaw, however this is a design choice, and not a flaw. The choice may seem to place a great amount of trust in the individuals who are managing the entity contract(entity owners). If the interests of the entity owner conflict with the interests of the members, the owner may resort to addition of fake addresses(to dominate consensus) or evicting members(to censor unfavourable decisions). At first glance this appears to be a major shortcomings, because the blockchain space is used to absolute removal of authority in most cases. Even the official definition of a dapp requires the absence of any party that manages the services provided by the application. However, the trust in entity owners is not misplaced, if it can be ensured that the interests of entity owners are aligned with the interests of members. Another criticism of such a system would be that the standard edge of blockchain intermediation - “you cannot bribe the system if you don’t know who to bribe” - no longer holds. It is possible to bribe an entity owner into submission, and get them to censor or fake votes. There are several ways to respond to this argument. First of all, all activities, such as addition of members, and removal of members can be tracked on the blockchain and traces of such activity cannot be removed. It is not difficult to build analytics tools to detect malicious activity(adding 100 fake members suddenly who vote in the direction/sudden removal of a number of members voting in a certain direction). Secondly, the entity owners’ power is limited to the addition and removal of members. This means that they cannot tamper any votes. They can only alter the counting system to include fake voters or remove real voters. Any sensible auditor can identify the malicious/victim addresses and create an open source audit tool to find out the correct results. The biggest loser in this attack will be the entity owner, who has a reputation to lose. Finally, one must understand why we are taking a step away from trustlessness in this trade-off. The answer is usability. Introducing a permissioning system expands the scope of products and services that can be delivered through the blockchain, while leveraging other aspects of the blockchain(cheap, immutable, no red-tape, secure). Consider the example of the driver licence issuing agency using the ERC-1300 standard. This is a service that simply cannot be deployed in a completely trustless environment. The introduction of permissioned systems expanded the scope of services on the blockchain to cover this particular service. Sure, they have the power to revoke a person’s licence for no reason. But will they? Who stands to lose the most, if the agency acts erratically? The agency itself. Now consider the alternative, the way licences(not necessarily only drivers licence, but say shareholder certificates and so on) are issued, the amount of time consumed, the complete lack of transparency. One could argue that if the legacy systems providing these services really wanted to carry out corruption and nepotism in the execution of these services, the present systems make it much easier to do so. Also, they are not transparent, meaning that there is no way to even detect if they act maliciously. All that being said, we are very excited to share our proposal with the community and open up to suggestions in this space.</p> <h2 id="specification">Specification</h2> <p>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> <p><strong>Every ERC-1261 compliant contract must implement the <code>ERC1261</code>, <code>ERC173</code> and <code>ERC165</code> interfaces</strong> (subject to "caveats" below):</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-1261 MVT Standard</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See https://github.com/ethereum/EIPs/blob/master/EIPS/./01261.md</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-comment"> The constructor should define the attribute set for this MVT.</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-keyword"> Note</span><span class="z-comment">: the ERC-165 identifier for this interface is 0x1d8362cf.</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC1261</span><span> {</span><span class="z-comment">/*</span><span class="z-comment"> is ERC173, ERC165 </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a token is assigned to a member.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Assigned</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint</span><span>[</span><span>]</span><span class="z-variable"> attributeIndexes</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a membership is revoked.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Revoked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a user forfeits his membership</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Forfeited</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a membership request is accepted</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ApprovedMembership</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint</span><span>[</span><span>]</span><span class="z-variable"> attributeIndexes</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when a membership is requested by an user</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> RequestedMembership</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when data of a member is modified.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Doesn&#39;t emit when a new membership is created and data is assigned.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> ModifiedAttributes</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> attributeIndex</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> attributeValueIndex</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Adds a new attribute (key, value) pair to the set of pre-existing attributes.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Adds a new attribute at the end of the array of attributes and maps it to `values`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Contract can set a max number of attributes and throw if limit is reached.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _name</span><span class="z-comment"> Name of the attribute which is to be added.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> values</span><span class="z-comment"> List of values of the specified attribute.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addAttributeSet</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _name</span><span>,</span><span class="z-support"> bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable"> values</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Modifies the attribute value of a specific attribute for a given `_to` address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Use appropriate checks for whether a user/admin can modify the data.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Best practice is to use onlyOwner modifier from ERC173.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address whose attribute is being modified.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _attributeIndex</span><span class="z-comment"> The index of attribute which is being modified.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _modifiedValueIndex</span><span class="z-comment"> The index of the new value which is being assigned to the user attribute.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> modifyAttributeByIndex</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _attributeIndex</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _modifiedValueIndex</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Requests membership from any address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if the `msg.sender` already has the token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The individual `msg.sender` can request for a membership if some existing criteria are satisfied.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When a membership is requested, this function emits the RequestedMembership event.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> dev can store the membership request and use `approveRequest` to assign membership later</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> dev can also oraclize the request to assign membership later</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _attributeIndexes</span><span class="z-comment"> the attribute data associated with the member.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This is an array which contains indexes of attributes.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> requestMembership</span><span>(</span><span class="z-support">uint</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _attributeIndexes</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> User can forfeit his membership.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if the `msg.sender` already doesn&#39;t have the token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The individual `msg.sender` can revoke his/her membership.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When the token is revoked, this function emits the Revoked event.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> forfeitMembership</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> payable</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Owner approves membership from any address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if the `_user` doesn&#39;t have a pending request.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if the `msg.sender` is not an owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Approves the pending request</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Make oraclize callback call this function</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When the token is assigned, this function emits the `ApprovedMembership` and `Assigned` events.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _user</span><span class="z-comment"> the user whose membership request will be approved.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approveRequest</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _user</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Owner discards membership from any address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if the `_user` doesn&#39;t have a pending request.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if the `msg.sender` is not an owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Discards the pending request</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Make oraclize callback call this function if criteria are not satisfied</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _user</span><span class="z-comment"> the user whose membership request will be discarded.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> discardRequest</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _user</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Assigns membership of an MVT from owner address to another address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if the member already has the token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if `_to` is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if the `msg.sender` is not an owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> The entity assigns the membership to each individual.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When the token is assigned, this function emits the Assigned event.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address to which the token is assigned.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _attributeIndexes</span><span class="z-comment"> The attribute data associated with the member.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> This is an array which contains indexes of attributes.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> assignTo</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint</span><span>[</span><span>]</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _attributeIndexes</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Only Owner can revoke the membership.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This removes the membership of the user.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if the `_from` is not an owner of the token.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if the `msg.sender` is not an owner.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if `_from` is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> When transaction is complete, this function emits the Revoked event.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _from</span><span class="z-comment"> The current owner of the MVT.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> revokeFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Queries whether a member is a current member of the organization.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> MVT&#39;s assigned to the zero address are considered invalid, and this</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> function throws for queries about the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> An address for whom to query the membership.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Whether</span><span class="z-comment"> the member owns the token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isCurrentMember</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Gets the value collection of an attribute.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Returns the values of attributes as a bytes32 array.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _name</span><span class="z-comment"> Name of the attribute whose values are to be fetched</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> values of attributes.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributeExhaustiveCollection</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _name</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the list of all past and present members.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Use this function along with isCurrentMember to find wasMemberOf() in Js.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> It can be calculated as present in getAllMembers() and !isCurrentMember().</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> List</span><span class="z-comment"> of addresses who have owned the token and currently own the token.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAllMembers</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>[</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the count of all current members.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Use this function in polls as denominator to get percentage of members voted.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> Count</span><span class="z-comment"> of current Members.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getCurrentMemberCount</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the list of all attribute names.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Returns the names of attributes as a bytes32 array.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> AttributeNames are stored in a bytes32 Array.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Possible values for each attributeName are stored in a mapping(attributeName =&gt; attributeValues).</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> AttributeName is bytes32 and attributeValues is bytes32[].</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Attributes of a particular user are stored in bytes32[].</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Which has a single attributeValue for each attributeName in an array.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Use web3.toAscii(data[0]).replace(/\u0000/g, &quot;&quot;) to convert to string in JS.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> names of attributes.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributeNames</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>[</span><span>]</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the attributes of `_to` address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Throws if `_to` is the zero address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Use web3.toAscii(data[0]).replace(/\u0000/g, &quot;&quot;) to convert to string in JS.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address whose current attributes are to be returned.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> attributes associated with `_to` address.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributes</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>[</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the `attribute` stored against `_to` address.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Finds the index of the `attribute`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Throws if the attribute is not present in the predefined attributes.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> Returns the attributeValue for the specified `attribute`.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _to</span><span class="z-comment"> The address whose attribute is requested.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _attributeIndex</span><span class="z-comment"> The attribute Index which is required.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> attribute value at the specified name.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAttributeByIndex</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _attributeIndex</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC173</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC165 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> This emits when ownership of a contract changes.</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> OwnershipTransferred</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> previousOwner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> newOwner</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Get the address of the owner</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> address of the owner.</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> owner</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Set the address of the new owner of the contract</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> _newOwner</span><span class="z-comment"> The address of the new owner of the contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferOwnership</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _newOwner</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC165</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Query if a contract implements an interface</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> interfaceID</span><span class="z-comment"> The interface identifier, as specified in ERC-165</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Interface identification is specified in ERC-165. This function</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> uses less than 30,000 gas.</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-comment"> `true` if the contract implements `interfaceID` and</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-comment"> `interfaceID` is not 0xffffffff, `false` otherwise</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <strong>metadata extension</strong> is OPTIONAL for ERC-1261 smart contracts (see "caveats", below). This allows your smart contract to be interrogated for its name and for details about the organization which your MV tokens represent.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @title</span><span class="z-comment"> ERC-1261 MVT Standard, optional metadata extension</span></span> <span class="giallo-l"><span class="z-comment">///</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> See https://github.com/ethereum/EIPs/blob/master/EIPS/./01261.md</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC1261Metadata</span><span class="z-comment"> /*</span><span class="z-comment"> is ERC1261 </span><span class="z-comment">*/</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> A descriptive name for a collection of MVTs in this contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> name</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _name</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> An abbreviated name for MVTs in this contract</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> symbol</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable z-parameter z-function"> _symbol</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This is the "ERC1261 Metadata JSON Schema" referenced above.</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">title</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Organization Metadata</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">properties</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Identifies the organization to which this MVT represents</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">description</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Describes the organization to which this MVT represents</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="caveats">Caveats</h3> <p>The 0.4.24 Solidity interface grammar is not expressive enough to document the ERC-1261 standard. A contract which complies with ERC-1261 MUST also abide by the following:</p> <ul> <li>Solidity issue #3412: The above interfaces include explicit mutability guarantees for each function. Mutability guarantees are, in order weak to strong: <code>payable</code>, implicit nonpayable, <code>view</code>, and <code>pure</code>. Your implementation MUST meet the mutability guarantee in this interface and you MAY meet a stronger guarantee. For example, a <code>payable</code> function in this interface may be implemented as nonpayble (no state mutability specified) in your contract. We expect a later Solidity release will allow your stricter contract to inherit from this interface, but a workaround for version 0.4.24 is that you can edit this interface to add stricter mutability before inheriting from your contract.</li> <li>Solidity issue #3419: A contract that implements <code>ERC1261Metadata</code> SHALL also implement <code>ERC1261</code>.</li> <li>Solidity issue #2330: If a function is shown in this specification as <code>external</code> then a contract will be compliant if it uses <code>public</code> visibility. As a workaround for version 0.4.24, you can edit this interface to switch to <code>public</code> before inheriting from your contract.</li> <li>Solidity issues #3494, #3544: Use of <code>this.*.selector</code> is marked as a warning by Solidity, a future version of Solidity will not mark this as an error.</li> </ul> <p><em>If a newer version of Solidity allows the caveats to be expressed in code, then this EIP MAY be updated and the caveats removed, such will be equivalent to the original specification.</em></p> <h2 id="rationale">Rationale</h2> <p>There are many potential uses of Ethereum smart contracts that depend on tracking membership. Examples of existing or planned MVT systems are Vault, a DAICO platform, and Stream, a security token framework. Future uses include the implementation of direct democracy, in-game memberships and badges, licence and travel document issuance, electronic voting machine trails, software licencing and many more.</p> <p><strong>MVT Word Choice:</strong></p> <p>Since the tokens are non transferable and revocable, they function like membership cards. Hence the word membership verification token.</p> <p><strong>Transfer Mechanism</strong></p> <p>MVTs can't be transferred. This is a design choice, and one of the features that distinguishes this protocol. Any member can always ask the issuer to revoke the token from an existing address and assign to a new address. One can think of the set of MVTs as identifying a user, and you cannot split the user into parts and have it be the same user, but you can transfer a user to a new private key.</p> <p><strong>Assign and Revoke mechanism</strong></p> <p>The assign and revoke functions' documentation only specify conditions when the transaction MUST throw. Your implementation MAY also throw in other situations. This allows implementations to achieve interesting results:</p> <ul> <li><strong>Disallow additional memberships after a condition is met</strong> — Sample contract available on GitHub</li> <li><strong>Blacklist certain address from receiving MV tokens</strong> — Sample contract available on GitHub</li> <li><strong>Disallow additional memberships after a certain time is reached</strong> — Sample contract available on GitHub</li> <li><strong>Charge a fee to user of a transaction</strong> — require payment when calling <code>assign</code> and <code>revoke</code> so that condition checks from external sources can be made</li> </ul> <p><strong>ERC-173 Interface</strong></p> <p>We chose Standard Interface for Ownership (ERC-173) to manage the ownership of a ERC-1261 contract.</p> <p>A future EIP/ Zeppelin may create a multi-ownable implementation for ownership. We strongly support such an EIP and it would allow your ERC-1261 implementation to implement <code>ERC1261Metadata</code>, or other interfaces by delegating to a separate contract.</p> <p><strong>ERC-165 Interface</strong></p> <p>We chose Standard Interface Detection (ERC-165) to expose the interfaces that a ERC-1261 smart contract supports.</p> <p>A future EIP may create a global registry of interfaces for contracts. We strongly support such an EIP and it would allow your ERC-1261 implementation to implement <code>ERC1261Metadata</code>, or other interfaces by delegating to a separate contract.</p> <p><strong>Gas and Complexity</strong> (regarding the enumeration extension)</p> <p>This specification contemplates implementations that manage a few and <em>arbitrarily large</em> numbers of MVTs. If your application is able to grow then avoid using for/while loops in your code. These indicate your contract may be unable to scale and gas costs will rise over time without bound</p> <p><strong>Privacy</strong></p> <p>Personal information: The protocol does not put any personal information on to the blockchain, so there is no compromise of privacy in that respect. Membership privacy: The protocol by design, makes it public which addresses are/aren’t members. Without making that information public, it would not be possible to independently audit governance activity or track admin(entity owner) activity.</p> <p><strong>Metadata Choices</strong> (metadata extension)</p> <p>We have required <code>name</code> and <code>symbol</code> functions in the metadata extension. Every token EIP and draft we reviewed (ERC-20, ERC-223, ERC-677, ERC-777, ERC-827) included these functions.</p> <p>We remind implementation authors that the empty string is a valid response to <code>name</code> and <code>symbol</code> if you protest to the usage of this mechanism. We also remind everyone that any smart contract can use the same name and symbol as <em>your</em> contract. How a client may determine which ERC-1261 smart contracts are well-known (canonical) is outside the scope of this standard.</p> <p>A mechanism is provided to associate MVTs with URIs. We expect that many implementations will take advantage of this to provide metadata for each MVT system. The URI MAY be mutable (i.e. it changes from time to time). We considered an MVT representing membership of a place, in this case metadata about the organization can naturally change.</p> <p>Metadata is returned as a string value. Currently this is only usable as calling from <code>web3</code>, not from other contracts. This is acceptable because we have not considered a use case where an on-blockchain application would query such information.</p> <p><em>Alternatives considered: put all metadata for each asset on the blockchain (too expensive), use URL templates to query metadata parts (URL templates do not work with all URL schemes, especially P2P URLs), multiaddr network address (not mature enough)</em></p> <p><strong>Community Consensus</strong></p> <p>We have been very inclusive in this process and invite anyone with questions or contributions into our discussion. However, this standard is written only to support the identified use cases which are listed herein.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>We have adopted <code>name</code> and <code>symbol</code> semantics from the ERC-20 specification.</p> <p>Example MVT implementations as of July 2018:</p> <ul> <li>Membership Verification Token(https://github.com/chaitanyapotti/MembershipVerificationToken)</li> </ul> <h2 id="test-cases">Test Cases</h2> <p>Membership Verification Token ERC-1261 Token includes test cases written using Truffle.</p> <h2 id="implementations">Implementations</h2> <p>Membership Verification Token ERC1261 -- a reference implementation</p> <ul> <li>MIT licensed, so you can freely use it for your projects</li> <li>Includes test cases</li> <li>Also available as a npm package - npm i membershipverificationtoken</li> </ul> <h2 id="references">References</h2> <p><strong>Standards</strong></p> <ol> <li>ERC-20 Token Standard. ./00020.md</li> <li>ERC-165 Standard Interface Detection. ./00165.md</li> <li>ERC-725/735 Claim Registry ./00725.md</li> <li>ERC-173 Owned Standard. ./00173.md</li> <li>JSON Schema. https://json-schema.org/</li> <li>Multiaddr. https://github.com/multiformats/multiaddr</li> <li>RFC 2119 Key words for use in RFCs to Indicate Requirement Levels. https://www.ietf.org/rfc/rfc2119.txt</li> </ol> <p><strong>Issues</strong></p> <ol> <li>The Original ERC-1261 Issue. https://github.com/ethereum/eips/issues/1261</li> <li>Solidity Issue #2330 -- Interface Functions are Axternal. https://github.com/ethereum/solidity/issues/2330</li> <li>Solidity Issue #3412 -- Implement Interface: Allow Stricter Mutability. https://github.com/ethereum/solidity/issues/3412</li> <li>Solidity Issue #3419 -- Interfaces Can't Inherit. https://github.com/ethereum/solidity/issues/3419</li> </ol> <p><strong>Discussions</strong></p> <ol> <li>Gitter #EIPs (announcement of first live discussion). https://gitter.im/ethereum/EIPs?at=5b5a1733d2f0934551d37642</li> <li>ERC-1261 (announcement of first live discussion). https://github.com/ethereum/eips/issues/1261</li> </ol> <p><strong>MVT Implementations and Other Projects</strong></p> <ol> <li>Membership Verification Token ERC-1261 Token. https://github.com/chaitanyapotti/MembershipVerificationToken</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-07-10T00:00:00+00:00 2026-02-11T14:48:25+00:00 Xiaoyu Wanghttps://github.com/wxygeek Bicong Wanghttps://github.com/Wangbicong https://wg-eips.ritovision.com/1207/ <h1 id="dauth-access-delegation-standard">DAuth Access Delegation Standard</h1> <h2 id="simple-summary">Simple Summary</h2> <p>DAuth is a standard interface for accessing authorization delegation between smart contracts and users.</p> <h2 id="abstract">Abstract</h2> <p>The DAuth protocol defines a set of standard API allowing identity delegations between smart contracts without the user's private key. Identity delegations include accessing and operating a user's data and assets contained in the delegated contracts.</p> <h2 id="motivation">Motivation</h2> <p>The inspiration for designing DAuth comes from OAuth protocol that is extensively used in web applications. But unlike the centralized authorization of OAuth, DAuth works in a distributed manner, thus providing much more reliability and generality.</p> <h2 id="specification">Specification</h2> <p><img src="https://wg-eips.ritovision.com/1207/./assets/rationale.png" alt="Rationale" /></p> <p><strong>Resource owner</strong>: the authorizer</p> <p><strong>Resource contract</strong>: the contract providing data and operators</p> <p><strong>API</strong>: the resource contract APIs that the grantee contract can invoke</p> <p><strong>Client contract</strong>: the grantee contract using authorization to access and operate the data</p> <p><strong>Grantee request</strong>: the client contract calls the resource contract with the authorizer authorization</p> <p><strong>AuthInfo</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">struct</span><span class="z-variable z-other"> AuthInfo</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> string</span><span>[</span><span>]</span><span class="z-variable z-other"> funcNames</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> expireAt</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Required - The struct contains user authorization information</p> <ul> <li><code>funcNames</code>: a list of function names callable by the granted contract</li> <li><code>expireAt</code>: the authorization expire timestamp in seconds</li> </ul> <p><strong>userAuth</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-entity z-name">mapping</span><span>(</span><span class="z-variable">address</span><span class="z-storage z-type"> =&gt;</span><span class="z-entity z-name"> mapping</span><span>(</span><span class="z-variable">address</span><span class="z-storage z-type"> =&gt;</span><span class="z-variable z-other"> AuthInfo</span><span>)</span><span>)</span><span class="z-variable z-other"> userAuth</span><span>;</span></span></code></pre> <p>Required - userAuth maps (authorizer address, grantee contract address) pair to the user’s authorization AuthInfo object</p> <p><strong>callableFuncNames</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">string</span><span>[</span><span>]</span><span class="z-variable z-other"> callableFuncNames</span><span>;</span></span></code></pre> <p>Required - All methods that are allowed other contracts to call</p> <ul> <li>The callable function MUST verify the grantee’s authorization</li> </ul> <p><strong>updateCallableFuncNames</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> updateCallableFuncNames</span><span>(</span><span class="z-variable">string</span><span class="z-variable"> _invokes</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span></code></pre> <p>Optional - Update the callable function list for the client contract by the resource contract's administrator</p> <ul> <li><code>_invokes</code>: the invoke methods that the client contract can call</li> <li>return: Whether the callableFuncNames is updated or not</li> <li>This method MUST return success or throw, no other outcomes can be possible</li> </ul> <p><strong>verify</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> verify</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _authorizer</span><span>,</span><span class="z-variable"> string</span><span class="z-variable"> _invoke</span><span>)</span><span class="z-entity z-name"> internal</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span></code></pre> <p>Required - check the invoke method authority for the client contract</p> <ul> <li><code>_authorizer</code>: the user address that the client contract agents</li> <li><code>_invoke</code>: the invoke method that the client contract wants to call</li> <li>return: Whether the grantee request is authorized or not</li> <li>This method MUST return success or throw, no other outcomes can be possible</li> </ul> <p><strong>grant</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> grant</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _grantee</span><span>,</span><span class="z-variable"> string</span><span class="z-variable"> _invokes</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> _expireAt</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span></code></pre> <p>Required - delegate a client contract to access the user's resource</p> <ul> <li><code>_grantee</code>: the client contract address</li> <li><code>_invokes</code>: the callable methods that the client contract can access. It is a string which contains all function names split by spaces</li> <li><code>_expireAt</code>: the authorization expire timestamp in seconds</li> <li>return: Whether the grant is successful or not</li> <li>This method MUST return success or throw, no other outcomes can be possible</li> <li>A successful grant MUST fire the Grant event(defined below)</li> </ul> <p><strong>regrant</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> regrant</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _grantee</span><span>,</span><span class="z-variable"> string</span><span class="z-variable"> _invokes</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> _expireAt</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span></code></pre> <p>Optional - alter a client contract's delegation</p> <p><strong>revoke</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revoke</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _grantee</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span></code></pre> <p>Required - delete a client contract's delegation</p> <ul> <li><code>_grantee</code>: the client contract address</li> <li>return: Whether the revoke is successful or not</li> <li>A successful revoke MUST fire the Revoke event(defined below).</li> </ul> <p><strong>Grant</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Grant</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> _authorizer</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> _grantee</span><span>,</span><span class="z-variable z-other"> string</span><span class="z-variable z-other"> _invokes</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> _expireAt</span><span>)</span><span>;</span></span></code></pre> <ul> <li>This event MUST trigger when the authorizer grant a new authorization when <code>grant</code> or <code>regrant</code> processes successfully</li> </ul> <p><strong>Revoke</strong></p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Revoke</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> _authorizer</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> _grantee</span><span>)</span><span>;</span></span></code></pre> <ul> <li>This event MUST trigger when the authorizer revoke a specific authorization successfully</li> </ul> <p><strong>Callable Resource Contract Functions</strong></p> <p>All public or external functions that are allowed the grantee to call MUST use overload to implement two functions: The First one is the standard method that the user invokes directly, the second one is the grantee methods of the same function name with one more authorizer address parameter.</p> <p>Example:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _spender</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _approve</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> _spender</span><span>,</span><span class="z-variable z-other"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _spender</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _authorizer</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> verify</span><span>(</span><span class="z-variable z-other">_authorizer</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">approve</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> _approve</span><span>(</span><span class="z-variable z-other">_authorizer</span><span>,</span><span class="z-variable z-other"> _spender</span><span>,</span><span class="z-variable z-other"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> _approve</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> sender</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _spender</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> internal</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> allowed</span><span>[</span><span class="z-variable z-other">sender</span><span>]</span><span>[</span><span class="z-variable z-other">_spender</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> _value</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> _spender</span><span>,</span><span class="z-variable z-other"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p><strong>Current Limitations</strong></p> <p>The current design of many smart contracts only considers the user invokes the smart contract functions by themselves using the private key. However, in some case, the user wants to delegate other client smart contracts to access and operate their data or assets in the resource smart contract. There isn’t a common protocol to provide a standard delegation approach.</p> <p><strong>Rationale</strong></p> <p>On the Ethereum platform, all storage is transparent and the <code>msg.sender</code> is reliable. Therefore, the DAuth don't need an <code>access_token</code> like OAuth. DAuth just recodes the users' authorization for the specific client smart contract's address. It is simple and reliable on the Ethereum platform.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces no backward compatibility issues. In the future, the new version protocol has to keep these interfaces.</p> <h2 id="implementation">Implementation</h2> <p>Following is the DAuth Interface implementation. Furthermore, the example implementations of EIP20 Interface and ERC-DAuth Interface are also provided. Developers can easily implement their own contracts with ERC-DAuth Interface and other EIP.</p> <ul> <li> <p>ERC-DAuth Interface implementation is available at:</p> <p>https://github.com/DIA-Network/ERC-DAuth/blob/master/ERC-DAuth-Interface.sol</p> </li> <li> <p>Example implementation with EIP20 Interface and ERC-DAuth Interface is available at:</p> <p>https://github.com/DIA-Network/ERC-DAuth/blob/master/eip20-dauth-example/EIP20DAuth.sol</p> </li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-07-01T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jeff Huangjeffishjeff@gmail.com Min Zucrawlregister@gmail.com https://wg-eips.ritovision.com/1203/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for multi-class tokens (MCTs).</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for MCTs within smart contracts. This standard provides basic functionality to track, transfer, and convert MCTs.</p> <h2 id="motivation">Motivation</h2> <p>This standard is heavily inspired by ERC-20 Token Standard and ERC-721 Non-Fungible Token Standard. However, whereas these standards are chiefly concerned with representation of items/value in a single class, fungible or note, this proposed standard focus on that of a more complexed, multi-class system. It is fair to think of MCTs as a hybrid of fungible tokens (FT) and non-fungible tokens (NFTs), that is tokens are fungible within the same class but non-fungible with that from a different class. And conversions between classes may be optionally supported.</p> <p>MCTs are useful in representing various structures with heterogeneous components, such as:</p> <ul> <li> <p><strong>Abstract Concepts:</strong> A company may have different classes of stocks (e.g. senior preferred, junior preferred, class A common, class B common) that together make up its outstanding equities. A shareholder's position of such company composites of zero or more shares in each class.</p> </li> <li> <p><strong>Virtual Items:</strong> A sandbox computer game may have many types of resources (e.g. rock, wood, berries, cows, meat, knife, etc.) that together make up that virtual world. A player's inventory has any combination and quantity of these resources</p> </li> <li> <p><strong>Physical Items:</strong> A supermarket may have many SKUs it has available for purchase (e.g. eggs, milk, beef jerky, beer, etc.). Things get added or removed from a shopper's cart as it moves down the aisle.</p> </li> </ul> <p>It's sometimes possible, especially with regard to abstract concepts or virtual items, to convert from one class to another, at a specified conversion ratio. When it comes to physical items, such conversion essentially is the implementation of bartering. Though it might generally be easier to introduce a common intermediary class, i.e. money.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _spender</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC1203</span><span class="z-storage"> is</span><span class="z-entity z-name"> ERC20</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fullyDilutedTotalSupply</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fullyDilutedBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fullyDilutedAllowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> convert</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _fromClass</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toClass</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _class</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _spender</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _class</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Convert</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _fromClass</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _toClass</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="erc-20-methods-and-events-fully-compatible">ERC-20 Methods and Events (fully compatible)</h3> <p>Please see <a href="https://wg-eips.ritovision.com/20/">ERC-20 Token Standard</a> for detailed specifications. Do note that these methods and events only work on the "default" class of an MCT.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _spender</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span></code></pre><h3 id="tracking-and-transferring">Tracking and Transferring</h3> <p><strong>totalSupply</strong></p> <p>Returns the total number of tokens in the specified <code>_class</code></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <p><strong>balanceOf</strong></p> <p>Returns the number of tokens of a specified <code>_class</code> that the <code>_owner</code> has</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <p><strong>transfer</strong></p> <p>Transfer <code>_value</code> tokens of <code>_class</code> to address specified by <code>_to</code>, return <code>true</code> if successful</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre> <p><strong>approve</strong></p> <p>Grant <code>_spender</code> the right to transfer <code>_value</code> tokens of <code>_class</code>, return <code>true</code> if successful</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre> <p><strong>allowance</strong></p> <p>Return the number of tokens of <code>_class</code> that <code>_spender</code> is authorized to transfer on the behalf of <code>_owner</code></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <p><strong>transferFrom</strong></p> <p>Transfer <code>_value</code> tokens of <code>_class</code> from address specified by <code>_from</code> to address specified by <code>_to</code> as previously approved, return <code>true</code> if successful</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _class</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre> <p><strong>Transfer</strong></p> <p>Triggered when tokens are transferred or created, including zero value transfers</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _class</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span></code></pre> <p><strong>Approval</strong></p> <p>Triggered on successful <code>approve</code></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _spender</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _class</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span></code></pre><h3 id="conversion-and-dilution">Conversion and Dilution</h3> <p><strong>fullyDilutedTotalSupply</strong></p> <p>Return the total token supply as if all converted to the lowest common denominator class</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fullyDilutedTotalSupply</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <p><strong>fullyDilutedBalanceOf</strong></p> <p>Return the total token owned by <code>_owner</code> as if all converted to the lowest common denominator class</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fullyDilutedBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <p><strong>fullyDilutedAllowance</strong></p> <p>Return the total token <code>_spender</code> is authorized to transfer on behalf of <code>_owner</code> as if all converted to the lowest common denominator class</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> fullyDilutedAllowance</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _spender</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span></code></pre> <p><strong>convert</strong></p> <p>Convert <code>_value</code> of <code>_fromClass</code> to <code>_toClass</code>, return <code>true</code> if successful</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> convert</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _fromClass</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _toClass</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _value</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre> <p><strong>Conversion</strong></p> <p>Triggered on successful <code>convert</code></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Conversion</span><span>(</span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _fromClass</span><span>, </span><span class="z-support">uint256</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _toClass</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _value</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This standard purposely extends ERC-20 Token Standard so that new MCTs following or existing ERC-20 tokens extending this standard are fully compatible with current wallets and exchanges. In addition, new methods and events are kept as closely to ERC-20 conventions as possible for ease of adoption.</p> <p>We have considered alternative implementations to support the multi-class structure, as discussed below, and we found current token standards incapable or inefficient in deal with such structures.</p> <p><strong>Using multiple ERC-20 tokens</strong></p> <p>It is certainly possible to create an ERC-20 token for each class, and a separate contract to coordinate potential conversions, but the short coming in this approach is clearly evident. The rationale behind this standard is to have a single contract to manage multiple classes of tokens.</p> <p><strong>Shoehorning ERC-721 token</strong></p> <p>Treating each token as unique, the non-fungible token standard offers maximum representational flexibility arguably at the expense of convenience. The main challenge of using ERC-721 to represent multi-class token is that separate logic is required to keep track of which tokens belongs to which class, a hacky and unnecessary endeavor.</p> <p><strong>Using ERC-1178 token</strong></p> <p>We came across ERC-1178 as we were putting final touches on our own proposal. The two ERCs look very similar on the surface but we believe there're a few key advantages this one has over ERC-1178.</p> <ul> <li>ERC-1178 offers no backward compatibility whereas this proposal is an extension of ERC-20 and therefore fully compatible with all existing wallets and exchanges</li> <li>By the same token, existing ERC-20 contracts can extend themselves to adopt this standard and support additional classes without affecting their current behaviors</li> <li>This proposal introduces the concept of cross class conversion and dilution, making each token class integral part of a whole system rather than many silos</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is fully compatible with the mandatory methods of ERC20 Token Standard so long as the implementation includes a "lowest common denominator" class, which may be class B common/gold coin/money in the abstract/virtual/physical examples above respectively. Where it is not possible to implement such class, then the implementation should specify a default class for tracking or transferring unless otherwise specified, e.g. US dollar is transferred unless other currency is explicitly specified.</p> <p>We find it contrived to require the optional methods of ERC20 Token Standard, <code>name()</code>, <code>symbol()</code>, and <code>decimals()</code>, but developers are certainly free to implement these as they wish.</p> <h2 id="test-cases">Test Cases</h2> <p>The repository at <a rel="external" href="https://github.com/jeffishjeff/ERC-1203">jeffishjeff/ERC-1203</a> contains the <a rel="external" href="https://github.com/jeffishjeff/ERC-1203/blob/master/token.test.js">sample test cases</a>.</p> <h2 id="implementation">Implementation</h2> <p>The repository at <a rel="external" href="https://github.com/jeffishjeff/ERC-1203">jeffishjeff/ERC-1203</a> contains the <a rel="external" href="https://github.com/jeffishjeff/ERC-1203/blob/master/token.sol">sample implementation</a>.</p> <h2 id="references">References</h2> <ul> <li>ERC-20 Token Standard. ./00020.md</li> <li>ERC-721 Non-Fungible Token Standard. ./00721.md</li> <li>ERC-1178 Multi-class Token Standard. ./01178.md</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-06-24T00:00:00+00:00 2026-02-11T14:49:27+00:00 Simon Jentzschsimon.jentzsch@slock.it Christoph Jentzschchristoph.jentzsch@slock.it https://wg-eips.ritovision.com/1186/ <h2 id="simple-summary">Simple Summary</h2> <p>One of the great features of Ethereum is the fact, that you can verify all data of the state. But in order to allow verification of accounts outside the client, we need an additional function delivering us the required proof. These proofs are important to secure Layer2-Technologies.</p> <h2 id="abstract">Abstract</h2> <p>Ethereum uses a <a rel="external" href="https://github.com/ethereum/eth-wiki/blob/master/fundamentals/patricia-tree.md">Merkle Tree</a> to store the state of accounts and their storage. This allows verification of each value by simply creating a Merkle Proof. But currently, the standard RPC-Interface does not give you access to these proofs. This EIP suggests an additional RPC-Method, which creates Merkle Proofs for Accounts and Storage Values.</p> <p>Combined with a stateRoot (from the blockheader) it enables offline verification of any account or storage-value. This allows especially IOT-Devices or even mobile apps which are not able to run a light client to verify responses from an untrusted source only given a trusted blockhash.</p> <h2 id="motivation">Motivation</h2> <p>In order to create a MerkleProof access to the full state db is required. The current RPC-Methods allow an application to access single values (<code>eth_getBalance</code>,<code>eth_getTransactionCount</code>,<code>eth_getStorageAt</code>,<code>eth_getCode</code>), but it is impossible to read the data needed for a MerkleProof through the standard RPC-Interface. (There are implementations using leveldb and accessing the data via filesystems, but this can not be used for production systems since it requires the client to be stopped first - See https://github.com/zmitton/eth-proof)</p> <p>Today MerkleProofs are already used internally. For example, the <a rel="external" href="https://github.com/zsfelfoldi/go-ethereum/wiki/Light-Ethereum-Subprotocol-%28LES%29#on-demand-data-retrieval">Light Client Protocol</a> supports a function creating MerkleProof, which is used in order to verify the requested account or storage-data.</p> <p>Offering these already existing function through the RPC-Interface as well would enable Applications to store and send these proofs to devices which are not directly connected to the p2p-network and still are able to verify the data. This could be used to verify data in mobile applications or IOT-devices, which are currently only using a remote client.</p> <h2 id="specification">Specification</h2> <p>As Part of the eth-Module, an additional Method called <code>eth_getProof</code> should be defined as follows:</p> <h4 id="eth-getproof">eth_getProof</h4> <p>Returns the account- and storage-values of the specified account including the Merkle-proof.</p> <h5 id="parameters">Parameters</h5> <ol> <li><code>DATA</code>, 20 Bytes - address of the account.</li> <li><code>ARRAY</code>, 32 Bytes - array of storage-keys which should be proofed and included. See <a rel="external" href="https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getstorageat"><code>eth_getStorageAt</code></a></li> <li><code>QUANTITY|TAG</code> - integer block number, or the string <code>"latest"</code> or <code>"earliest"</code>, see the <a rel="external" href="https://github.com/ethereum/wiki/wiki/JSON-RPC#the-default-block-parameter">default block parameter</a></li> </ol> <h5 id="returns">Returns</h5> <p><code>Object</code> - A account object:</p> <ul> <li> <p><code>balance</code>: <code>QUANTITY</code> - the balance of the account. See <a rel="external" href="https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_getbalance"><code>eth_getBalance</code></a></p> </li> <li> <p><code>codeHash</code>: <code>DATA</code>, 32 Bytes - hash of the code of the account. For a simple Account without code it will return <code>"0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"</code></p> </li> <li> <p><code>nonce</code>: <code>QUANTITY</code>, - nonce of the account. See <a rel="external" href="https://github.com/ethereum/wiki/wiki/JSON-RPC#eth_gettransactioncount"><code>eth_getTransactionCount</code></a></p> </li> <li> <p><code>storageHash</code>: <code>DATA</code>, 32 Bytes - SHA3 of the StorageRoot. All storage will deliver a MerkleProof starting with this rootHash.</p> </li> <li> <p><code>accountProof</code>: <code>ARRAY</code> - Array of rlp-serialized MerkleTree-Nodes, starting with the stateRoot-Node, following the path of the SHA3 (address) as key.</p> </li> <li> <p><code>storageProof</code>: <code>ARRAY</code> - Array of storage-entries as requested. Each entry is an object with these properties:</p> <ul> <li><code>key</code>: <code>QUANTITY</code> - the requested storage key</li> <li><code>value</code>: <code>QUANTITY</code> - the storage value</li> <li><code>proof</code>: <code>ARRAY</code> - Array of rlp-serialized MerkleTree-Nodes, starting with the storageHash-Node, following the path of the SHA3 (key) as path.</li> </ul> </li> </ul> <h5 id="example">Example</h5> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eth_getProof</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7F0d15C7FAae65896648C8273B6d7E43f58Fa842</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span> [</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">latest</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The result will look like this:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">accountProof</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf90211a...0701bc80</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf90211a...0d832380</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf90211a...5fb20c80</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf90211a...0675b80</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf90151a0...ca08080</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">balance</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">codeHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xc5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">nonce</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">storageHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">storageProof</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">key</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">proof</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf90211a...0701bc80</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xf90211a...0d832380</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">value</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>This one Method actually returns 3 different important data points:</p> <ol> <li>The 4 fields of an account-object as specified in the yellow paper <code>[nonce, balance, storageHash, codeHash ]</code>, which allows storing a hash of the account-object in order to keep track of changes.</li> <li>The MerkleProof for the account starting with a stateRoot from the specified block.</li> <li>The MerkleProof for each requested storage entry starting with a storageHash from the account.</li> </ol> <p>Combining these in one Method allows the client to work very efficient since the required data are already fetched from the db.</p> <h3 id="proofs-for-non-existent-values">Proofs for non existent values</h3> <p>In case an address or storage-value does not exist, the proof needs to provide enough data to verify this fact. This means the client needs to follow the path from the root node and deliver until the last matching node. If the last matching node is a branch, the proof value in the node must be an empty one. In case of leaf-type, it must be pointing to a different relative-path in order to proof that the requested path does not exist.</p> <h3 id="possible-changes-to-be-discussed">possible Changes to be discussed:</h3> <ul> <li>instead of providing the blocknumber maybe the blockhash would be better since it would allow proofs of uncles-states.</li> <li>in order to reduce data, the account-object may only provide the <code>accountProof</code> and <code>storageProof</code>. The Fields <code>balance</code>, <code>nonce</code>, <code>storageHash</code> and <code>codeHash</code> could be taken from the last Node in the proof by deserializing it.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Since this only adds a new Method there are no issues with Backwards Compatibility.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO: Tests still need to be implemented, but the core function creating the proof already exists inside the clients and are well tested.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-06-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Albert Chonachon@stanford.edu https://wg-eips.ritovision.com/1178/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for multi-class fungible tokens.</p> <h2 id="abstract">Abstract</h2> <p>This standard allows for the implementation of a standard API for multi-class fungible tokens (henceforth referred to as "MCFTs") within smart contracts. This standard provides basic functionality to track and transfer ownership of MCFTs.</p> <h2 id="motivation">Motivation</h2> <p>Currently, there is no standard to support tokens that have multiple classes. In the real world, there are many situations in which defining distinct classes of the same token would be fitting (e.g. distinguishing between preferred/common/restricted shares of a company). Yet, such nuance cannot be supported in today's token standards. An ERC-20 token contract defines tokens that are all of one class while an ERC-721 token contract creates a class (defined by token_id) for each individual token. The ERC-1178 token standard proposes a new standard for creating multiple classes of tokens within one token contract.</p> <blockquote> <p>Aside: In theory, while it is possible to implement tokens with classes using the properties of token structs in ERC-721 tokens, gas costs of implementing this in practice are prohibitive for any non-trivial application.</p> </blockquote> <h2 id="specification">Specification</h2> <h3 id="erc-20-compatibility-partial">ERC-20 Compatibility (partial)</h3> <p><strong>name</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> name</span><span>(</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable"> name</span><span>)</span></span></code></pre> <p><em>OPTIONAL - It is recommended that this method is implemented for enhanced usability with wallets and exchanges, but interfaces and other contracts MUST NOT depend on the existence of this method.</em></p> <p>Returns the name of the aggregate collection of MCFTs managed by this contract. - e.g. <code>"My Company Tokens"</code>.</p> <p><strong>class name</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> className</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> classId</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable"> name</span><span>)</span></span></code></pre> <p><em>OPTIONAL - It is recommended that this method is implemented for enhanced usability with wallets and exchanges, but interfaces and other contracts MUST NOT depend on the existence of this method.</em></p> <p>Returns the name of the class of MCFT managed by this contract. - e.g. <code>"My Company Preferred Shares Token"</code>.</p> <p><strong>symbol</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> symbol</span><span>(</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable"> symbol</span><span>)</span></span></code></pre> <p><em>OPTIONAL - It is recommend that this method is implemented for enhanced usability with wallets and exchanges, but interfaces and other contracts MUST NOT depend on the existence of this method.</em></p> <p>Returns a short string symbol referencing the entire collection of MCFT managed in this contract. e.g. "MUL". This symbol SHOULD be short (3-8 characters is recommended), with no whitespace characters or new-lines and SHOULD be limited to the uppercase latin alphabet (i.e. the 26 letters used in English).</p> <p><strong>totalSupply</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> totalSupply</span><span>)</span></span></code></pre> <p>Returns the total number of all MCFTs currently tracked by this contract.</p> <p><strong>individualSupply</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> individualSupply</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _classId</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> individualSupply</span><span>)</span></span></code></pre> <p>Returns the total number of MCFTs of class <code>_classId</code> currently tracked by this contract.</p> <p><strong>balanceOf</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _classId</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> balance</span><span>)</span></span></code></pre> <p>Returns the number of MCFTs of token class <code>_classId</code> assigned to address <code>_owner</code>.</p> <p><strong>classesOwned</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> classesOwned</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _owner</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>[</span><span>]</span><span class="z-variable"> classes</span><span>)</span></span></code></pre> <p>Returns an array of <code>_classId</code>'s of MCFTs that address <code>_owner</code> owns in the contract.</p> <blockquote> <p>NOTE: returning an array is supported by <code>pragma experimental ABIEncoderV2</code></p> </blockquote> <h2 id="basic-ownership">Basic Ownership</h2> <p><strong>approve</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> quantity</span><span>)</span></span></code></pre> <p>Grants approval for address <code>_to</code> to take possession <code>quantity</code> amount of the MCFT with ID <code>_classId</code>. This method MUST <code>throw</code> if <code>balanceOf(msg.sender, _classId) &lt; quantity</code>, or if <code>_classId</code> does not represent an MCFT class currently tracked by this contract, or if <code>msg.sender == _to</code>.</p> <p>Only one address can "have approval" at any given time for a given address and <code>_classId</code>. Calling <code>approve</code> with a new address and <code>_classId</code> revokes approval for the previous address and <code>_classId</code>. Calling this method with 0 as the <code>_to</code> argument clears approval for any address and the specified <code>_classId</code>.</p> <p>Successful completion of this method MUST emit an <code>Approval</code> event (defined below) unless the caller is attempting to clear approval when there is no pending approval. In particular, an Approval event MUST be fired if the <code>_to</code> address is zero and there is some outstanding approval. Additionally, an Approval event MUST be fired if <code>_to</code> is already the currently approved address and this call otherwise has no effect. (i.e. An <code>approve()</code> call that "reaffirms" an existing approval MUST fire an event.)</p> <!-- ActionPrior State_to addressNew StateEventClear unset approvalClear0ClearNoneSet new approvalClearXSet to XApproval(owner, X, _classId)Change approvalSet to XYSet to YApproval(owner, Y, _classId)Reaffirm approvalSet to XXSet to XApproval(owner, X, _classId)Clear approvalSet to X0ClearApproval(owner, 0, _classId) Note: ANY change of ownership of an MCFT – whether directly through the `transfer` and `transferFrom` methods defined in this interface, or through any other mechanism defined in the conforming contract – MUST clear any and all approvals for the transferred MCFT. The implicit clearing of approval via ownership transfer MUST also fire the event `Approval(0, _classId)` if there was an outstanding approval. (i.e. All actions that transfer ownership must emit the same Approval event, if any, as would emitted by calling `approve(0, _classId)`.)--> <p><strong>transfer</strong></p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _classId</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> quantity</span><span>)</span></span></code></pre> <p>Assigns the ownership of <code>quantity</code> MCFT's with ID <code>_classId</code> to <code>_to</code> if and only if <code>quantity == balanceOf(msg.sender, _classId)</code>. A successful transfer MUST fire the <code>Transfer</code> event (defined below).</p> <p>This method MUST transfer ownership to <code>_to</code> or <code>throw</code>, no other outcomes can be possible. Reasons for failure include (but are not limited to):</p> <ul> <li><code>msg.sender</code> is not the owner of <code>quantity</code> amount of tokens of <code>_classId</code>'s.</li> <li><code>_classId</code> does not represent an MCFT class currently tracked by this contract</li> </ul> <p>A conforming contract MUST allow the current owner to "transfer" a token to themselves, as a way of affirming ownership in the event stream. (i.e. it is valid for <code>_to == msg.sender</code> if <code>balanceOf(msg.sender, _classId) &gt;= balance</code>.) This "no-op transfer" MUST be considered a successful transfer, and therefore MUST fire a <code>Transfer</code> event (with the same address for <code>_from</code> and <code>_to</code>).</p> <h2 id="advanced-ownership-and-exchange">Advanced Ownership and Exchange</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approveForToken</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> classIdHeld</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> quantityHeld</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> classIdWanted</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> quantityWanted</span><span>)</span></span></code></pre> <p>Allows holder of one token to allow another individual (or the smart contract itself) to approve the exchange of their tokens of one class for tokens of another class at their specified exchange rate (see sample implementation for more details). This is equivalent to posting a bid in a marketplace.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> exchange</span><span>(</span><span class="z-support">address</span><span class="z-variable"> to</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> classIdPosted</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> quantityPosted</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> classIdWanted</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> quantityWanted</span><span>)</span></span></code></pre> <p>Allows an individual to fill an existing bid (see above function) and complete the exchange of their tokens of one class for another. In the sample implementation, this function call should fail unless the callee has already approved the contract to transfer their tokens. Of course, it is possible to create an implementation where calling this function implicitly assumes approval and the transfer is completed in one step.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-support">address</span><span> from</span><span>,</span><span class="z-support"> address</span><span> to</span><span>,</span><span class="z-support"> uint256</span><span> classId</span><span>)</span></span></code></pre> <p>Allows a third party to initiate a transfer of tokens from <code>from</code> to <code>to</code> assuming the approvals have been granted.</p> <h2 id="events">Events</h2> <p><strong>Transfer</strong></p> <p>This event MUST trigger when MCFT ownership is transferred via any mechanism.</p> <p>Additionally, the creation of new MCFTs MUST trigger a Transfer event for each newly created MCFTs, with a <code>_from</code> address of 0 and a <code>_to</code> address matching the owner of the new MCFT (possibly the smart contract itself). The deletion (or burn) of any MCFT MUST trigger a Transfer event with a <code>_to</code> address of 0 and a <code>_from</code> address of the owner of the MCFT (now former owner!).</p> <p>NOTE: A Transfer event with <code>_from == _to</code> is valid. See the <code>transfer()</code> documentation for details.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _classId</span><span>)</span></span></code></pre> <p><strong>Approval</strong> This event MUST trigger on any successful call to <code>approve(_to, _classId, quantity)</code> (unless the caller is attempting to clear approval when there is no pending approval).</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _owner</span><span>, </span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> _approved</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> _classId</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="current-limitations">Current Limitations</h3> <p>The design of this project was motivated when I tried to create different classes of fungible ERC-721 tokens (an oxymoron) but ran into gas limits from having to create each tokens individually and maintain them in an efficient data structure for access. Using the maximum gas amount one can send with a transaction on Metamask (a popular web wallet), I was only able to create around 46 ERC-721 tokens before exhausting all gas. This experience motivated the creation of the multi-class fungible token standard.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Adoption of the MCFT standard proposal would not pose backwards compatibility issues as it defines a new standard for token creation. This standard follows the semantics of ERC-721 as closely as possible, but can't be entirely compatible with it due to the fundamental differences between multi-class fungible and non-fungible tokens. For example, the <code>ownerOf</code>, <code>takeOwnership</code>, and <code>tokenOfOwnerByIndex</code> methods in the ERC-721 token standard cannot be implemented in this standard. Furthermore, the function arguments to <code>balanceOf</code>, <code>approve</code>, and <code>transfer</code> differ as well.</p> <h2 id="implementation">Implementation</h2> <p>A sample implementation can be found <a rel="external" href="https://github.com/achon22/ERC-1178/blob/master/erc1178-sample.sol">here</a></p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-06-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jet Limhttps://github.com/Nitro888 https://wg-eips.ritovision.com/1175/ <h1 id="all-tokens-go-to-heaven">All tokens go to heaven</h1> <h2 id="simple-summary">Simple Summary</h2> <p>Make wallets and shops created from certified contracts make erc20 tokens easy to use for commerce.</p> <p><img src="https://wg-eips.ritovision.com/1175/./assets/wallet.png" alt="wallet" /></p> <h2 id="abstract">Abstract</h2> <p>The mutual trust between the wallet and the shop created by the authenticated contract allows you to pay for and purchase items at a simple process.</p> <h2 id="motivation">Motivation</h2> <p>New standards with improvements have been released, but the majority of tokens currently being developed are erc20 tokens. So I felt I needed a proposal to use old tokens in commerce. To use various erc20 tokens for trading, you need a custom contract. However, a single wallet with a variety of tokens, and a mutually trusted store, can make transactions that are simple and efficient. The erc20 token is traded through two calls, <code>approve (address _spender, uint256 _value)</code> and <code>transferFrom (address _from, address _to, uint256 _value)</code>, but when using the wallet contract, <code>paySafe (address _shop, uint256 _item)</code>will be traded only in one call. And if you only reuse the store interface, you can also trade using <code>payUnsafe (address _shop, uint256 _item)</code>.</p> <h2 id="specification">Specification</h2> <p><img src="https://wg-eips.ritovision.com/1175/./assets/workflow.png" alt="workflow" /></p> <h2 id="walletcenter">WalletCenter</h2> <h3 id="methods">Methods</h3> <h4 id="createwallet">createWallet</h4> <p>Create wallet contract and add to list. Returns the address of new wallet.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> createWallet</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">address</span><span class="z-variable"> _wallet</span><span>)</span></span></code></pre><h4 id="iswallet">isWallet</h4> <p>Returns true or false value for test this address is a created by createWallet.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isWallet</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _wallet</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span></span></code></pre><h4 id="createshop">createShop</h4> <p>Create Shop contract and add to list. Returns the address of new Shop with erc20 token address.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> createShop</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>)</span></span></code></pre><h4 id="isshop">isShop</h4> <p>Returns true or false value for test this address is a created by createWallet.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isShop</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span></span></code></pre><h3 id="events">Events</h3> <h4 id="wallet">Wallet</h4> <p>Search for my wallet.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Wallet</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _owner</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _wallet</span><span>)</span></span></code></pre><h4 id="shop">Shop</h4> <p>Search for my shop.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Shop</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _owner</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _shop</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _erc20</span><span>)</span></span></code></pre><h2 id="wallet-1">Wallet</h2> <p>Wallet must be created by wallet center.</p> <h3 id="methods-1">Methods</h3> <h4 id="balanceof">balanceOf</h4> <p>Returns the account balance of Wallet.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> balance</span><span>)</span></span></code></pre><h4 id="withdrawal">withdrawal</h4> <p>withdrawal <code>_value</code> amount of <code>_erc20</code> token to <code>_owner</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> withdrawal</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="paysafe">paySafe</h4> <p>Pay for safe shop (created by contract) item with item index <code>_item</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> paySafe</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> onlyShop</span><span>(</span><span class="z-variable">_shop</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="payunsafe">payUnsafe</h4> <p>Pay for unsafe shop (did not created by contract) item with item index <code>_item</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> payUnsafe</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="paycancel">payCancel</h4> <p>Cancel pay and refund. (only weekly model)</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> payCancel</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="refund">refund</h4> <p>Refund from shop with item index <code>_item</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> refund</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h3 id="events-1">Events</h3> <h4 id="pay">Pay</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Pay</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _shop</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _value</span><span>)</span></span></code></pre><h4 id="refund-1">Refund</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Refund</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _shop</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _value</span><span>)</span></span></code></pre><h2 id="shop-1">Shop</h2> <p>Shop is created by wallet center or not. but Shop that created by wallet center is called safe shop.</p> <h3 id="methods-2">Methods</h3> <h4 id="balanceof-1">balanceOf</h4> <p>Returns the account balance of Shop.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> balance</span><span>)</span></span></code></pre><h4 id="withdrawal-1">withdrawal</h4> <p>withdrawal <code>_value</code> amount of <code>_erc20</code> token to <code>_owner</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> withdrawal</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="pay-1">pay</h4> <p>Pay from buyer with item index <code>_item</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> pay</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyWallet</span><span>(</span><span>msg.sender</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="refund-2">refund</h4> <p>refund token to <code>_to</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> refund</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _buyer</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> onlyWallet</span><span>(</span><span class="z-variable">_buyer</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="resister">resister</h4> <p>Listing item for sell.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> resister</span><span>(</span><span class="z-variable">uint8</span><span class="z-variable"> _category</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _price</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _stock</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> _itemId</span><span>)</span></span></code></pre><h4 id="update">update</h4> <p>Update item state for sell. (change item <code>_price</code> or add item <code>_stock</code>)</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> update</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _price</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _stock</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span></span></code></pre><h4 id="price">price</h4> <p>Get token address and price from buyer with item index <code>_item</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> price</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span></span></code></pre><h4 id="canbuy">canBuy</h4> <p><code>_who</code> can Buy <code>_item</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> canBuy</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _who</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> _canBuy</span><span>)</span></span></code></pre><h4 id="isbuyer">isBuyer</h4> <p><code>_who</code> is buyer of <code>_item</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isBuyer</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _who</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> _buyer</span><span>)</span></span></code></pre><h4 id="info">info</h4> <p>Set shop information bytes.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> info</span><span>(</span><span class="z-variable">bytes</span><span class="z-variable"> _msgPack</span><span>)</span></span></code></pre><h4 id="upvote">upVote</h4> <p>Up vote for this shop.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> upVote</span><span>(</span><span>)</span></span></code></pre><h4 id="dnvote">dnVote</h4> <p>Down vote for this shop.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> dnVote</span><span>(</span><span>)</span></span></code></pre><h4 id="about">about</h4> <p>Get shop token, up vote and down vote.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> about</span><span>(</span><span>)</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _up</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _down</span><span>)</span></span></code></pre><h4 id="infoitem">infoItem</h4> <p>Set item information bytes.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> infoItem</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> _msgPack</span><span>)</span></span></code></pre><h4 id="upvoteitem">upVoteItem</h4> <p>Up vote for this item.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> upVoteItem</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>)</span></span></code></pre><h4 id="dnvoteitem">dnVoteItem</h4> <p>Down vote for this item.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> dnVoteItem</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>)</span></span></code></pre><h4 id="aboutitem">aboutItem</h4> <p>Get Item price, up vote and down vote.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> aboutItem</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> _price</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _up</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _down</span><span>)</span></span></code></pre><h3 id="events-2">Events</h3> <h4 id="pay-2">Pay</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Pay</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _buyer</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _value</span><span>)</span></span></code></pre><h4 id="refund-3">Refund</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Refund</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _to</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _value</span><span>)</span></span></code></pre><h4 id="item">Item</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Item</span><span>(</span><span class="z-variable z-other">uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> _price</span><span>)</span></span></code></pre><h4 id="info-1">Info</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Info</span><span>(</span><span class="z-variable z-other">bytes</span><span class="z-variable z-other"> _msgPack</span><span>)</span></span></code></pre><h4 id="infoitem-1">InfoItem</h4> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> InfoItem</span><span>(</span><span class="z-variable z-other">uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> bytes</span><span class="z-variable z-other"> _msgPack</span><span>)</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>Sample token contract address is <a rel="external" href="https://ropsten.etherscan.io/address/0x393dd70ce2ae7b30501aec94727968c517f90d52">0x393dd70ce2ae7b30501aec94727968c517f90d52</a></p> <p>WalletCenter contract address is <a rel="external" href="https://ropsten.etherscan.io/address/0x1fe0862a4a8287d6c23904d61f02507b5044ea31">0x1fe0862a4a8287d6c23904d61f02507b5044ea31</a></p> <p>WalletCenter create shop contract address is <a rel="external" href="https://ropsten.etherscan.io/address/0x59117730D02Ca3796121b7975796d479A5Fe54B0">0x59117730D02Ca3796121b7975796d479A5Fe54B0</a></p> <p>WalletCenter create wallet contract address is <a rel="external" href="https://ropsten.etherscan.io/address/0x39da7111844df424e1d0a0226183533dd07bc5c6">0x39da7111844df424e1d0a0226183533dd07bc5c6</a></p> <h2 id="appendix">Appendix</h2> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">pragma</span><span class="z-variable z-other"> solidity</span><span class="z-keyword"> ^</span><span class="z-constant">0</span><span class="z-constant">.</span><span class="z-constant">4</span><span>.</span><span class="z-constant">24</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> ERC20Interface</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalSupply</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> tokenOwner</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span class="z-variable"> balance</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> allowance</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> tokenOwner</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> spender</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span class="z-variable"> remaining</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokens</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> spender</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokens</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transferFrom</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> from</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> to</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> tokens</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Transfer</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> from</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> tokenOwner</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> spender</span><span>,</span><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> tokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> SafeMath</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeAdd</span><span>(</span><span class="z-variable">uint</span><span class="z-variable"> a</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> b</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> pure</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span class="z-variable"> c</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> c</span><span class="z-keyword"> =</span><span class="z-variable z-other"> a</span><span class="z-keyword"> +</span><span class="z-variable z-other"> b</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">c</span><span class="z-keyword"> &gt;=</span><span class="z-variable z-other"> a</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeSub</span><span>(</span><span class="z-variable">uint</span><span class="z-variable"> a</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> b</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> pure</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span class="z-variable"> c</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">b</span><span class="z-keyword"> &lt;=</span><span class="z-variable z-other"> a</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> c</span><span class="z-keyword"> =</span><span class="z-variable z-other"> a</span><span class="z-keyword"> -</span><span class="z-variable z-other"> b</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeMul</span><span>(</span><span class="z-variable">uint</span><span class="z-variable"> a</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> b</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> pure</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span class="z-variable"> c</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> c</span><span class="z-keyword"> =</span><span class="z-variable z-other"> a</span><span class="z-keyword"> *</span><span class="z-variable z-other"> b</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">a</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span class="z-keyword"> ||</span><span class="z-variable z-other"> c</span><span class="z-keyword"> /</span><span class="z-variable z-other"> a</span><span class="z-keyword"> ==</span><span class="z-variable z-other"> b</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> safeDiv</span><span>(</span><span class="z-variable">uint</span><span class="z-variable"> a</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> b</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> pure</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint</span><span class="z-variable"> c</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">b</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> c</span><span class="z-keyword"> =</span><span class="z-variable z-other"> a</span><span class="z-keyword"> /</span><span class="z-variable z-other"> b</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> _Base</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> internal</span><span class="z-variable z-other"> owner</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> internal</span><span class="z-variable z-other"> walletCenter</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> modifier</span><span class="z-variable z-other"> onlyOwner</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">owner</span><span class="z-keyword"> ==</span><span class="z-variable z-other"> msg</span><span>.</span><span class="z-variable z-other">sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> modifier</span><span class="z-entity z-name"> onlyWallet</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> _addr</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">WalletCenter</span><span>(</span><span class="z-variable z-other">walletCenter</span><span>)</span><span>.</span><span class="z-entity z-name">isWallet</span><span>(</span><span class="z-variable z-other">_addr</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> modifier</span><span class="z-entity z-name"> onlyShop</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> _addr</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">WalletCenter</span><span>(</span><span class="z-variable z-other">walletCenter</span><span>)</span><span>.</span><span class="z-entity z-name">isShop</span><span>(</span><span class="z-variable z-other">_addr</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> _</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> balanceOf</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> balance</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>.</span><span class="z-variable z-other">balance</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _to</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> internal</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">?</span><span class="z-entity z-name">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>.</span><span class="z-variable z-other">balance</span><span class="z-keyword">:</span><span class="z-entity z-name">ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>)</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> _to</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> else</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">approve</span><span>(</span><span class="z-variable z-other">_to</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> withdrawal</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Pay</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _who</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Refund</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _who</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Prize</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _who</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> _Wallet</span><span class="z-variable z-other"> is</span><span class="z-variable z-other"> _Base</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> constructor</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> _who</span><span>)</span><span class="z-variable z-other"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> owner</span><span class="z-keyword"> =</span><span class="z-variable z-other"> _who</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> walletCenter</span><span class="z-keyword"> =</span><span class="z-variable z-other"> msg</span><span>.</span><span class="z-variable z-other">sender</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pay</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> private</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">_Shop</span><span>(</span><span class="z-variable z-other">_shop</span><span>)</span><span>.</span><span class="z-entity z-name">canBuy</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">_item</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> _erc20</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> _value</span><span>;</span></span> <span class="giallo-l"><span> (</span><span class="z-variable z-other">_erc20</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span class="z-keyword"> =</span><span class="z-entity z-name"> _Shop</span><span>(</span><span class="z-variable z-other">_shop</span><span>)</span><span>.</span><span class="z-entity z-name">price</span><span>(</span><span class="z-variable z-other">_item</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable z-other">_shop</span><span>,</span><span class="z-variable z-other">_erc20</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _Shop</span><span>(</span><span class="z-variable z-other">_shop</span><span>)</span><span>.</span><span class="z-entity z-name">pay</span><span>(</span><span class="z-variable z-other">_item</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Pay</span><span>(</span><span class="z-variable z-other">_shop</span><span>,</span><span class="z-variable z-other">_item</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> paySafe</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> onlyShop</span><span>(</span><span class="z-variable">_shop</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> pay</span><span>(</span><span class="z-variable z-other">_shop</span><span>,</span><span class="z-variable z-other">_item</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> payUnsafe</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> pay</span><span>(</span><span class="z-variable z-other">_shop</span><span>,</span><span class="z-variable z-other">_item</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> payCancel</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> _Shop</span><span>(</span><span class="z-variable z-other">_shop</span><span>)</span><span>.</span><span class="z-entity z-name">payCancel</span><span>(</span><span class="z-variable z-other">_item</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refund</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">value</span><span class="z-keyword">:</span><span class="z-entity z-name">ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">allowance</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-language">this</span><span>)</span><span>)</span><span class="z-keyword">==</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">!=</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Refund</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other">_item</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> prize</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">value</span><span class="z-keyword">:</span><span class="z-entity z-name">ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">allowance</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-language">this</span><span>)</span><span>)</span><span class="z-keyword">==</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">!=</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Prize</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other">_item</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> withdrawal</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">?</span><span class="z-entity z-name">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>.</span><span class="z-variable z-other">balance</span><span class="z-keyword">:</span><span class="z-entity z-name">ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>)</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> owner</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> else</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span class="z-variable z-other">owner</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> _Shop</span><span class="z-variable z-other"> is</span><span class="z-variable z-other"> _Base</span><span>,</span><span class="z-variable z-other"> SafeMath</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> erc20</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> constructor</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> _who</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> _erc20</span><span>)</span><span class="z-variable z-other"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> owner</span><span class="z-keyword"> =</span><span class="z-variable z-other"> _who</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> walletCenter</span><span class="z-keyword"> =</span><span class="z-variable z-other"> msg</span><span>.</span><span class="z-variable z-other">sender</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> erc20</span><span class="z-keyword"> =</span><span class="z-variable z-other"> _erc20</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> struct</span><span class="z-variable z-other"> item</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint8</span><span class="z-variable z-other"> category</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 0 = disable, 1 = non Stock, non Expire, 2 = can Expire (after 1 week), 3 = stackable</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> price</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> stockCount</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> mapping</span><span>(</span><span class="z-variable">address</span><span class="z-storage z-type">=&gt;</span><span class="z-variable z-other">uint256</span><span>)</span><span class="z-variable z-other"> customer</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> index</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> mapping</span><span>(</span><span class="z-variable">uint256</span><span class="z-storage z-type">=&gt;</span><span class="z-variable z-other">item</span><span>)</span><span class="z-variable z-other"> items</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> pay</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyWallet</span><span>(</span><span>msg.sender</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">canBuy</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> _item</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span>(</span><span class="z-variable z-other">erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">value</span><span class="z-keyword">:</span><span class="z-entity z-name">ERC20Interface</span><span>(</span><span class="z-variable z-other">erc20</span><span>)</span><span>.</span><span class="z-entity z-name">allowance</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-language">this</span><span>)</span><span>)</span><span class="z-keyword">==</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">erc20</span><span class="z-keyword">!=</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC20Interface</span><span>(</span><span class="z-variable z-other">erc20</span><span>)</span><span>.</span><span class="z-entity z-name">transferFrom</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">1</span><span class="z-keyword"> ||</span><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">2</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> now</span><span class="z-keyword"> &gt;</span><span class="z-entity z-name"> safeAdd</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span>,</span><span class="z-constant"> 1</span><span class="z-variable z-other"> weeks</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> now</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">2</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> now</span><span class="z-keyword"> &lt;</span><span class="z-entity z-name"> safeAdd</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span>,</span><span class="z-constant"> 1</span><span class="z-variable z-other"> weeks</span><span>)</span><span> )</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> safeAdd</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span>,</span><span class="z-constant"> 1</span><span class="z-variable z-other"> weeks</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">3</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> safeAdd</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span>,</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">stockCount</span><span class="z-keyword"> =</span><span class="z-entity z-name"> safeSub</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">stockCount</span><span>,</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Pay</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other">_item</span><span>,</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> payCancel</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyWallet</span><span>(</span><span>msg.sender</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span> (</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">2</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">safeAdd</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span>,</span><span class="z-constant">2</span><span class="z-variable z-other"> weeks</span><span>)</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">now</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-other">erc20</span><span>)</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> safeSub</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span>,</span><span class="z-constant">1</span><span class="z-variable z-other"> weeks</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other"> erc20</span><span>,</span><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _Wallet</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>)</span><span>.</span><span class="z-entity z-name">refund</span><span>(</span><span class="z-variable z-other">erc20</span><span>,</span><span class="z-variable z-other">_item</span><span>,</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Refund</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other">_item</span><span>,</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> refund</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _to</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> onlyWallet</span><span>(</span><span class="z-variable">_to</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> payable</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">isBuyer</span><span>(</span><span class="z-variable z-other">_to</span><span>,</span><span class="z-variable z-other">_item</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_to</span><span>]</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">||</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">2</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">safeAdd</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_to</span><span>]</span><span>,</span><span class="z-constant">2</span><span class="z-variable z-other"> weeks</span><span>)</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">now</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span>(</span><span class="z-variable z-other">erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">?</span><span class="z-entity z-name">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>.</span><span class="z-variable z-other">balance</span><span class="z-keyword">:</span><span class="z-entity z-name">ERC20Interface</span><span>(</span><span class="z-variable z-other">erc20</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>)</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">1</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_to</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">2</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_to</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> safeSub</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_to</span><span>]</span><span>,</span><span class="z-constant">1</span><span class="z-variable z-other"> weeks</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> else</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_to</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> safeSub</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_to</span><span>]</span><span>,</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-entity z-name"> transfer</span><span>(</span><span class="z-variable z-other">_to</span><span>,</span><span class="z-variable z-other"> erc20</span><span>,</span><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> _Wallet</span><span>(</span><span class="z-variable z-other">_to</span><span>)</span><span>.</span><span class="z-entity z-name">refund</span><span>(</span><span class="z-variable z-other">erc20</span><span>,</span><span class="z-variable z-other">_item</span><span>,</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Refund</span><span>(</span><span class="z-variable z-other">_to</span><span>,</span><span class="z-variable z-other">_item</span><span>,</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Item</span><span>(</span><span class="z-variable z-other">uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _item</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> _price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> resister</span><span>(</span><span class="z-variable">uint8</span><span class="z-variable"> _category</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _price</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _stock</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> _itemId</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">_category</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">_category</span><span class="z-keyword">&lt;</span><span class="z-constant">4</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">_price</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">index</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> item</span><span>(</span><span class="z-variable z-other">_category</span><span>,</span><span class="z-variable z-other">_price</span><span>,</span><span class="z-variable z-other">_stock</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> index</span><span class="z-keyword"> =</span><span class="z-entity z-name"> safeAdd</span><span>(</span><span class="z-variable z-other">index</span><span>,</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Item</span><span>(</span><span class="z-variable z-other">index</span><span>,</span><span class="z-variable z-other">_price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> safeSub</span><span>(</span><span class="z-variable z-other">index</span><span>,</span><span class="z-constant">1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> update</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _price</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _stock</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">_price</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> temp</span><span class="z-keyword"> =</span><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span class="z-keyword"> =</span><span class="z-variable z-other"> _price</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">stockCount</span><span class="z-keyword"> =</span><span class="z-entity z-name"> safeAdd</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">stockCount</span><span>,</span><span class="z-variable z-other">_stock</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">temp</span><span class="z-keyword">!=</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Item</span><span>(</span><span class="z-variable z-other">index</span><span>,</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> price</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-variable z-other">erc20</span><span>,</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">price</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> canBuy</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _who</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> _canBuy</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> &amp;&amp;</span></span> <span class="giallo-l"><span class="z-keyword"> !</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">1</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_who</span><span>]</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> &amp;&amp;</span></span> <span class="giallo-l"><span> (</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">stockCount</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isBuyer</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _who</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _item</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> _buyer</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">1</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_who</span><span>]</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">||</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">2</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">safeAdd</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_who</span><span>]</span><span>,</span><span class="z-constant">1</span><span class="z-variable z-other"> weeks</span><span>)</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">now</span><span>)</span><span class="z-keyword">||</span><span>(</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">category</span><span class="z-keyword">==</span><span class="z-constant">3</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">items</span><span>[</span><span class="z-variable z-other">_item</span><span>]</span><span>.</span><span class="z-variable z-other">customer</span><span>[</span><span class="z-variable z-other">_who</span><span>]</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> lastWithdrawal</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> withdrawal</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>,</span><span class="z-variable"> uint256</span><span class="z-variable"> _value</span><span>)</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-entity z-name">safeAdd</span><span>(</span><span class="z-variable z-other">lastWithdrawal</span><span>,</span><span class="z-constant">1</span><span class="z-variable z-other"> weeks</span><span>)</span><span class="z-keyword">&lt;=</span><span class="z-variable z-other">now</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">?</span><span class="z-entity z-name">address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>.</span><span class="z-variable z-other">balance</span><span class="z-keyword">:</span><span class="z-entity z-name">ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">balanceOf</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>)</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">_erc20</span><span class="z-keyword">==</span><span class="z-entity z-name">address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> owner</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> else</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC20Interface</span><span>(</span><span class="z-variable z-other">_erc20</span><span>)</span><span>.</span><span class="z-entity z-name">transfer</span><span>(</span><span class="z-variable z-other">owner</span><span>,</span><span class="z-variable z-other">_value</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> lastWithdrawal</span><span class="z-keyword"> =</span><span class="z-variable z-other"> now</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> WalletCenter</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> mapping</span><span>(</span><span class="z-variable">address</span><span class="z-storage z-type">=&gt;</span><span class="z-variable z-other">bool</span><span>)</span><span class="z-variable z-other"> public</span><span class="z-variable z-other"> wallet</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Wallet</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _owner</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _wallet</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createWallet</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">address</span><span class="z-variable"> _wallet</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> _wallet</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> _Wallet</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> wallet</span><span>[</span><span class="z-variable z-other">_wallet</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Wallet</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other">_wallet</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> _wallet</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isWallet</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _wallet</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> wallet</span><span>[</span><span class="z-variable z-other">_wallet</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> mapping</span><span>(</span><span class="z-variable">address</span><span class="z-storage z-type">=&gt;</span><span class="z-variable z-other">bool</span><span>)</span><span class="z-variable z-other"> public</span><span class="z-variable z-other"> shop</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span class="z-entity z-name"> Shop</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _owner</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _shop</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> _erc20</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> createShop</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _erc20</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> _shop</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> _Shop</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other">_erc20</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> shop</span><span>[</span><span class="z-variable z-other">_shop</span><span>]</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> emit</span><span class="z-entity z-name"> Shop</span><span>(</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>,</span><span class="z-variable z-other">_shop</span><span>,</span><span class="z-variable z-other">_erc20</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> _shop</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isShop</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _shop</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> shop</span><span>[</span><span class="z-variable z-other">_shop</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-06-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 nitika-goelnitika@govblocks.io https://wg-eips.ritovision.com/1132/ <h2 id="simple-summary">Simple Summary</h2> <p>An extension to the ERC20 standard with methods for time-locking of tokens within a contract.</p> <h2 id="abstract">Abstract</h2> <p>This proposal provides basic functionality to time-lock tokens within an ERC20 smart contract for multiple utilities without the need of transferring tokens to an external escrow smart contract. It also allows fetching balance of locked and transferable tokens.</p> <p>Time-locking can also be achieved via staking (#900), but that requires transfer of tokens to an escrow contract / stake manager, resulting in the following six concerns:</p> <ol> <li>additional trust on escrow contract / stake manager</li> <li>additional approval process for token transfer</li> <li>increased ops costs due to gas requirements in transfers</li> <li>tough user experience as the user needs to claim the amount back from external escrows</li> <li>inability for the user to track their true token balance / token activity</li> <li>inability for the user to utilize their locked tokens within the token ecosystem.</li> </ol> <h2 id="motivation">Motivation</h2> <p>dApps often require tokens to be time-locked against transfers for letting members 1) adhere to vesting schedules and 2) show skin in the game to comply with the underlying business process. I realized this need while building Nexus Mutual and GovBlocks.</p> <p>In <a rel="external" href="https://nexusmutual.io">Nexus Mutual</a>, claim assessors are required to lock their tokens before passing a vote for claims assessment. This is important as it ensures assessors’ skin in the game. The need here was that once a claim assessor locks his tokens for ‘n’ days, he should be able to cast multiple votes during that period of ‘n’ days, which is not feasible with staking mechanism. There are other scenarios like skills/identity verification or participation in gamified token curated registries where time-locked tokens are required as well.</p> <p>In <a rel="external" href="https://govblocks.io">GovBlocks</a>, I wanted to allow dApps to lock member tokens for governance, while still allowing members to use those locked tokens for other activities within the dApp business. This is also the case with DGX governance model where they’ve proposed quarterly token locking for participation in governance activities of DGX.</p> <p>In addition to locking functionality, I have proposed a <code>Lock()</code> and <code>Unlock()</code> event, just like the <code>Transfer()</code> event , to track token lock and unlock status. From token holder’s perspective, it gets tough to manage token holdings if certain tokens are transferred to another account for locking, because whenever <code>balanceOf()</code> queries are triggered on token holder’s account – the result does not include locked tokens. A <code>totalBalanceOf()</code> function intends to solve this problem.</p> <p>The intention with this proposal is to enhance the ERC20 standard with token-locking capability so that dApps can time-lock tokens of the members without having to transfer tokens to an escrow / stake manager and at the same time allow members to use the locked tokens for multiple utilities.</p> <h2 id="specification">Specification</h2> <p>I’ve extended the ERC20 interface with the following enhancements:</p> <h3 id="locking-of-tokens">Locking of tokens</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Locks a specified amount of tokens against an address,</span></span> <span class="giallo-l"><span class="z-comment"> * for a specified reason and time</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _reason</span><span class="z-comment"> The reason to lock tokens</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _amount</span><span class="z-comment"> Number of tokens to be locked</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _time</span><span class="z-comment"> Lock time in seconds</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> lock</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _reason</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _amount</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _time</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span></code></pre><h3 id="fetching-number-of-tokens-locked-under-each-utility">Fetching number of tokens locked under each utility</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns tokens locked for a specified address for a</span></span> <span class="giallo-l"><span class="z-comment"> * specified reason</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _of</span><span class="z-comment"> The address whose tokens are locked</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _reason</span><span class="z-comment"> The reason to query the lock tokens for</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-entity z-name"> tokensLocked</span><span>(</span><span class="z-support">address</span><span> _of</span><span>,</span><span class="z-support"> bytes32</span><span> _reason</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span></span></code></pre><h3 id="fetching-number-of-tokens-locked-under-each-utility-at-a-future-timestamp">Fetching number of tokens locked under each utility at a future timestamp</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns tokens locked for a specified address for a</span></span> <span class="giallo-l"><span class="z-comment"> * specified reason at a specific time</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _of</span><span class="z-comment"> The address whose tokens are locked</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _reason</span><span class="z-comment"> The reason to query the lock tokens for</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _time</span><span class="z-comment"> The timestamp to query the lock tokens for</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokensLockedAtTime</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _of</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _reason</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _time</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span></span></code></pre><h3 id="fetching-number-of-tokens-held-by-an-address">Fetching number of tokens held by an address</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-storage z-type"> @dev</span><span class="z-comment"> Returns total tokens held by an address (locked + transferable)</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _of</span><span class="z-comment"> The address to query the total balance of</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> totalBalanceOf</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _of</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span></span></code></pre><h3 id="extending-lock-period">Extending lock period</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Extends lock for a specified reason and time</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _reason</span><span class="z-comment"> The reason to lock tokens</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _time</span><span class="z-comment"> Lock extension time in seconds</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> extendLock</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _reason</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _time</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span></code></pre><h3 id="increasing-number-of-tokens-locked">Increasing number of tokens locked</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Increase number of tokens locked for a specified reason</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _reason</span><span class="z-comment"> The reason to lock tokens</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _amount</span><span class="z-comment"> Number of tokens to be increased</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> increaseLockAmount</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable z-parameter z-function"> _reason</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span></code></pre><h3 id="fetching-number-of-unlockable-tokens-under-each-utility">Fetching number of unlockable tokens under each utility</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Returns unlockable tokens for a specified address for a specified reason</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _of</span><span class="z-comment"> The address to query the unlockable token count of</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _reason</span><span class="z-comment"> The reason to query the unlockable tokens for</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> tokensUnlockable</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _of</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _reason</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>)</span></span></code></pre><h3 id="fetching-number-of-unlockable-tokens">Fetching number of unlockable tokens</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Gets the unlockable tokens of a specified address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _of</span><span class="z-comment"> The address to query the unlockable token count of</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getUnlockableTokens</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _of</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> unlockableTokens</span><span>)</span></span></code></pre><h3 id="unlocking-tokens">Unlocking tokens</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> Unlocks the unlockable tokens of a specified address</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@param</span><span class="z-variable z-other"> _of</span><span class="z-comment"> Address of user, claiming back unlockable tokens</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unlock</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _of</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> unlockableTokens</span><span>)</span></span></code></pre><h3 id="lock-event-recorded-in-the-token-contract">Lock event recorded in the token contract</h3> <p><code>event Locked(address indexed _of, uint256 indexed _reason, uint256 _amount, uint256 _validity)</code></p> <h3 id="unlock-event-recorded-in-the-token-contract">Unlock event recorded in the token contract</h3> <p><code>event Unlocked(address indexed _of, uint256 indexed _reason, uint256 _amount)</code></p> <h2 id="test-cases">Test Cases</h2> <p>Test cases are available at <a rel="external" href="https://github.com/nitika-goel/lockable-token">https://github.com/nitika-goel/lockable-token</a>.</p> <h2 id="implementation">Implementation</h2> <ul> <li>Complete implementation available at https://github.com/nitika-goel/lockable-token</li> <li><a rel="external" href="https://govblocks.io">GovBlocks</a> Project specific implementation available at https://github.com/somish/govblocks-protocol/blob/Locking/contracts/GBTStandardToken.sol</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-31T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jan Turkhttps://github.com/ThunderDeliverer https://wg-eips.ritovision.com/1129/ <h2 id="simple-summary">Simple Summary</h2> <p>Standardisation of announcements in DAPPs and services on Ethereum network. This ERC provides proposed mechanics to increase the quality of service provided by DAPP developers and service providers, by setting a framework for announcements. Be it transitioning to a new smart contract or just freezing the service for some reason.</p> <h2 id="abstract">Abstract</h2> <p>The proposed ERC defines format on how to post announcements about the service as well as how to remove them. It also defines mechanics on posting permissions and human friendly interface.</p> <h2 id="motivation">Motivation</h2> <p>Currently there are no guidelines on how to notify the users of the service status in the DAPPs. This is especially obvious in ERC20 and it's derivates. If the service is impeded by any reason it is good practice to have some sort of guidelines on how to announce that to the user. The standardisation would also provide traceability of the service's status.</p> <h2 id="specification">Specification</h2> <h3 id="structures">Structures</h3> <h4 id="announcer">Announcer</h4> <p>Stores information about the announcement maker. The <code>allowedToPost</code> stores posting permissions and is used for modifiers limiting announcement posting only to authorised entities. The <code>name</code> is used for human friendly identifier of the author to be stored.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">struct</span><span class="z-variable z-other"> Announcer</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> bool</span><span class="z-variable z-other"> allowedToPost</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> string</span><span class="z-variable z-other"> name</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="announcement">Announcement</h4> <p>Stores information about the individual announcement. The human friendly author identifier is stored in <code>author</code>. Ethereum address associated with the author is stored in <code>authorAddress</code>. The announcement itself is stored in <code>post</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">struct</span><span class="z-variable z-other"> Announcement</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> string</span><span class="z-variable z-other"> author</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> authorAddress</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> string</span><span class="z-variable z-other"> post</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="methods">Methods</h3> <h4 id="the-number-of-announcements">the number of announcements</h4> <p>Returns the number of announcements currently active.</p> <p>OPTIONAL - this method can be used to provide quicker information for the UI, but could also be retrieved from <code>numberOfMessages</code> variable.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> theNumberOfAnnouncements</span><span>(</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _numberOfAnnouncements</span><span>)</span></span></code></pre><h4 id="read-posts">read posts</h4> <p>Returns the specified announcement as well as human friendly poster identificator (name or nickname).</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> readPosts</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _postNumber</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-variable">string</span><span class="z-variable"> _author</span><span>,</span><span class="z-variable"> string</span><span class="z-variable"> _post</span><span>)</span></span></code></pre><h4 id="give-posting-permission">give posting permission</h4> <p>Sets posting permissions of the address <code>_newAnnouncer</code> to <code>_postingPrivileges</code> and can also be used to revoke those permissions. The <code>_posterName</code> is human friendly author identificator used in the announcement data.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> givePostingPermission</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> _newAnnouncer</span><span>,</span><span class="z-variable"> bool</span><span class="z-variable"> _postingPrivileges</span><span>,</span><span class="z-variable"> string</span><span class="z-variable"> _posterName</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> onlyOwner</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="can-post">can post</h4> <p>Checks if the entity that wants to post an announcement has the posting privilieges.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">modifier</span><span class="z-variable z-other"> canPost</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">posterData</span><span>[</span><span class="z-variable z-other">msg</span><span>.</span><span class="z-variable z-other">sender</span><span>]</span><span>.</span><span class="z-variable z-other">allowedToPost</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> _</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="post-announcement">post announcement</h4> <p>Lets user post announcements, but only if they have their posting privileges set to <code>true</code>. The announcement is sent in <code>_message</code> variable.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> postAnnouncement</span><span>(</span><span class="z-variable">string</span><span class="z-variable"> _message</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> canPost</span></span></code></pre><h4 id="remove-announcement">remove announcement</h4> <p>Removes an announcement with <code>_messageNumber</code> announcement identifier and rearranges the mapping so there are no empty slots. The <code>_removalReason</code> is used to update users if the issue that caused the announcement is resolved or what are the next steps from the service provider / DAPP development team.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> removeAnnouncement</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _messageNumber</span><span>,</span><span class="z-variable"> string</span><span class="z-variable"> _removalReason</span><span>)</span><span class="z-entity z-name"> public</span></span></code></pre><h3 id="events">Events</h3> <h4 id="new-announcement">New announcement</h4> <p>MUST trigger when new announcement is created.</p> <p>Every time there is a new announcement it should be advertised in this event. It holds the information about author <code>author</code> and the announcement istelf <code>message</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> NewAnnouncement</span><span>(</span><span class="z-variable z-other">string</span><span class="z-variable z-other"> author</span><span>,</span><span class="z-variable z-other"> string</span><span class="z-variable z-other"> message</span><span>)</span></span></code></pre><h4 id="removed-announcement">Removed announcement</h4> <p>MUST trigger when an announcement is removed.</p> <p>Every time an announcement is removed it should be advertised in this event. It holds the information about author <code>author</code>, the announcement itself <code>message</code>, the reason for removal or explanation of the solution <code>reason</code> and the address of the entity that removed the announcement <code>remover</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> RemovedAnnouncement</span><span>(</span><span class="z-variable z-other">string</span><span class="z-variable z-other"> author</span><span>,</span><span class="z-variable z-other"> string</span><span class="z-variable z-other"> message</span><span>,</span><span class="z-variable z-other"> string</span><span class="z-variable z-other"> reason</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> remover</span><span>)</span><span>;</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The proposed solution was designed with UX in mind . It provides mechanics that serve to present the announcements in the user friendly way. It is meant to be deployed as a Solidity smart contract on Ethereum network.</p> <h2 id="test-cases">Test Cases</h2> <p>The proposed version is deployed on Ropsten testnet all of the information can be found <a rel="external" href="https://ropsten.etherscan.io/address/0xb04f67172b9733837e59ebaf03d277279635c8e6#readContract">here</a>.</p> <h2 id="implementation">Implementation</h2> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-22T00:00:00+00:00 2026-02-11T14:49:27+00:00 Jordi Baylinahttps://github.com/jbaylina https://wg-eips.ritovision.com/1109/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP creates a specific opcode named <code>PRECOMPILEDCALL</code> to call Precompiled contracts without the costs of a normal <code>CALL</code>.</p> <h2 id="abstract">Abstract</h2> <p>This EIP tries to resolve the problem of high gas consumption when calling precompiled contracts with a small gas cost. Using this opcode for calling precompiled contracts allows to define precompiled contracts whose effective cost it is less than 700.</p> <h2 id="motivation">Motivation</h2> <p>Each precompiled contract has an already defined cost for calling it. It does not make sense to add the implicit extra gas cost of the CALL opcode.</p> <p>As an example, SHA256 precompiled contract costs 60 and ECADD costs 500 (proposed to costs only 50 in <a href="https://wg-eips.ritovision.com/1108/">EIP-1108</a> . When a precompiled contract is called, 700 gas is consumed just for the CALL opcode besides the costs of the precompiled contract.</p> <p>This makes no sense, and right now it's impossible to define a precompiled contract whose effective cost for using it, is less than 700.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= XXXXX</code>, define a new opcode named <code>PRECOMPILEDCALL</code> with code value <code>0xfb</code>.</p> <p>The gas cost of the OPCODE is 2 (Gbase) plus the Specific gas cost defined for each specific precompiled smart contract.</p> <p>The OPCODE takes 5 words from the stack and returns 1 word to the stack.</p> <p>The input stack values are:</p> <p>mu_s[0] = The address of the precompiled smart contract that is called. mu_s[1] = Pointer to memory for the input parameters. mu_s[2] = Length of the input parameters in bytes. mu_s[3] = Pointer to memory where the output is stored mu_s[4] = Length of the output buffer.</p> <p>The return will be 1 in case of success call and 0 in any of the next cases:</p> <p>1.- mu_s[0] is an address of an undefined precompiled smart contract. 2.- The precompiled smart contract fails (as defined on each smart contract). Invalid input parameters for example.</p> <p>Precompiled smart contracts, does not execute opcodes, so there is no need to pass a gas parameter as a normal <code>CALL</code> (<code>0xf1</code>). If the available gas is less that 2 plus the required gas required for the specific precompiled smart contract, the context just STOPS executing with an "Out of Gas" error.</p> <p>There is no stack check for this call.</p> <p>The normal <code>CALL</code>s to the precompiled smart contracts continue to work with the exact same behavior.</p> <p>A <code>PRECOMPILEDCALL</code> to a regular address or regular smart contract, is considered a call to an "undefined smart contract", so the VM MUST not execute it and the opcode must return 0x0 .</p> <h2 id="rationale">Rationale</h2> <p>There was a first proposal for removing the gast consts for the <code>CALL</code>, but it looks that it's easier to implement and test a new opcode just for that.</p> <p>The code is just the next opcode available after the <code>STATICCALL</code> opcode.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backwards compatible. Smart contracts that call precompiled contracts using this new opcode will cost less from now on.</p> <p>Old contracts that call precompiled smart contracts with the <code>CALL</code> method, will continue working.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li>Normal call to a defined precompiled contract.</li> <li>Call to undefined precompiled contract.</li> <li>Call to a regular contract</li> <li>Call to a regular account</li> <li>Call to 0x0 smart contract (Does not exists).</li> <li>Call with large values for the offste pointers and lengths</li> <li>Call with the exact gas remaining needed to call smart contract.</li> <li>Call with the exact gas remaining minus one needed to call smart contract.</li> </ul> <h2 id="implementation">Implementation</h2> <p>Not implemented yet.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-17T00:00:00+00:00 2026-02-11T14:49:27+00:00 Nick Johnsonhttps://github.com/arachnid https://wg-eips.ritovision.com/1087/ <h2 id="abstract">Abstract</h2> <p>This EIP proposes a change to how gas is charged for EVM <code>SSTORE</code> operations, in order to reduce excessive gas costs in situations where these are unwarranted, and to enable new use-cases for contract storage.</p> <h2 id="motivation">Motivation</h2> <p>Presently, <code>SSTORE</code> (<code>0x55</code>) operations are charged as follows:</p> <ul> <li>20,000 gas to set a slot from 0 to non-0</li> <li>5,000 gas for any other change</li> <li>A 10,000 gas refund when a slot is set from non-0 to 0. Refunds are applied at the end of the transaction.</li> </ul> <p>In situations where a single update is made to a storage value in a transaction, these gas costs have been determined to fairly reflect the resources consumed by the operation. However, this results in excessive gas costs for sequences of operations that make multiple updates.</p> <p>Some examples to illustrate the problem:</p> <ul> <li>If a contract with empty storage sets slot 0 to 1, then back to 0, it will be charged <code>20000 + 5000 - 10000 = 15000</code> gas, despite this sequence of operations not requiring any disk writes.</li> <li>A contract with empty storage that increments slot 0 5 times will be charged <code>20000 + 5 * 5000 = 45000</code> gas, despite this sequence of operations requiring no more disk activity than a single write, charged at 20000 gas.</li> <li>A balance transfer from account A to account B followed by a transfer from B to C, with all accounts having nonzero starting and ending balances, will cost <code>5000 * 4 = 20000</code> gas.</li> </ul> <p>Addressing this issue would also enable new use-cases that are currently cost-prohibitive, where a sequence of operations results in no net change to storage at the end of the transaction. For instance, mutexes to prevent reentrancy, or context information passed between multiple calls to the same contract. One such example is an <code>approveAndCall</code> operation, which would permit sending to and calling a contract in a single transaction, without that contract having to be updated for a new token standard.</p> <h2 id="specification">Specification</h2> <p>The following changes are made to the EVM:</p> <ul> <li>A 'dirty map' for each transaction is maintained, tracking all storage slots in all contracts that have been modified in the current transaction. The dirty map is scoped in the same manner as updates to storage, meaning that changes to the dirty map in a call that later reverts are not retained.</li> <li>When a storage slot is written to with the value it already contains, 200 gas is deducted.</li> <li>When a storage slot's value is changed for the first time, the slot is marked as dirty. If the slot was previously set to 0, 20000 gas is deducted; otherwise, 5000 gas is deducted.</li> <li>When a storage slot that is already in the dirty map is written to, 200 gas is deducted.</li> <li>At the end of the transaction, for each slot in the dirty map: <ul> <li>If the slot was 0 before the transaction and is 0 now, refund 19800 gas.</li> <li>If the slot was nonzero before the transaction and its value has not changed, refund 4800 gas.</li> <li>If the slot was nonzero before the transaction and is 0 now, refund 15000 gas.</li> </ul> </li> </ul> <p>After these changes, transactions that make only a single change to a storage slot will retain their existing costs. However, contracts that make multiple changes will see significantly reduced costs. Repeating the examples from the Motivation section:</p> <ul> <li>If a contract with empty storage sets slot 0 to 1, then back to 0, it will be charged <code>20000 + 200 - 19800 = 400</code> gas, down from 15000.</li> <li>A contract with empty storage that increments slot 0 5 times will be charged <code>20000 + 5 * 200 = 21000</code> gas, down from 45000.</li> <li>A balance transfer from account A to account B followed by a transfer from B to C, with all accounts having nonzero starting and ending balances, will cost <code>5000 * 3 + 200 - 4800 = 10400</code> gas, down from 20000.</li> </ul> <h2 id="rationale">Rationale</h2> <p>We believe the proposed mechanism represents the simplest way to reduce storage gas costs in situations where they do not reflect the actual costs borne by nodes. Several alternative designs were considered and dismissed:</p> <ul> <li>Charging a flat 200 gas for <code>SSTORE</code> operations, and an additional 19800 / 4800 at the end of a transaction for new or modified values is simpler, and removes the need for a dirty map, but pushes a significant source of gas consumption out of the EVM stack and applies it at the end of the transaction, which is likely to complicate debugging and reduces contracts' ability to limit the gas consumption of callees, as well as introducing a new mechanism to the EVM.</li> <li>Keeping a separate refund counter for storage gas refunds would avoid the issue of refunds being limited to half the gas consumed (not necessary here), but would introduce additional complexity in tracking this value.</li> <li>Refunding gas each time a storage slot is set back to its initial value would introduce a new mechanism (instant refunds) and complicate gas accounting for contracts calling other contracts; it would also permit the possibility of a contract call with negative execution cost.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP requires a hard fork to implement.</p> <p>No contract should see an increase in gas cost for this change, and many will see decreased gas consumption, so no contract-layer backwards compatibility issues are anticipated.</p> <h2 id="test-cases">Test Cases</h2> <ul> <li>Writing x to a storage slot that contains 0, where x != 0 (20k gas, no refund)</li> <li>Writing y to a storage slot that contained x, where x != y and x != 0 (5k gas, no refund)</li> <li>Writing 0 to a storage slot that contains x, where x != 0 (5k gas, 10k refund)</li> <li>Writing 0 to a storage slot that already contains zero (200 gas, no refund)</li> <li>Writing x to a storage slot that already contains x, where x != 0 (200 gas, no refund)</li> <li>Writing x, then y to a storage slot that contains 0, where x != y (20200 gas, no refund)</li> <li>Writing x, then y to a storage slot that contains 0, where x != y != z and x != 0 (5200 gas, no refund)</li> <li>Writing x, then 0 to a storage slot that contains 0, where x != 0 (20200 gas, 19800 refund)</li> <li>Writing x, then y to a storage slot that contains y, where x != y != 0 (5200 gas, 4800 refund)</li> <li>Writing x, then 0 to a storage slot that contains 0, then reverting the stack frame in which the writes occurred (20200 gas, no refund)</li> <li>Writing x, then y to a storage slot that contains y, then reverting the stack frame in which the writes occurred (5200 gas, no refund)</li> <li>In a nested frame, writing x to a storage slot that contains 0, then returning, and writing 0 to that slot (20200 gas, 19800 refund)</li> </ul> <h2 id="implementation">Implementation</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Mark Beylinmark.beylin@consensys.net Kevin Owockikevin.owocki@consensys.net Ricardo Guilherme Schmidthttps://github.com/3esmit https://wg-eips.ritovision.com/1081/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard contract and interface for issuing bounties on Ethereum, usable for any type of task, paying in any ERC20 token or in ETH.</p> <h2 id="abstract">Abstract</h2> <p>In order to encourage cross-platform interoperability of bounties on Ethereum, and for easier reputational tracking, StandardBounties can facilitate the administration of funds in exchange for deliverables corresponding to a completed task, in a publicly auditable and immutable fashion.</p> <h2 id="motivation">Motivation</h2> <p>In the absence of a standard for bounties on Ethereum, it would be difficult for platforms to collaborate and share the bounties which users create (thereby recreating the walled gardens which currently exist on Web2.0 task outsourcing platforms). A standardization of these interactions across task types also makes it far easier to track various reputational metrics (such as how frequently you pay for completed submissions, or how frequently your work gets accepted).</p> <h2 id="specification">Specification</h2> <p>After studying bounties as they've existed for thousands of years (and after implementing and processing over 300 of them on main-net in beta), we've discovered that there are 3 core steps to every bounty:</p> <ul> <li>a bounty is <strong>issued</strong>: an <code>issuer</code> specifies the requirements for the task, describing the desired outcome, and how much they would be willing to pay for the completion of that task (denoted in one or several tokens).</li> <li>a bounty is <strong>fulfilled</strong>: a bounty <code>fulfiller</code> may see the bounty, complete the task, and produce a deliverable which is itself the desired outcome of the task, or simply a record that it was completed. Hashes of these deliverables should be stored immutably on-chain, to serve as proof after the fact.</li> <li>a fulfillment is <strong>accepted</strong>: a bounty <code>issuer</code> or <code>arbiter</code> may select one or more submissions to be accepted, thereby releasing payment to the bounty fulfiller(s), and transferring ownership over the given deliverable to the <code>issuer</code>.</li> </ul> <p>To implement these steps, a number of functions are needed:</p> <ul> <li><code>initializeBounty(address _issuer, address _arbiter, string _data, uint _deadline)</code>: This is used when deploying a new StandardBounty contract, and is particularly useful when applying the proxy design pattern, whereby bounties cannot be initialized in their constructors. Here, the data string should represent an IPFS hash, corresponding to a JSON object which conforms to the schema (described below).</li> <li><code>fulfillBounty(address[] _fulfillers, uint[] _numerators, uint _denomenator, string _data)</code>: This is called to submit a fulfillment, submitting a string representing an IPFS hash which contains the deliverable for the bounty. Initially fulfillments could only be submitted by one individual at a time, however users consistently told us they desired to be able to collaborate on fulfillments, thereby allowing the credit for submissions to be shared by several parties. The lines along which eventual payouts are split are determined by the fractions of the submission credited to each fulfiller (using the array of numerators and single denominator). Here, a bounty platform may also include themselves as a collaborator to collect a small fee for matching the bounty with fulfillers.</li> <li><code>acceptFulfillment(uint _fulfillmentId, StandardToken[] _payoutTokens, uint[] _tokenAmounts)</code>: This is called by the <code>issuer</code> or the <code>arbiter</code> to pay out a given fulfillment, using an array of tokens, and an array of amounts of each token to be split among the contributors. This allows for the bounty payout amount to move as it needs to be based on incoming contributions (which may be transferred directly to the contract address). It also allows for the easy splitting of a given bounty's balance among several fulfillments, if the need should arise. <ul> <li><code>drainBounty(StandardToken[] _payoutTokens)</code>: This may be called by the <code>issuer</code> to drain a bounty of it's funds, if the need should arise.</li> </ul> </li> <li><code>changeBounty(address _issuer, address _arbiter, string _data, uint _deadline)</code>: This may be called by the <code>issuer</code> to change the <code>issuer</code>, <code>arbiter</code>, <code>data</code>, and <code>deadline</code> fields of their bounty.</li> <li><code>changeIssuer(address _issuer)</code>: This may be called by the <code>issuer</code> to change to a new <code>issuer</code> if need be</li> <li><code>changeArbiter(address _arbiter)</code>: This may be called by the <code>issuer</code> to change to a new <code>arbiter</code> if need be</li> <li><code>changeData(string _data)</code>: This may be called by the <code>issuer</code> to change just the <code>data</code></li> <li><code>changeDeadline(uint _deadline)</code>: This may be called by the <code>issuer</code> to change just the <code>deadline</code></li> </ul> <p>Optional Functions:</p> <ul> <li><code>acceptAndFulfill(address[] _fulfillers, uint[] _numerators, uint _denomenator, string _data, StandardToken[] _payoutTokens, uint[] _tokenAmounts)</code>: During the course of the development of this standard, we discovered the desire for fulfillers to avoid paying gas fees on their own, entrusting the bounty's <code>issuer</code> to make the submission for them, and at the same time accept it. This is useful since it still immutably stores the exchange of tokens for completed work, but avoids the need for new bounty fulfillers to have any ETH to pay for gas costs in advance of their earnings.</li> <li><code>changeMasterCopy(StandardBounty _masterCopy)</code>: For <code>issuer</code>s to be able to change the masterCopy which their proxy contract relies on, if the proxy design pattern is being employed.</li> <li><code>refundableContribute(uint[] _amounts, StandardToken[] _tokens)</code>: While non-refundable contributions may be sent to a bounty simply by transferring those tokens to the address where it resides, one may also desire to contribute to a bounty with the option to refund their contribution, should the bounty never receive a correct submission which is paid out. <code>refundContribution(uint _contributionId)</code>: If a bounty hasn't yet paid out to any correct submissions and is past it's deadline, those individuals who employed the <code>refundableContribute</code> function may retrieve their funds from the contract.</li> </ul> <p><strong>Schemas</strong> Persona Schema:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> name: // optional - A string representing the name of the persona</span></span> <span class="giallo-l"><span> email: // optional - A string representing the preferred contact email of the persona</span></span> <span class="giallo-l"><span> githubUsername: // optional - A string representing the github username of the persona</span></span> <span class="giallo-l"><span> address: // required - A string web3 address of the persona</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Bounty issuance <code>data</code> Schema:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> payload: {</span></span> <span class="giallo-l"><span> title: // A string representing the title of the bounty</span></span> <span class="giallo-l"><span> description: // A string representing the description of the bounty, including all requirements</span></span> <span class="giallo-l"><span> issuer: {</span></span> <span class="giallo-l"><span> // persona for the issuer of the bounty</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> funders:[</span></span> <span class="giallo-l"><span> // array of personas of those who funded the issue.</span></span> <span class="giallo-l"><span> ],</span></span> <span class="giallo-l"><span> categories: // an array of strings, representing the categories of tasks which are being requested</span></span> <span class="giallo-l"><span> tags: // an array of tags, representing various attributes of the bounty</span></span> <span class="giallo-l"><span> created: // the timestamp in seconds when the bounty was created</span></span> <span class="giallo-l"><span> tokenSymbol: // the symbol for the token which the bounty pays out</span></span> <span class="giallo-l"><span> tokenAddress: // the address for the token which the bounty pays out (0x0 if ETH)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // ------- add optional fields here -------</span></span> <span class="giallo-l"><span> sourceFileName: // A string representing the name of the file</span></span> <span class="giallo-l"><span> sourceFileHash: // The IPFS hash of the file associated with the bounty</span></span> <span class="giallo-l"><span> sourceDirectoryHash: // The IPFS hash of the directory which can be used to access the file</span></span> <span class="giallo-l"><span> webReferenceURL: // The link to a relevant web reference (ie github issue)</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> meta: {</span></span> <span class="giallo-l"><span> platform: // a string representing the original posting platform (ie &#39;gitcoin&#39;)</span></span> <span class="giallo-l"><span> schemaVersion: // a string representing the version number (ie &#39;0.1&#39;)</span></span> <span class="giallo-l"><span> schemaName: // a string representing the name of the schema (ie &#39;standardSchema&#39; or &#39;gitcoinSchema&#39;)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Bounty <code>fulfillment</code> data Schema:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> payload: {</span></span> <span class="giallo-l"><span> description: // A string representing the description of the fulfillment, and any necessary links to works</span></span> <span class="giallo-l"><span> sourceFileName: // A string representing the name of the file being submitted</span></span> <span class="giallo-l"><span> sourceFileHash: // A string representing the IPFS hash of the file being submitted</span></span> <span class="giallo-l"><span> sourceDirectoryHash: // A string representing the IPFS hash of the directory which holds the file being submitted</span></span> <span class="giallo-l"><span> fulfillers: {</span></span> <span class="giallo-l"><span> // personas for the individuals whose work is being submitted</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // ------- add optional fields here -------</span></span> <span class="giallo-l"><span> },</span></span> <span class="giallo-l"><span> meta: {</span></span> <span class="giallo-l"><span> platform: // a string representing the original posting platform (ie &#39;gitcoin&#39;)</span></span> <span class="giallo-l"><span> schemaVersion: // a string representing the version number (ie &#39;0.1&#39;)</span></span> <span class="giallo-l"><span> schemaName: // a string representing the name of the schema (ie &#39;standardSchema&#39; or &#39;gitcoinSchema&#39;)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The development of this standard began a year ago, with the goal of encouraging interoperability among bounty implementations on Ethereum. The initial version had significantly more restrictions: a bounty's <code>data</code> could not be changed after issuance (it seemed unfair for bounty <code>issuer</code>s to change the requirements after work is underway), and the bounty payout could not be changed (all funds needed to be deposited in the bounty contract before it could accept submissions).</p> <p>The initial version was also far less extensible, and only allowed for fixed payments to a given set of fulfillments. This new version makes it possible for funds to be split among several correct submissions, for submissions to be shared among several contributors, and for payouts to not only be in a single token as before, but in as many tokens as the <code>issuer</code> of the bounty desires. These design decisions were made after the 8+ months which Gitcoin, the Bounties Network, and Status Open Bounty have been live and meaningfully facilitating bounties for repositories in the Web3.0 ecosystem.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests for our implementation can be found here: https://github.com/Bounties-Network/StandardBounties/tree/develop/test</p> <h2 id="implementation">Implementation</h2> <p>A reference implementation can be found here: https://github.com/Bounties-Network/StandardBounties/blob/develop/contracts/StandardBounty.sol <strong>Although this code has been tested, it has not yet been audited or bug-bountied, so we cannot make any assertions about it's correctness, nor can we presently encourage it's use to hold funds on the Ethereum mainnet.</strong></p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-05T00:00:00+00:00 2026-02-11T14:48:25+00:00 Brooklyn Zelenkahttps://github.com/expede Tom Carchraehttps://github.com/carchrae Gleb Naumenkohttps://github.com/naumenkogs https://wg-eips.ritovision.com/1066/ <h2 id="simple-summary">Simple Summary</h2> <p>Broadly applicable status codes for smart contracts.</p> <h2 id="abstract">Abstract</h2> <p>This standard outlines a common set of status codes in a similar vein to HTTP statuses. This provides a shared set of signals to allow smart contracts to react to situations autonomously, expose localized error messages to users, and so on.</p> <p>The current state of the art is to either <code>revert</code> on anything other than a clear success (ie: require human intervention), or return a low-context <code>true</code> or <code>false</code>. Status codes are similar-but-orthogonal to <code>revert</code>ing with a reason, but aimed at automation, debugging, and end-user feedback (including translation). <em>They are fully compatible with both <code>revert</code> and <code>revert</code>-with-reason.</em></p> <p>As is the case with HTTP, having a standard set of known codes has many benefits for developers. They remove friction from needing to develop your own schemes for every contract, makes inter-contract automation easier, and makes it easier to broadly understand which of the finite states your request produced. Importantly, it makes it much easier to distinguish between expected errors states, truly exceptional conditions that require halting execution, normal state transitions, and various success cases.</p> <h2 id="motivation">Motivation</h2> <h3 id="semantic-density">Semantic Density</h3> <p>HTTP status codes are widely used for this purpose. BEAM languages use atoms and tagged tuples to signify much the same information. Both provide a lot of information both to the programmer (debugging for instance), and to the program that needs to decide what to do next.</p> <p>Status codes convey a much richer set of information <a rel="external" href="https://existentialtype.wordpress.com/2011/03/15/boolean-blindness/">than Booleans</a>, and are able to be reacted to autonomously unlike arbitrary strings.</p> <h3 id="user-experience-ux">User Experience (UX)</h3> <p><em>End users get little to no feedback, and there is no translation layer.</em></p> <p>Since ERC1066 status codes are finite and known in advance, we can leverage <a href="https://wg-eips.ritovision.com/1444/">ERC-1444</a> to provide global, human-readable sets of status messages. These may also be translated into any language, differing levels of technical detail, added as <code>revert</code> messages, natspecs, and so on.</p> <p>Status codes convey a much richer set of information than Booleans, and are able to be reacted to autonomously unlike arbitrary strings.</p> <h3 id="developer-experience-dx">Developer Experience (DX)</h3> <p><em>Developers currently have very little context exposed by their smart contracts.</em></p> <p>At time of writing, other than stepping through EVM execution and inspecting memory dumps directly, it is very difficult to understand what is happening during smart contract execution. By returning more context, developers can write well-decomposed tests and assert certain codes are returned as an expression of where the smart contract got to. This includes status codes as bare values, <code>event</code>s, and <code>revert</code>s.</p> <p>Having a fixed set of codes also makes it possible to write common helper functions to react in common ways to certain signals. This can live off- or on-chain library, lowering the overhead in building smart contracts, and helping raise code quality with trusted shared components.</p> <p>We also see a desire for this <a href="https://wg-eips.ritovision.com/658/">in transactions</a>, and there's no reason that these status codes couldn't be used by the EVM itself.</p> <h3 id="smart-contract-autonomy">Smart Contract Autonomy</h3> <p><em>Smart contracts don’t know much about the result of a request beyond pass/fail; they can be smarter with more context.</em></p> <p>Smart contracts are largely intended to be autonomous. While each contract may define a specific interface, having a common set of semantic codes can help developers write code that can react appropriately to various situations.</p> <p>While clearly related, status codes are complementary to <code>revert</code>-with-reason. Status codes are not limited to rolling back the transaction, and may represent known error states without halting execution. They may also represent off-chain conditions, supply a string to revert, signal time delays, and more.</p> <p>All of this enables contracts to share a common vocabulary of state transitions, results, and internal changes, without having to deeply understand custom status enums or the internal business logic of collaborator contracts.</p> <h2 id="specification">Specification</h2> <h3 id="format">Format</h3> <p>Codes are returned either on their own, or as the first value of a multiple return.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Status only</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isInt</span><span>(</span><span class="z-support">uint</span><span class="z-variable"> num</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> hex</span><span class="z-string">&quot;01&quot;</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Status and value</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-support">uint8</span><span class="z-storage z-type"> private</span><span> counter</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> safeIncrement</span><span>(</span><span class="z-support">uint8</span><span class="z-variable"> interval</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> status</span><span>,</span><span class="z-support"> uint8</span><span class="z-variable"> newCounter</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> uint8</span><span> updated </span><span class="z-keyword">=</span><span> counter </span><span class="z-keyword">+</span><span> interval</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>updated </span><span class="z-keyword">&gt;</span><span class="z-keyword">=</span><span> counter</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> counter </span><span class="z-keyword">=</span><span> updated</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>hex</span><span class="z-string">&quot;01&quot;</span><span>,</span><span> updated</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>hex</span><span class="z-string">&quot;00&quot;</span><span>,</span><span> counter</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="code-table">Code Table</h3> <p>Codes break nicely into a 16x16 matrix, represented as a 2-digit hex number. The high nibble represents the code's kind or "category", and the low nibble contains the state or "reason". We present them below as separate tables per range for explanatory and layout reasons.</p> <p><strong>NB: Unspecified codes are <em>not</em> free for arbitrary use, but rather open for further specification.</strong></p> <h4 id="0x0-generic"><code>0x0*</code> Generic</h4> <p>General codes. These double as bare "reasons", since <code>0x01 == 1</code>.</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>0x00</code></td><td>Failure</td></tr> <tr><td><code>0x01</code></td><td>Success</td></tr> <tr><td><code>0x02</code></td><td>Awaiting Others</td></tr> <tr><td><code>0x03</code></td><td>Accepted</td></tr> <tr><td><code>0x04</code></td><td>Lower Limit or Insufficient</td></tr> <tr><td><code>0x05</code></td><td>Receiver Action Requested</td></tr> <tr><td><code>0x06</code></td><td>Upper Limit</td></tr> <tr><td><code>0x07</code></td><td>[reserved]</td></tr> <tr><td><code>0x08</code></td><td>Duplicate, Unnecessary, or Inapplicable</td></tr> <tr><td><code>0x09</code></td><td>[reserved]</td></tr> <tr><td><code>0x0A</code></td><td>[reserved]</td></tr> <tr><td><code>0x0B</code></td><td>[reserved]</td></tr> <tr><td><code>0x0C</code></td><td>[reserved]</td></tr> <tr><td><code>0x0D</code></td><td>[reserved]</td></tr> <tr><td><code>0x0E</code></td><td>[reserved]</td></tr> <tr><td><code>0x0F</code></td><td>Informational or Metadata</td></tr> </tbody></table> <h4 id="0x1-permission-control"><code>0x1*</code> Permission &amp; Control</h4> <p>Also used for common state machine actions (ex. "stoplight" actions).</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>0x10</code></td><td>Disallowed or Stop</td></tr> <tr><td><code>0x11</code></td><td>Allowed or Go</td></tr> <tr><td><code>0x12</code></td><td>Awaiting Other's Permission</td></tr> <tr><td><code>0x13</code></td><td>Permission Requested</td></tr> <tr><td><code>0x14</code></td><td>Too Open / Insecure</td></tr> <tr><td><code>0x15</code></td><td>Needs Your Permission or Request for Continuation</td></tr> <tr><td><code>0x16</code></td><td>Revoked or Banned</td></tr> <tr><td><code>0x17</code></td><td>[reserved]</td></tr> <tr><td><code>0x18</code></td><td>Not Applicable to Current State</td></tr> <tr><td><code>0x19</code></td><td>[reserved]</td></tr> <tr><td><code>0x1A</code></td><td>[reserved]</td></tr> <tr><td><code>0x1B</code></td><td>[reserved]</td></tr> <tr><td><code>0x1C</code></td><td>[reserved]</td></tr> <tr><td><code>0x1D</code></td><td>[reserved]</td></tr> <tr><td><code>0x1E</code></td><td>[reserved]</td></tr> <tr><td><code>0x1F</code></td><td>Permission Details or Control Conditions</td></tr> </tbody></table> <h4 id="0x2-find-inequalities-range"><code>0x2*</code> Find, Inequalities &amp; Range</h4> <p>This range is broadly intended for finding and matching. Data lookups and order matching are two common use cases.</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>0x20</code></td><td>Not Found, Unequal, or Out of Range</td></tr> <tr><td><code>0x21</code></td><td>Found, Equal or In Range</td></tr> <tr><td><code>0x22</code></td><td>Awaiting Match</td></tr> <tr><td><code>0x23</code></td><td>Match Request Sent</td></tr> <tr><td><code>0x24</code></td><td>Below Range or Underflow</td></tr> <tr><td><code>0x25</code></td><td>Request for Match</td></tr> <tr><td><code>0x26</code></td><td>Above Range or Overflow</td></tr> <tr><td><code>0x27</code></td><td>[reserved]</td></tr> <tr><td><code>0x28</code></td><td>Duplicate, Conflict, or Collision</td></tr> <tr><td><code>0x29</code></td><td>[reserved]</td></tr> <tr><td><code>0x2A</code></td><td>[reserved]</td></tr> <tr><td><code>0x2B</code></td><td>[reserved]</td></tr> <tr><td><code>0x2C</code></td><td>[reserved]</td></tr> <tr><td><code>0x2D</code></td><td>[reserved]</td></tr> <tr><td><code>0x2E</code></td><td>[reserved]</td></tr> <tr><td><code>0x2F</code></td><td>Matching Meta or Info</td></tr> </tbody></table> <h4 id="0x3-negotiation-governance"><code>0x3*</code> Negotiation &amp; Governance</h4> <p>Negotiation, and very broadly the flow of such transactions. Note that "other party" may be more than one actor (not necessarily the sender).</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>0x30</code></td><td>Sender Disagrees or Nay</td></tr> <tr><td><code>0x31</code></td><td>Sender Agrees or Yea</td></tr> <tr><td><code>0x32</code></td><td>Awaiting Ratification</td></tr> <tr><td><code>0x33</code></td><td>Offer Sent or Voted</td></tr> <tr><td><code>0x34</code></td><td>Quorum Not Reached</td></tr> <tr><td><code>0x35</code></td><td>Receiver's Ratification Requested</td></tr> <tr><td><code>0x36</code></td><td>Offer or Vote Limit Reached</td></tr> <tr><td><code>0x37</code></td><td>[reserved]</td></tr> <tr><td><code>0x38</code></td><td>Already Voted</td></tr> <tr><td><code>0x39</code></td><td>[reserved]</td></tr> <tr><td><code>0x3A</code></td><td>[reserved]</td></tr> <tr><td><code>0x3B</code></td><td>[reserved]</td></tr> <tr><td><code>0x3C</code></td><td>[reserved]</td></tr> <tr><td><code>0x3D</code></td><td>[reserved]</td></tr> <tr><td><code>0x3E</code></td><td>[reserved]</td></tr> <tr><td><code>0x3F</code></td><td>Negotiation Rules or Participation Info</td></tr> </tbody></table> <h4 id="0x4-availability-time"><code>0x4*</code> Availability &amp; Time</h4> <p>Service or action availability.</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>0x40</code></td><td>Unavailable</td></tr> <tr><td><code>0x41</code></td><td>Available</td></tr> <tr><td><code>0x42</code></td><td>Paused</td></tr> <tr><td><code>0x43</code></td><td>Queued</td></tr> <tr><td><code>0x44</code></td><td>Not Available Yet</td></tr> <tr><td><code>0x45</code></td><td>Awaiting Your Availability</td></tr> <tr><td><code>0x46</code></td><td>Expired</td></tr> <tr><td><code>0x47</code></td><td>[reserved]</td></tr> <tr><td><code>0x48</code></td><td>Already Done</td></tr> <tr><td><code>0x49</code></td><td>[reserved]</td></tr> <tr><td><code>0x4A</code></td><td>[reserved]</td></tr> <tr><td><code>0x4B</code></td><td>[reserved]</td></tr> <tr><td><code>0x4C</code></td><td>[reserved]</td></tr> <tr><td><code>0x4D</code></td><td>[reserved]</td></tr> <tr><td><code>0x4E</code></td><td>[reserved]</td></tr> <tr><td><code>0x4F</code></td><td>Availability Rules or Info (ex. time since or until)</td></tr> </tbody></table> <h4 id="0x5-tokens-funds-finance"><code>0x5*</code> Tokens, Funds &amp; Finance</h4> <p>Special token and financial concepts. Many related concepts are included in other ranges.</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>0x50</code></td><td>Transfer Failed</td></tr> <tr><td><code>0x51</code></td><td>Transfer Successful</td></tr> <tr><td><code>0x52</code></td><td>Awaiting Payment From Others</td></tr> <tr><td><code>0x53</code></td><td>Hold or Escrow</td></tr> <tr><td><code>0x54</code></td><td>Insufficient Funds</td></tr> <tr><td><code>0x55</code></td><td>Funds Requested</td></tr> <tr><td><code>0x56</code></td><td>Transfer Volume Exceeded</td></tr> <tr><td><code>0x57</code></td><td>[reserved]</td></tr> <tr><td><code>0x58</code></td><td>Funds Not Required</td></tr> <tr><td><code>0x59</code></td><td>[reserved]</td></tr> <tr><td><code>0x5A</code></td><td>[reserved]</td></tr> <tr><td><code>0x5B</code></td><td>[reserved]</td></tr> <tr><td><code>0x5C</code></td><td>[reserved]</td></tr> <tr><td><code>0x5D</code></td><td>[reserved]</td></tr> <tr><td><code>0x5E</code></td><td>[reserved]</td></tr> <tr><td><code>0x5F</code></td><td>Token or Financial Information</td></tr> </tbody></table> <h4 id="0x6-tbd"><code>0x6*</code> TBD</h4> <p>Currently unspecified. (Full range reserved)</p> <h4 id="0x7-tbd"><code>0x7*</code> TBD</h4> <p>Currently unspecified. (Full range reserved)</p> <h4 id="0x8-tbd"><code>0x8*</code> TBD</h4> <p>Currently unspecified. (Full range reserved)</p> <h4 id="0x9-tbd"><code>0x9*</code> TBD</h4> <p>Currently unspecified. (Full range reserved)</p> <h4 id="0xa-application-specific-codes"><code>0xA*</code> Application-Specific Codes</h4> <p>Contracts may have special states that they need to signal. This proposal only outlines the broadest meanings, but implementers may have very specific meanings for each, as long as they are coherent with the broader definition.</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>0xA0</code></td><td>App-Specific Failure</td></tr> <tr><td><code>0xA1</code></td><td>App-Specific Success</td></tr> <tr><td><code>0xA2</code></td><td>App-Specific Awaiting Others</td></tr> <tr><td><code>0xA3</code></td><td>App-Specific Acceptance</td></tr> <tr><td><code>0xA4</code></td><td>App-Specific Below Condition</td></tr> <tr><td><code>0xA5</code></td><td>App-Specific Receiver Action Requested</td></tr> <tr><td><code>0xA6</code></td><td>App-Specific Expiry or Limit</td></tr> <tr><td><code>0xA7</code></td><td>[reserved]</td></tr> <tr><td><code>0xA8</code></td><td>App-Specific Inapplicable Condition</td></tr> <tr><td><code>0xA9</code></td><td>[reserved]</td></tr> <tr><td><code>0xAA</code></td><td>[reserved]</td></tr> <tr><td><code>0xAB</code></td><td>[reserved]</td></tr> <tr><td><code>0xAC</code></td><td>[reserved]</td></tr> <tr><td><code>0xAD</code></td><td>[reserved]</td></tr> <tr><td><code>0xAE</code></td><td>[reserved]</td></tr> <tr><td><code>0xAF</code></td><td>App-Specific Meta or Info</td></tr> </tbody></table> <h4 id="0xb-tbd"><code>0xB*</code> TBD</h4> <p>Currently unspecified. (Full range reserved)</p> <h4 id="0xc-tbd"><code>0xC*</code> TBD</h4> <p>Currently unspecified. (Full range reserved)</p> <h4 id="0xd-tbd"><code>0xD*</code> TBD</h4> <p>Currently unspecified. (Full range reserved)</p> <h4 id="0xe-encryption-identity-proofs"><code>0xE*</code> Encryption, Identity &amp; Proofs</h4> <p>Actions around signatures, cryptography, signing, and application-level authentication.</p> <p>The meta code <code>0xEF</code> is often used to signal a payload describing the algorithm or process used.</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>0xE0</code></td><td>Decrypt Failure</td></tr> <tr><td><code>0xE1</code></td><td>Decrypt Success</td></tr> <tr><td><code>0xE2</code></td><td>Awaiting Other Signatures or Keys</td></tr> <tr><td><code>0xE3</code></td><td>Signed</td></tr> <tr><td><code>0xE4</code></td><td>Unsigned or Untrusted</td></tr> <tr><td><code>0xE5</code></td><td>Signature Required</td></tr> <tr><td><code>0xE6</code></td><td>Known to be Compromised</td></tr> <tr><td><code>0xE7</code></td><td>[reserved]</td></tr> <tr><td><code>0xE8</code></td><td>Already Signed or Not Encrypted</td></tr> <tr><td><code>0xE9</code></td><td>[reserved]</td></tr> <tr><td><code>0xEA</code></td><td>[reserved]</td></tr> <tr><td><code>0xEB</code></td><td>[reserved]</td></tr> <tr><td><code>0xEC</code></td><td>[reserved]</td></tr> <tr><td><code>0xED</code></td><td>[reserved]</td></tr> <tr><td><code>0xEE</code></td><td>[reserved]</td></tr> <tr><td><code>0xEF</code></td><td>Cryptography, ID, or Proof Metadata</td></tr> </tbody></table> <h4 id="0xf-off-chain"><code>0xF*</code> Off-Chain</h4> <p>For off-chain actions. Much like th <code>0x0*: Generic</code> range, <code>0xF*</code> is very general, and does little to modify the reason.</p> <p>Among other things, the meta code <code>0xFF</code> may be used to describe what the off-chain process is.</p> <table><thead><tr><th>Code</th><th>Description</th></tr></thead><tbody> <tr><td><code>0xF0</code></td><td>Off-Chain Failure</td></tr> <tr><td><code>0xF1</code></td><td>Off-Chain Success</td></tr> <tr><td><code>0xF2</code></td><td>Awaiting Off-Chain Process</td></tr> <tr><td><code>0xF3</code></td><td>Off-Chain Process Started</td></tr> <tr><td><code>0xF4</code></td><td>Off-Chain Service Unreachable</td></tr> <tr><td><code>0xF5</code></td><td>Off-Chain Action Required</td></tr> <tr><td><code>0xF6</code></td><td>Off-Chain Expiry or Limit Reached</td></tr> <tr><td><code>0xF7</code></td><td>[reserved]</td></tr> <tr><td><code>0xF8</code></td><td>Duplicate Off-Chain Request</td></tr> <tr><td><code>0xF9</code></td><td>[reserved]</td></tr> <tr><td><code>0xFA</code></td><td>[reserved]</td></tr> <tr><td><code>0xFB</code></td><td>[reserved]</td></tr> <tr><td><code>0xFC</code></td><td>[reserved]</td></tr> <tr><td><code>0xFD</code></td><td>[reserved]</td></tr> <tr><td><code>0xFE</code></td><td>[reserved]</td></tr> <tr><td><code>0xFF</code></td><td>Off-Chain Info or Meta</td></tr> </tbody></table> <h3 id="as-a-grid">As a Grid</h3> <table><thead><tr><th></th><th><code>0x0*</code> General</th><th><code>0x1*</code> Permission &amp; Control</th><th><code>0x2*</code> Find, Inequalities &amp; Range</th><th><code>0x3*</code> Negotiation &amp; Governance</th><th><code>0x4*</code> Availability &amp; Time</th><th><code>0x5*</code> Tokens, Funds &amp; Finance</th><th><code>0x6*</code> TBD</th><th><code>0x7*</code> TBD</th><th><code>0x8*</code> TBD</th><th><code>0x9*</code> TBD</th><th><code>0xA*</code> Application-Specific Codes</th><th><code>0xB*</code> TBD</th><th><code>0xC*</code> TBD</th><th><code>0xD*</code> TBD</th><th><code>0xE*</code> Encryption, Identity &amp; Proofs</th><th><code>0xF*</code> Off-Chain</th></tr></thead><tbody> <tr><td><code>0x*0</code></td><td><code>0x00</code> Failure</td><td><code>0x10</code> Disallowed or Stop</td><td><code>0x20</code> Not Found, Unequal, or Out of Range</td><td><code>0x30</code> Sender Disagrees or Nay</td><td><code>0x40</code> Unavailable</td><td><code>0x50</code> Transfer Failed</td><td><code>0x60</code> [reserved]</td><td><code>0x70</code> [reserved]</td><td><code>0x80</code> [reserved]</td><td><code>0x90</code> [reserved]</td><td><code>0xA0</code> App-Specific Failure</td><td><code>0xB0</code> [reserved]</td><td><code>0xC0</code> [reserved]</td><td><code>0xD0</code> [reserved]</td><td><code>0xE0</code> Decrypt Failure</td><td><code>0xF0</code> Off-Chain Failure</td></tr> <tr><td><code>0x*1</code></td><td><code>0x01</code> Success</td><td><code>0x11</code> Allowed or Go</td><td><code>0x21</code> Found, Equal or In Range</td><td><code>0x31</code> Sender Agrees or Yea</td><td><code>0x41</code> Available</td><td><code>0x51</code> Transfer Successful</td><td><code>0x61</code> [reserved]</td><td><code>0x71</code> [reserved]</td><td><code>0x81</code> [reserved]</td><td><code>0x91</code> [reserved]</td><td><code>0xA1</code> App-Specific Success</td><td><code>0xB1</code> [reserved]</td><td><code>0xC1</code> [reserved]</td><td><code>0xD1</code> [reserved]</td><td><code>0xE1</code> Decrypt Success</td><td><code>0xF1</code> Off-Chain Success</td></tr> <tr><td><code>0x*2</code></td><td><code>0x02</code> Awaiting Others</td><td><code>0x12</code> Awaiting Other's Permission</td><td><code>0x22</code> Awaiting Match</td><td><code>0x32</code> Awaiting Ratification</td><td><code>0x42</code> Paused</td><td><code>0x52</code> Awaiting Payment From Others</td><td><code>0x62</code> [reserved]</td><td><code>0x72</code> [reserved]</td><td><code>0x82</code> [reserved]</td><td><code>0x92</code> [reserved]</td><td><code>0xA2</code> App-Specific Awaiting Others</td><td><code>0xB2</code> [reserved]</td><td><code>0xC2</code> [reserved]</td><td><code>0xD2</code> [reserved]</td><td><code>0xE2</code> Awaiting Other Signatures or Keys</td><td><code>0xF2</code> Awaiting Off-Chain Process</td></tr> <tr><td><code>0x*3</code></td><td><code>0x03</code> Accepted</td><td><code>0x13</code> Permission Requested</td><td><code>0x23</code> Match Request Sent</td><td><code>0x33</code> Offer Sent or Voted</td><td><code>0x43</code> Queued</td><td><code>0x53</code> Hold or Escrow</td><td><code>0x63</code> [reserved]</td><td><code>0x73</code> [reserved]</td><td><code>0x83</code> [reserved]</td><td><code>0x93</code> [reserved]</td><td><code>0xA3</code> App-Specific Acceptance</td><td><code>0xB3</code> [reserved]</td><td><code>0xC3</code> [reserved]</td><td><code>0xD3</code> [reserved]</td><td><code>0xE3</code> Signed</td><td><code>0xF3</code> Off-Chain Process Started</td></tr> <tr><td><code>0x*4</code></td><td><code>0x04</code> Lower Limit or Insufficient</td><td><code>0x14</code> Too Open / Insecure</td><td><code>0x24</code> Below Range or Underflow</td><td><code>0x34</code> Quorum Not Reached</td><td><code>0x44</code> Not Available Yet</td><td><code>0x54</code> Insufficient Funds</td><td><code>0x64</code> [reserved]</td><td><code>0x74</code> [reserved]</td><td><code>0x84</code> [reserved]</td><td><code>0x94</code> [reserved]</td><td><code>0xA4</code> App-Specific Below Condition</td><td><code>0xB4</code> [reserved]</td><td><code>0xC4</code> [reserved]</td><td><code>0xD4</code> [reserved]</td><td><code>0xE4</code> Unsigned or Untrusted</td><td><code>0xF4</code> Off-Chain Service Unreachable</td></tr> <tr><td><code>0x*5</code></td><td><code>0x05</code> Receiver Action Required</td><td><code>0x15</code> Needs Your Permission or Request for Continuation</td><td><code>0x25</code> Request for Match</td><td><code>0x35</code> Receiver's Ratification Requested</td><td><code>0x45</code> Awaiting Your Availability</td><td><code>0x55</code> Funds Requested</td><td><code>0x65</code> [reserved]</td><td><code>0x75</code> [reserved]</td><td><code>0x85</code> [reserved]</td><td><code>0x95</code> [reserved]</td><td><code>0xA5</code> App-Specific Receiver Action Requested</td><td><code>0xB5</code> [reserved]</td><td><code>0xC5</code> [reserved]</td><td><code>0xD5</code> [reserved]</td><td><code>0xE5</code> Signature Required</td><td><code>0xF5</code> Off-Chain Action Required</td></tr> <tr><td><code>0x*6</code></td><td><code>0x06</code> Upper Limit</td><td><code>0x16</code> Revoked or Banned</td><td><code>0x26</code> Above Range or Overflow</td><td><code>0x36</code> Offer or Vote Limit Reached</td><td><code>0x46</code> Expired</td><td><code>0x56</code> Transfer Volume Exceeded</td><td><code>0x66</code> [reserved]</td><td><code>0x76</code> [reserved]</td><td><code>0x86</code> [reserved]</td><td><code>0x96</code> [reserved]</td><td><code>0xA6</code> App-Specific Expiry or Limit</td><td><code>0xB6</code> [reserved]</td><td><code>0xC6</code> [reserved]</td><td><code>0xD6</code> [reserved]</td><td><code>0xE6</code> Known to be Compromised</td><td><code>0xF6</code> Off-Chain Expiry or Limit Reached</td></tr> <tr><td><code>0x*7</code></td><td><code>0x07</code> [reserved]</td><td><code>0x17</code> [reserved]</td><td><code>0x27</code> [reserved]</td><td><code>0x37</code> [reserved]</td><td><code>0x47</code> [reserved]</td><td><code>0x57</code> [reserved]</td><td><code>0x67</code> [reserved]</td><td><code>0x77</code> [reserved]</td><td><code>0x87</code> [reserved]</td><td><code>0x97</code> [reserved]</td><td><code>0xA7</code> [reserved]</td><td><code>0xB7</code> [reserved]</td><td><code>0xC7</code> [reserved]</td><td><code>0xD7</code> [reserved]</td><td><code>0xE7</code> [reserved]</td><td><code>0xF7</code> [reserved]</td></tr> <tr><td><code>0x*8</code></td><td><code>0x08</code> Duplicate, Unnecessary, or Inapplicable</td><td><code>0x18</code> Not Applicable to Current State</td><td><code>0x28</code> Duplicate, Conflict, or Collision</td><td><code>0x38</code> Already Voted</td><td><code>0x48</code> Already Done</td><td><code>0x58</code> Funds Not Required</td><td><code>0x68</code> [reserved]</td><td><code>0x78</code> [reserved]</td><td><code>0x88</code> [reserved]</td><td><code>0x98</code> [reserved]</td><td><code>0xA8</code> App-Specific Inapplicable Condition</td><td><code>0xB8</code> [reserved]</td><td><code>0xC8</code> [reserved]</td><td><code>0xD8</code> [reserved]</td><td><code>0xE8</code> Already Signed or Not Encrypted</td><td><code>0xF8</code> Duplicate Off-Chain Request</td></tr> <tr><td><code>0x*9</code></td><td><code>0x09</code> [reserved]</td><td><code>0x19</code> [reserved]</td><td><code>0x29</code> [reserved]</td><td><code>0x39</code> [reserved]</td><td><code>0x49</code> [reserved]</td><td><code>0x59</code> [reserved]</td><td><code>0x69</code> [reserved]</td><td><code>0x79</code> [reserved]</td><td><code>0x89</code> [reserved]</td><td><code>0x99</code> [reserved]</td><td><code>0xA9</code> [reserved]</td><td><code>0xB9</code> [reserved]</td><td><code>0xC9</code> [reserved]</td><td><code>0xD9</code> [reserved]</td><td><code>0xE9</code> [reserved]</td><td><code>0xF9</code> [reserved]</td></tr> <tr><td><code>0x*A</code></td><td><code>0x0A</code> [reserved]</td><td><code>0x1A</code> [reserved]</td><td><code>0x2A</code> [reserved]</td><td><code>0x3A</code> [reserved]</td><td><code>0x4A</code> [reserved]</td><td><code>0x5A</code> [reserved]</td><td><code>0x6A</code> [reserved]</td><td><code>0x7A</code> [reserved]</td><td><code>0x8A</code> [reserved]</td><td><code>0x9A</code> [reserved]</td><td><code>0xAA</code> [reserved]</td><td><code>0xBA</code> [reserved]</td><td><code>0xCA</code> [reserved]</td><td><code>0xDA</code> [reserved]</td><td><code>0xEA</code> [reserved]</td><td><code>0xFA</code> [reserved]</td></tr> <tr><td><code>0x*B</code></td><td><code>0x0B</code> [reserved]</td><td><code>0x1B</code> [reserved]</td><td><code>0x2B</code> [reserved]</td><td><code>0x3B</code> [reserved]</td><td><code>0x4B</code> [reserved]</td><td><code>0x5B</code> [reserved]</td><td><code>0x6B</code> [reserved]</td><td><code>0x7B</code> [reserved]</td><td><code>0x8B</code> [reserved]</td><td><code>0x9B</code> [reserved]</td><td><code>0xAB</code> [reserved]</td><td><code>0xBB</code> [reserved]</td><td><code>0xCB</code> [reserved]</td><td><code>0xDB</code> [reserved]</td><td><code>0xEB</code> [reserved]</td><td><code>0xFB</code> [reserved]</td></tr> <tr><td><code>0x*C</code></td><td><code>0x0C</code> [reserved]</td><td><code>0x1C</code> [reserved]</td><td><code>0x2C</code> [reserved]</td><td><code>0x3C</code> [reserved]</td><td><code>0x4C</code> [reserved]</td><td><code>0x5C</code> [reserved]</td><td><code>0x6C</code> [reserved]</td><td><code>0x7C</code> [reserved]</td><td><code>0x8C</code> [reserved]</td><td><code>0x9C</code> [reserved]</td><td><code>0xAC</code> [reserved]</td><td><code>0xBC</code> [reserved]</td><td><code>0xCC</code> [reserved]</td><td><code>0xDC</code> [reserved]</td><td><code>0xEC</code> [reserved]</td><td><code>0xFC</code> [reserved]</td></tr> <tr><td><code>0x*D</code></td><td><code>0x0D</code> [reserved]</td><td><code>0x1D</code> [reserved]</td><td><code>0x2D</code> [reserved]</td><td><code>0x3D</code> [reserved]</td><td><code>0x4D</code> [reserved]</td><td><code>0x5D</code> [reserved]</td><td><code>0x6D</code> [reserved]</td><td><code>0x7D</code> [reserved]</td><td><code>0x8D</code> [reserved]</td><td><code>0x9D</code> [reserved]</td><td><code>0xAD</code> [reserved]</td><td><code>0xBD</code> [reserved]</td><td><code>0xCD</code> [reserved]</td><td><code>0xDD</code> [reserved]</td><td><code>0xED</code> [reserved]</td><td><code>0xFD</code> [reserved]</td></tr> <tr><td><code>0x*E</code></td><td><code>0x0E</code> [reserved]</td><td><code>0x1E</code> [reserved]</td><td><code>0x2E</code> [reserved]</td><td><code>0x3E</code> [reserved]</td><td><code>0x4E</code> [reserved]</td><td><code>0x5E</code> [reserved]</td><td><code>0x6E</code> [reserved]</td><td><code>0x7E</code> [reserved]</td><td><code>0x8E</code> [reserved]</td><td><code>0x9E</code> [reserved]</td><td><code>0xAE</code> [reserved]</td><td><code>0xBE</code> [reserved]</td><td><code>0xCE</code> [reserved]</td><td><code>0xDE</code> [reserved]</td><td><code>0xEE</code> [reserved]</td><td><code>0xFE</code> [reserved]</td></tr> <tr><td><code>0x*F</code></td><td><code>0x0F</code> Informational or Metadata</td><td><code>0x1F</code> Permission Details or Control Conditions</td><td><code>0x2F</code> Matching Meta or Info</td><td><code>0x3F</code> Negotiation Rules or Participation Info</td><td><code>0x4F</code> Availability Rules or Info (ex. time since or until)</td><td><code>0x5F</code> Token or Financial Information</td><td><code>0x6F</code> [reserved]</td><td><code>0x7F</code> [reserved]</td><td><code>0x8F</code> [reserved]</td><td><code>0x9F</code> [reserved]</td><td><code>0xAF</code> App-Specific Meta or Info</td><td><code>0xBF</code> [reserved]</td><td><code>0xCF</code> [reserved]</td><td><code>0xDF</code> [reserved]</td><td><code>0xEF</code> Cryptography, ID, or Proof Metadata</td><td><code>0xFF</code> Off-Chain Info or Meta</td></tr> </tbody></table> <h3 id="example-function-change">Example Function Change</h3> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint256</span><span class="z-storage z-type"> private</span><span> startTime</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint</span><span>)</span><span class="z-storage z-type"> private</span><span> counters</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Before</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> increase</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable z-parameter z-function"> _available</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-language">now</span><span class="z-keyword"> &lt;</span><span> startTime </span><span class="z-keyword">&amp;&amp;</span><span> counters</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> counters</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> After</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> increase</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable z-parameter z-function"> _status</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-language">now</span><span class="z-keyword"> &lt;</span><span> start</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> hex</span><span class="z-string">&quot;44&quot;</span><span>;</span><span> }</span><span class="z-comment"> //</span><span class="z-comment"> Not yet available</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>counters</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> hex</span><span class="z-string">&quot;10&quot;</span><span>;</span><span> }</span><span class="z-comment"> //</span><span class="z-comment"> Not authorized</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> counters</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> +</span><span class="z-keyword">=</span><span class="z-constant"> 1</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> hex</span><span class="z-string">&quot;01&quot;</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> Success</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="example-sequence-diagrams">Example Sequence Diagrams</h3> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x03 = Waiting</span></span> <span class="giallo-l"><span>0x31 = Other Party (ie: not you) Agreed</span></span> <span class="giallo-l"><span>0x41 = Available</span></span> <span class="giallo-l"><span>0x44 = Not Yet Available</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Exchange</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>AwesomeCoin DEX TraderBot</span></span> <span class="giallo-l"><span> + + +</span></span> <span class="giallo-l"><span> | | buy(AwesomeCoin) |</span></span> <span class="giallo-l"><span> | | &lt;------------------------+</span></span> <span class="giallo-l"><span> | buy() | |</span></span> <span class="giallo-l"><span> | &lt;---------------------+ |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | Status [0x44] | |</span></span> <span class="giallo-l"><span> +---------------------&gt; | Status [0x44] |</span></span> <span class="giallo-l"><span> | +------------------------&gt; |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | | isDoneYet() |</span></span> <span class="giallo-l"><span> | | &lt;------------------------+</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | | Status [0x44] |</span></span> <span class="giallo-l"><span> | +------------------------&gt; |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | Status [0x41] | |</span></span> <span class="giallo-l"><span> +---------------------&gt; | |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | buy() | |</span></span> <span class="giallo-l"><span> | &lt;---------------------+ |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | Status [0x31] | |</span></span> <span class="giallo-l"><span> +---------------------&gt; | Status [0x31] |</span></span> <span class="giallo-l"><span> | +------------------------&gt; |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> | | |</span></span> <span class="giallo-l"><span> + + +</span></span></code></pre><pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x01 = Generic Success</span></span> <span class="giallo-l"><span>0x10 = Disallowed</span></span> <span class="giallo-l"><span>0x11 = Allowed</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Token Validation</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span> Buyer RegulatedToken TokenValidator IDChecker SpendLimiter</span></span> <span class="giallo-l"><span> + + + + +</span></span> <span class="giallo-l"><span> | buy() | | | |</span></span> <span class="giallo-l"><span> +------------------------&gt; | check() | | |</span></span> <span class="giallo-l"><span> | +-----------------------&gt; | check() | |</span></span> <span class="giallo-l"><span> | | +-----------------------&gt; | |</span></span> <span class="giallo-l"><span> | | | | |</span></span> <span class="giallo-l"><span> | | | Status [0x10] | |</span></span> <span class="giallo-l"><span> | | Status [0x10] | &lt;-----------------------+ |</span></span> <span class="giallo-l"><span> | revert() | &lt;-----------------------+ | |</span></span> <span class="giallo-l"><span> | &lt;------------------------+ | | |</span></span> <span class="giallo-l"><span> | | | | |</span></span> <span class="giallo-l"><span>+---------------------------+ | | | |</span></span> <span class="giallo-l"><span>| | | | | |</span></span> <span class="giallo-l"><span>| Updates ID with provider | | | | |</span></span> <span class="giallo-l"><span>| | | | | |</span></span> <span class="giallo-l"><span>+---------------------------+ | | | |</span></span> <span class="giallo-l"><span> | | | | |</span></span> <span class="giallo-l"><span> | buy() | | | |</span></span> <span class="giallo-l"><span> +------------------------&gt; | check() | | |</span></span> <span class="giallo-l"><span> | +-----------------------&gt; | check() | |</span></span> <span class="giallo-l"><span> | | +-----------------------&gt; | |</span></span> <span class="giallo-l"><span> | | | | |</span></span> <span class="giallo-l"><span> | | | Status [0x11] | |</span></span> <span class="giallo-l"><span> | | | &lt;-----------------------+ |</span></span> <span class="giallo-l"><span> | | | | |</span></span> <span class="giallo-l"><span> | | | | check() |</span></span> <span class="giallo-l"><span> | | +-------------------------------------------&gt; |</span></span> <span class="giallo-l"><span> | | | | |</span></span> <span class="giallo-l"><span> | | | | Status [0x11] |</span></span> <span class="giallo-l"><span> | | Status [0x11] | &lt;-------------------------------------------+</span></span> <span class="giallo-l"><span> | Status [0x01] | &lt;-----------------------+ | |</span></span> <span class="giallo-l"><span> | &lt;------------------------+ | | |</span></span> <span class="giallo-l"><span> | | | | |</span></span> <span class="giallo-l"><span> | | | | |</span></span> <span class="giallo-l"><span> | | | | |</span></span> <span class="giallo-l"><span> + + + + +</span></span></code></pre><h2 id="rationale">Rationale</h2> <h3 id="encoding">Encoding</h3> <p>Status codes are encoded as a <code>byte</code>. Hex values break nicely into high and low nibbles: <code>category</code> and <code>reason</code>. For instance, <code>0x01</code> stands for general success (ie: <code>true</code>) and <code>0x00</code> for general failure (ie: <code>false</code>).</p> <p>As a general approach, all even numbers are blocking conditions (where the receiver does not have control), and odd numbers are nonblocking (the receiver is free to continue as they wish). This aligns both a simple bit check with the common encoding of Booleans.</p> <p><code>bytes1</code> is very lightweight, portable, easily interoperable with <code>uint8</code>, cast from <code>enum</code>s, and so on.</p> <h4 id="alternatives">Alternatives</h4> <p>Alternate schemes include <code>bytes32</code> and <code>uint8</code>. While these work reasonably well, they have drawbacks.</p> <p><code>uint8</code> feels even more similar to HTTP status codes, and enums don't require as much casting. However does not break as evenly as a square table (256 doesn't look as nice in base 10).</p> <p>Packing multiple codes into a single <code>bytes32</code> is nice in theory, but poses additional challenges. Unused space may be interpreted as <code>0x00 Failure</code>, you can only efficiently pack four codes at once, and there is a challenge in ensuring that code combinations are sensible. Forcing four codes into a packed representation encourages multiple status codes to be returned, which is often more information than strictly necessarily. This can lead to paradoxical results (ex <code>0x00</code> and <code>0x01</code> together), or greater resources allocated to interpreting 256<sup>4</sup> (4.3 billion) permutations.</p> <h3 id="multiple-returns">Multiple Returns</h3> <p>While there may be cases where packing a byte array of status codes may make sense, the simplest, most forwards-compatible method of transmission is as the first value of a multiple return.</p> <p>Familiarity is also a motivating factor. A consistent position and encoding together follow the principle of least surprise. It is both viewable as a "header" in the HTTP analogy, or like the "tag" in BEAM tagged tuples.</p> <h3 id="human-readable">Human Readable</h3> <p>Developers should not be required to memorize 256 codes. However, they break nicely into a table. Cognitive load is lowered by organizing the table into categories and reasons. <code>0x10</code> and <code>0x11</code> belong to the same category, and <code>0x04</code> shares a reason with <code>0x24</code></p> <p>While this repository includes helper enums, we have found working directly in the hex values to be quite natural. Status code <code>0x10</code> is just as comfortable as HTTP 401, for example.</p> <h4 id="localizations">Localizations</h4> <p>One commonly requested application of this spec is human-readable translations of codes. This has been moved to its own proposal: <a href="https://wg-eips.ritovision.com/1444/">ERC-1444</a>, primarily due to a desire to keep both specs focused.</p> <h3 id="extensibility">Extensibility</h3> <p>The <code>0xA</code> category is reserved for application-specific statuses. In the case that 256 codes become insufficient, <code>bytes1</code> may be embedded in larger byte arrays.</p> <h3 id="evm-codes">EVM Codes</h3> <p>The EVM also returns a status code in transactions; specifically <code>0x00</code> and <code>0x01</code>. This proposal both matches the meanings of those two codes, and could later be used at the EVM level.</p> <h3 id="empty-space">Empty Space</h3> <p>Much like how HTTP status codes have large unused ranges, there are totally empty sections in this proposal. The intent is to not impose a complete set of codes up front, and to allow users to suggest uses for these spaces as time progresses.</p> <h3 id="beyond-errors">Beyond Errors</h3> <p>This spec is intended to be much more than a set of common errors. One design goal is to enable easier contract-to-contract communication, protocols built on top of status codes, and flows that cross off-chain. Many of these cases include either expected kinds of exception state (as opposed to true errors), neutral states, time logic, and various successes.</p> <p>Just like how HTTP 200 has a different meaning from HTTP 201, ERC-1066 status codes can relay information between contract beyond simply pass or fail. They can be thought of as the edges in a graph that has smart contracts as nodes.</p> <h3 id="fully-revertable">Fully <code>revert</code>able</h3> <p><em>This spec is fully compatible with <code>revert</code>-with-reason and does not intend to supplant it in any way.</em> Both by reverting with a common code, the developer can determine what went wrong from a set of known error states.</p> <p>Further, by leveraging ERC-1066 and a translation table (such as in ERC-1444) in conjunction, developers and end users alike can receive fully automated human-readable error messages in the language and phrasing of their choice.</p> <h3 id="nibble-order">Nibble Order</h3> <p>Nibble order makes no difference to the machine, and is purely mnemonic. This design was originally in opposite order, but changed it for a few convenience factors. Since it's a different scheme from HTTP, it may feel strange initially, but becomes very natural after a couple hours of use.</p> <h4 id="short-forms">Short Forms</h4> <p>Generic is <code>0x0*</code>, general codes are consistent with their integer representations</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>hex</span><span class="z-string">&quot;1&quot;</span><span class="z-keyword"> ==</span><span> hex</span><span class="z-string">&quot;01&quot;</span><span class="z-keyword"> ==</span><span class="z-constant"> 1</span><span class="z-comment"> //</span><span class="z-comment"> with casting</span></span></code></pre><h4 id="contract-categories">Contract Categories</h4> <p>Many applications will always be part of the same category. For instance, validation will generally be in the <code>0x10</code> range.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> Whitelist</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> bool</span><span>)</span><span class="z-storage z-type"> private</span><span> whitelist</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-storage z-type"> private</span><span> deadline</span><span>;</span></span> <span class="giallo-l"><span> byte </span><span class="z-storage z-type">constant</span><span class="z-storage z-type"> private</span><span> prefix </span><span class="z-keyword">=</span><span> hex</span><span class="z-string">&quot;10&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> check</span><span>(</span><span class="z-support">address</span><span class="z-constant"> _</span><span>,</span><span class="z-support"> address</span><span> _user</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable z-parameter z-function"> _status</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-language">now</span><span class="z-keyword"> &gt;</span><span class="z-keyword">=</span><span> deadline</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> prefix </span><span class="z-keyword">|</span><span class="z-constant"> 5</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>whitelist</span><span>[</span><span>_user</span><span>]</span><span>)</span><span> {</span><span class="z-keyword"> return</span><span> prefix </span><span class="z-keyword">|</span><span class="z-constant"> 1</span><span>;</span><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> prefix</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="helpers">Helpers</h4> <p>This above also means that working with app-specific enums is slightly easier, and also saves gas (fewer operations required).</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">enum</span><span class="z-entity z-name"> Sleep</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Awake</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> Asleep</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> BedOccupied</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other z-enummember"> WindingDown</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> From the helper library</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> appCode</span><span>(</span><span class="z-storage z-type">Sleep</span><span class="z-variable z-parameter z-function"> _state</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> code</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> byte</span><span>(</span><span class="z-constant">160</span><span class="z-keyword"> +</span><span> _state</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 160 = 0xA0</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment">//</span><span class="z-comment"> Versus</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> appCode</span><span>(</span><span class="z-storage z-type">Sleep</span><span class="z-variable z-parameter z-function"> _state</span><span>)</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> code</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> byte</span><span>(</span><span>(</span><span class="z-constant">16</span><span class="z-keyword"> *</span><span> _state</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 10</span><span>)</span><span>;</span><span class="z-comment"> //</span><span class="z-comment"> 10 = 0xA</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>Reference cases and helper libraries (Solidity and JS) can be found at:</p> <ul> <li><a rel="external" href="https://github.com/fission-suite/fission-codes/">Source Code</a></li> <li><a rel="external" href="https://www.npmjs.com/package/fission-codes/">Package on npm</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alex Van de Sandeavsa@ethereum.org Ricardo Guilherme Schmidthttps://github.com/3esmit https://wg-eips.ritovision.com/1077/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for gas abstraction in top of smart contracts.</p> <p>Allows users to offer <a href="https://wg-eips.ritovision.com/20/">EIP-20</a> token for paying the gas used in a call.</p> <h2 id="abstract">Abstract</h2> <p>A main barrier for the adoption of DApps is the requirement of multiple tokens for executing in chain actions. Allowing users to sign messages to show intent of execution, but allowing a third party relayer to execute them can circumvent this problem, while ETH will always be required for ethereum transactions, it's possible for smart contract to take <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> signatures and forward a payment incentive to an untrusted party with ETH for executing the transaction.</p> <h2 id="motivation">Motivation</h2> <p>Standardizing a common format for them, as well as a way in which the user allows the transaction to be paid in tokens, gives app developers a lot of flexibility and can become the main way in which app users interact with the Blockchain.</p> <h2 id="specification">Specification</h2> <h3 id="methods">Methods</h3> <h4 id="executegasrelay">executeGasRelay</h4> <p>Executes <code>_execData</code> with current <code>lastNonce()</code> and pays <code>msg.sender</code> the gas used in specified <code>_gasToken</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> executeGasRelay</span><span>(</span><span class="z-support">bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _execData</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _gasPrice</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _gasLimit</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _gasToken</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _gasRelayer</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> calldata</span><span class="z-variable z-parameter z-function"> _signature</span><span>)</span><span class="z-storage z-type"> external</span><span>;</span><span> </span></span></code></pre><h3 id="executegasrelaymsg">executeGasRelayMsg</h3> <p>Returns the <code>executeGasRelay</code> message used for signing messages..</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> executeGasRelayMsg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _nonce</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _execData</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _gasPrice</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _gasLimit</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _gasToken</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _gasRelayer</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h4 id="executegasrelayerc191msg">executeGasRelayERC191Msg</h4> <p>Returns the <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> of <code>executeGasRelayMsg</code> used for signing messages and for verifying the execution.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> executeGasRelayERC191Msg</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _nonce</span><span>,</span><span class="z-support"> bytes</span><span class="z-storage z-type"> memory</span><span class="z-variable z-parameter z-function"> _execData</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _gasPrice</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable z-parameter z-function"> _gasLimit</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _gasToken</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _gasRelayer</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</span><span class="z-storage z-type"> memory</span><span>)</span><span>;</span></span></code></pre><h4 id="lastnonce">lastNonce</h4> <p>Returns the current nonce for the gas relayed messages.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> lastNonce</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span class="z-variable"> nonce</span><span>)</span><span>;</span></span></code></pre><h3 id="signed-message">Signed Message</h3> <p>The signed message require the following fields:</p> <ul> <li>Nonce: A nonce <em>or</em> a timestamp;</li> <li>Execute Data: the bytecode to be executed by the account contract;</li> <li>Gas Price: The gas price (paid in the selected token);</li> <li>Gas Limit: The gas reserved to the relayed execution;</li> <li>Gas Token: A token in which the gas will be paid (leave 0 for ether);</li> <li>Gas Relayer: the beneficiary of gas refund for this call (leave 0 for <code>block.coinbase</code>) .</li> </ul> <h4 id="signing-the-message">Signing the message</h4> <p>The message <strong>MUST</strong> be signed as <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> standard, and the called contract <strong>MUST</strong> also implement <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> which must validate the signed messages.</p> <p>Messages <strong>MUST</strong> be signed by the owner of the account contract executing. If the owner is a contract, it must implement <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> interface and forward validation to it.</p> <p>In order to be compliant, the transaction <strong>MUST</strong> request to sign a "messageHash" that is a concatenation of multiple fields.</p> <p>The fields <strong>MUST</strong> be constructed as this method:</p> <p>The first and second fields are to make it <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> compliant. Starting a transaction with <code>byte(0x19)</code> ensure the signed data from being a <a rel="external" href="https://github.com/ethereum/wiki/wiki/RLP">valid ethereum transaction</a>. The second argument is a version control byte. The third being the validator address (the account contract address) according to version 0 of <a href="https://wg-eips.ritovision.com/191/">EIP-191</a>. The remaining arguments being the application specific data for the gas relay: chainID as per <a href="https://wg-eips.ritovision.com/1344/">EIP-1344</a>, execution nonce, execution data, agreed gas Price, gas limit of gas relayed call, gas token to pay back and gas relayer authorized to receive the reward.</p> <p>The <a href="https://wg-eips.ritovision.com/191/">EIP-191</a> message must be constructed as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">keccak256</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> byte</span><span>(</span><span class="z-constant">0x19</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment">ERC-191 - the initial 0x19 byte</span></span> <span class="giallo-l"><span class="z-entity z-name"> byte</span><span>(</span><span class="z-constant">0x0</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment">ERC-191 - the version byte</span></span> <span class="giallo-l"><span class="z-support"> address</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-comment"> //</span><span class="z-comment">ERC-191 - version data (validator address)</span></span> <span class="giallo-l"><span> chainID</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> bytes4</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> keccak256</span><span>(</span><span class="z-string">&quot;executeGasRelay(uint256,bytes,uint256,uint256,address,address)&quot;</span><span>)</span></span> <span class="giallo-l"><span> )</span><span>,</span></span> <span class="giallo-l"><span> _nonce</span><span>,</span><span> </span></span> <span class="giallo-l"><span> _execData</span><span>,</span></span> <span class="giallo-l"><span> _gasPrice</span><span>,</span></span> <span class="giallo-l"><span> _gasLimit</span><span>,</span></span> <span class="giallo-l"><span> _gasToken</span><span>,</span></span> <span class="giallo-l"><span> _gasRelayer</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>User pain points:</p> <ul> <li>users don't want to think about ether</li> <li>users don't want to think about backing up private keys or seed phrases</li> <li>users want to be able to pay for transactions using what they already have on the system, be apple pay, xbox points or even a credit card</li> <li>Users don’t want to sign a new transaction at every move</li> <li>Users don’t want to download apps/extensions (at least on the desktop) to connect to their apps</li> </ul> <p>App developer pain points:</p> <ul> <li>Many apps use their own token and would prefer to use those as the main accounting</li> <li>Apps want to be able to have apps in multiple platforms without having to share private keys between devices or have to spend transaction costs moving funds between them</li> <li>Token developers want to be able for their users to be able to move funds and pay fees in the token</li> <li>While the system provides fees and incentives for miners, there are no inherent business model for wallet developers (or other apps that initiate many transactions)</li> </ul> <p>Using signed messages, specially combined with an account contract that holds funds, and multiple disposable ether-less keys that can sign on its behalf, solves many of these pain points.</p> <h3 id="multiple-signatures">Multiple signatures</h3> <p>More than one signed transaction with the same parameter can be executed by this function at the same time, by passing all signatures in the <code>messageSignatures</code> field. That field will split the signature in multiple 72 character individual signatures and evaluate each one. This is used for cases in which one action might require the approval of multiple parties, in a single transaction.</p> <p>If multiple signatures are required, then all signatures should then be <em>ordered by account</em> and the account contract should implement signatures checks locally (<code>JUMP</code>) on <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> interface which might forward (<code>STATIC_CALL</code>) the <a href="https://wg-eips.ritovision.com/1271/">EIP-1271</a> signature check to owner contract.</p> <h3 id="keep-track-of-nonces">Keep track of nonces:</h3> <p>Note that <code>executeGasRelay</code> function does not take a <code>_nonce</code> as parameter. The contract knows what is the current nonce, and can only execute the transactions in order, therefore there is no reason</p> <p>Nonces work similarly to normal ethereum transactions: a transaction can only be executed if it matches the last nonce + 1, and once a transaction has occurred, the <code>lastNonce</code> will be updated to the current one. This prevents transactions to be executed out of order or more than once.</p> <p>Contracts may accept transactions without nonce (nonce = 0). The contract then must keep the full hash of the transaction to prevent it from being replayed. This would allows contracts to have more flexibilities as you can sign a transaction that can be executed out of order or not at all, but it uses more memory for each transaction. It can be used, for instance, for transactions that the user wants to schedule in the future but cannot know its future nonce, or transactions that are made for state channel contracts that are not guaranteed to be executed or are only executed when there's some dispute.</p> <h3 id="execute-transaction">Execute transaction</h3> <p>After signature validation, the evaluation of <code>_execBytes</code> is up to the account contract implementation, it's role of the wallet to properly use the account contract and it's gas relay method. A common pattern is to expose an interface which can be only called by the contract itself. The <code>_execBytes</code> could entirely forward the call in this way, as example: <code>address(this).call.gas(_gasLimit)(_execData);</code> Where <code>_execData</code> could call any method of the contract itself, for example:</p> <ul> <li><code>call(address to, uint256 value, bytes data)</code>: allow any type of ethereum call be performed;</li> <li><code>create(uint256 value, bytes deployData)</code>: allows create contract</li> <li><code>create2(uint256 value, bytes32 salt, bytes deployData)</code>: allows create contract with deterministic address</li> <li><code>approveAndCall(address token, address to, uint256 value, bytes data)</code>: allows safe approve and call of an ERC20 token.</li> <li><code>delegatecall(address codeBase, bytes data)</code>: allows executing code stored on other contract</li> <li><code>changeOwner(address newOwner)</code>: Some account contracts might allow change of owner</li> <li><code>foo(bytes bar)</code>: Some account contracts might have custom methods of any format.</li> </ul> <p>The standardization of account contracts is not scope of this ERC, and is presented here only for illustration on possible implementations. Using a self call to evaluate <code>_execBytes</code> is not mandatory, depending on the account contract logic, the evaluation could be done locally.</p> <h3 id="gas-accounting-and-refund">Gas accounting and refund</h3> <p>The implementing contract must keep track of the gas spent. One way to do it is to first call <code>gasLeft()</code> at the beginning of the function and then after executing the desired action and compare the difference.</p> <p>The contract then will make a token transfer (or ether, if <code>tokenAddress</code> is nil) in the value of <code>gasSpent * gasPrice</code> to the <code>_gasRelayer</code>, that is the account that deployed the message.</p> <p>If <code>_gasRelayer</code> is zero, then the funds <strong>MUST</strong> go to <code>block.coinbase</code>.</p> <p>If there are not enough funds, or if the total surpasses <code>gasLimit</code> then the transaction <strong>MUST</strong> revert.</p> <p>If the executed transaction fails internally, nonces should still be updated and gas needs to be paid.</p> <p>Contracts are not obligated to support ether or any other token they don’t want and can be implemented to only accept refunds in a few tokens of their choice.</p> <h3 id="usage-examples">Usage examples</h3> <p>This scheme opens up a great deal of possibilities on interaction as well as different experiments on business models:</p> <ul> <li>Apps can create individual identities contract for their users which holds the actual funds and then create a different private key for each device they log into. Other apps can use the same identity and just ask to add permissioned public keys to manage the device, so that if one individual key is lost, no ether is lost.</li> <li>An app can create its own token and only charge their users in its internal currency for any ethereum transaction. The currency units can be rounded so it looks more similar to actual amount of transactions: a standard transaction always costs 1 token, a very complex transaction costs exactly 2, etc. Since the app is the issuer of the transactions, they can do their own Sybil verifications and give a free amount of currency units to new users to get them started.</li> <li>A game company creates games with a traditional monthly subscription, either by credit card or platform-specific microtransactions. Private keys never leave the device and keep no ether and only the public accounts are sent to the company. The game then signs transactions on the device with gas price 0, sends them to the game company which checks who is an active subscriber and batches all transactions and pays the ether themselves. If the company goes bankrupt, the gamers themselves can set up similar subscription systems or just increase the gas price. End result is a <strong>ethereum based game in which gamers can play by spending apple, google or xbox credits</strong>.</li> <li>A standard token is created that doesn’t require its users to have ether, and instead allows tokens to be transferred by paying in tokens. A wallet is created that signs messages and send them via whisper to the network, where other nodes can compete to download the available transactions, check the current gas price, and select those who are paying enough tokens to cover the cost. <strong>The result is a token that the end users never need to keep any ether and can pay fees in the token itself.</strong></li> <li>A DAO is created with a list of accounts of their employees. Employees never need to own ether, instead they sign messages, send them to whisper to a decentralized list of relayers which then deploy the transactions. The DAO contract then checks if the transaction is valid and sends ether to the deployers. Employees have an incentive not to use too many of the companies resources because they’re identifiable. The result is that the users of the DAO don't need to keep ether, and <strong>the contract ends up paying for it's own gas usage</strong>.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There is no issues with backwards compatibility, however for future upgrades, as <code>_execData</code> contains arbitrary data evaluated by the account contract, it's up to the contract to handle properly this data and therefore contracts can gas relay any behavior with the current interface.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>One initial implementation of such a contract can be found at <a rel="external" href="https://github.com/status-im/account-contracts/blob/develop/contracts/account/AccountGasAbstract.sol">Status.im account-contracts repository</a></p> <p>Other version is implemented as Gnosis Safe variant in: https://github.com/status-im/safe-contracts</p> <h3 id="similar-implementations">Similar implementations</h3> <p>The idea of using signed messages as executable intent has been around for a while and many other projects are taking similar approaches, which makes it a great candidate for a standard that guarantees interoperability:</p> <ul> <li><a rel="external" href="https://github.com/ethereum/EIPs/pull/877">EIP-877</a> An attempt of doing the same but with a change in the protocol</li> <li><a rel="external" href="https://github.com/status-im/ideas/issues/73">Status</a></li> <li><a rel="external" href="https://github.com/aragonlabs/pay-protocol">Aragon</a> (this might not be the best link to show their work in this area)</li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/662">Token Standard Functions for Preauthorized Actions</a></li> <li><a rel="external" href="https://github.com/ethereum/EIPs/issues/865">Token Standard Extension 865</a></li> <li><a rel="external" href="https://github.com/iurimatias/TransactionRelay">Iuri Matias: Transaction Relay</a></li> <li><a rel="external" href="https://github.com/uport-project/uport-identity#send-a-meta-tx">uPort: Meta transactions</a></li> <li><a rel="external" href="https://github.com/uport-project/uport-identity/blob/develop/docs/txRelay.md">uPort: safe Identities</a></li> <li><a rel="external" href="https://github.com/gnosis/safe-contracts">Gnosis safe contracts</a></li> </ul> <p>Swarm city uses a similar proposition for etherless transactions, called <a rel="external" href="https://github.com/swarmcity/SCLabs-gasstation-service">Gas Station Service</a>, but it's a different approach. Instead of using signed messages, a traditional ethereum transaction is signed on an etherless account, the transaction is then sent to a service that immediately sends the exact amount of ether required and then publishes the transaction.</p> <h2 id="security-considerations">Security Considerations</h2> <p>Deployers of transactions (relayers) should be able to call untrusted contracts, which provides no guarantees that the contract they are interacting with correctly implements the standard and they will be reimbursed for gas. To prevent being fooled by bad implementations, relayers must <strong>estimate the outcome of a transaction</strong>, and only include/sign transactions which have a desired outcome.</p> <p>Is also interest of relayers to maintaining a private reputation of contracts they interact with, as well as keep track of which tokens and for which <code>gasPrice</code> they’re willing to deploy transactions.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> <h2 id="references">References</h2> <ul> <li><a rel="external" href="https://www.youtube.com/watch?v=qF2lhJzngto">Universal Logins talk at UX Unconf, Toronto</a></li> </ul> 2018-05-04T00:00:00+00:00 2026-02-11T14:48:25+00:00 Alex Van de Sandeavsa@ethereum.org https://wg-eips.ritovision.com/1078/ <h2 id="abstract">Abstract</h2> <p>This presents a method to replace the usual signup/login design pattern with a minimal ethereum native scheme, that doesn’t require passwords, backing up private keys nor typing seed phrases. From the user's point of view it will be very similar to patterns they’re already used to with second factor authentication (without relying in a central server), but for dapp developers it requires a new way to think about ethereum transactions.</p> <h2 id="simple-summary">Simple Summary</h2> <p>The unique identifier of the user is a contract that implements both Identity and the Executable Signed Messages ERCs. The user should not need to provide this address directly, only a ENS name pointing to it. These types of contracts are indirectly controlled by private keys that can sign messages indicating intents, which are then deployed to the contract by a third party (or a decentralized network of deployers).</p> <p>In this context, therefore, a device "logging into" an app using an identity, means that the device will generate a private key locally and then request an authorization to add that key as one of the signers of that identity, with a given set of permissions. Since that private key is only used for signing messages, it is not required to hold ether, tokens or assets, and if lost, it can be simply be replaced by a new one – the user's funds are kept on the identity contract.</p> <p>In this context, ethereum accounts are used in a manner more similar to auth tokens, rather than unique keys.</p> <p>The login process is as follows:</p> <h4 id="1-request-a-name-from-the-user">1) Request a name from the user</h4> <p>The first step of the process is to request from the user the ENS name that points to their identity. If the user doesn’t have a login set up, the app should–if they have an integrated identity manager–provide an option to provide a subdomain or a name they own.</p> <p><strong>UX Note:</strong> there are many ways to provide this interface, the app can ask if they want to signup/login before hand or simply directly ask them to type the name. Note that since it’s trivial to verify if a username exists, your app should adapt to it gracefully and not require the user to type their name twice. If they ask to signup and provide a name that exists then ask them if they want to login using that name, or similarly if they ask to connect to an existing name but type a non-existent name show them a nice alert and ask them if they want to create that name now. Don’t force them to type the same name twice in two different fields.</p> <h4 id="2-a-create-a-new-identity">2.a) Create a new identity</h4> <p>If the user doesn’t have an identity, the app should provide the option to create one for them. Each app must have one or more domains they control which they can create immediate subdomains on demand. The app therefore will make these actions on the background:</p> <ol> <li>Generate a private key which it will keep saved locally on the device or browser, the safest way possible.</li> <li>Create (or set up) an identity contract which supports both ERC720 and ERC1077</li> <li>Register the private key created on step 1 as the <em>only</em> admin key of the contract (the app must not add any app-controlled key, except as a recovery option - see 5)</li> <li>Register the requested subdomain and transfer its ownership to the contract (while the app controls the main domain and may keep the option to reassign them at will, the ownership of the subdomain itself should belong to the identity, therefore allowing them to transfer it)</li> <li>(Optionally) Register a recovery method on the contract, which allows the user to regain access to the contract in case the main key is lost.</li> </ol> <p>All those steps can be designed to be set up in a single ethereum transaction. Since this step is not free, the app reserves the right to charge for registering users, or require the user to be verified in a sybil resistant manner of the app’s choosing (captcha, device ID registration, proof of work, etc)</p> <p>The user shouldn’t be forced to wait for transaction confirmation times. Instead, have an indicator somewhere on the app that shows the progress and then allow the user to interact with your app normally. It’s unlikely that they’ll need the identity in the first few minutes and if something goes wrong (username gets registered at the same time), you can then ask the user for an action.</p> <p><strong>Implementation note:</strong> in order to save gas, some of these steps can be done in advance. The app can automatically deploy a small number of contracts when the gas price is low, and set up all their main variables to be 0xFFFFFF...FFFFF. These should be considered ‘vacant’ and when the user registers one, they will get a gas discount for freeing up space on the chain. This has the added benefit of allowing the user a choice in contract address/icon.</p> <h4 id="2-b-connect-to-an-existing-identity">2.b) Connect to an existing identity</h4> <p>If the user wants to connect with an existing identity, then the first thing the app needs to understand is what level of privilege it’s going to ask for:</p> <p><strong>Manager</strong> the higher level, allows the key to initiate or sign transactions that change the identity itself, like adding or removing keys. An app should only require this level if it integrates an identity manager. Depending on how the identity is set up, it might require signature from more keys before these transactions can be deployed.</p> <p><strong>Action</strong> this level allows the key to initiate or sign transactions on address other than itself. It can move funds, ether, assets etc. An app should only require this level of privilege if it’s a general purpose wallet or browser for sending ethereum transactions. Depending on how the identity is set up, it might require signature from more keys before these transactions can be deployed.</p> <p><strong>Encryption</strong> the lower level has no right to initiate any transactions, but it can be used to represent the user in specific instances or off-chain signed messages. It’s the ideal level of privilege for games, chat or social media apps, as they can be used to sign moves, send messages, etc. If a game requires actual funds (say, to start a game with funds in stake) then it should still use the encryption level, and then require the main wallet/browser of the user to sign messages using the ethereum URI standard.</p> <p>Once the desired level is known, the app must take these steps:</p> <ol> <li><strong>Generate a private key</strong> which it will keep saved locally on the device or browser, the safest way possible.</li> <li><strong>Query ens</strong> to figure the existing address of the identity</li> <li><strong>Generate the bytecode</strong> for a transaction calling the function <code>addKey(PUBLICKEY,LEVEL)</code>.</li> <li><strong>Broadcast a transaction request on a whisper channel</strong> or some other decentralized network of peers. Details on this step require further discussions</li> <li><strong>If web3 is available</strong> then attempt calling web3.eth.sendTransaction. This can be automatic or prompted by user action.</li> <li><strong>Attempt calling a URI</strong> if the app supports <a href="https://wg-eips.ritovision.com/681/">URL format for transaction requests EIP</a> then attempt calling this. This can be automatic or prompted by user action.</li> <li><strong>Show a QR code</strong>: with an EIP681 formatted URL. That QR code can be clickable to attempt to retry the other options, but it should be done last: if step 1 works, the user should receive a notification on their compatible device and won't need to use the QR code.</li> </ol> <p>Here's an example of a EIP681 compatible address to add a public key generated locally in the app:</p> <p><code>ethereum:bob.example.eth?function=addKey(address='0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',uint=1)</code></p> <p>If adding the new key requires multiple signatures, or if the app receiving that request exclusiveky deals with executable signed messages and has no ether on itself, then it should follow the steps in the next section on how to request transactions.</p> <p>As before, the user shouldn’t be forced to wait for transaction confirmation times. Instead, have an indicator somewhere on the app the shows the progress and then allow the user to interact with your app normally.</p> <h4 id="3-request-transactions">3) Request transactions</h4> <p>After step 2, the end result should be that your app should have the identity address of the user, their main ens name and a private key, whose public account is listed on the identity as one of their keys, with roles being either manager, action or encryption. Now it can start using that information to sign and execute transactions.</p> <p><strong>Not all transactions need to be on chain</strong>, actually most common uses of signed messages should be off chain. If you have a chat app, for instance, you can use the local key for signing messages and sending it to the other parties, and they can just query the identity contract to see if that key actually comes from the user. If you have a game with funds at stake, only the first transaction moving funds and setting up the initial game needs to be executed by the identity: at each turn the players can sign a hash of the current state of the board and at the end, the last two plays can be used to determine the winner. Notice that keys can be revoked at any time, so your app should take that in consideration, for instance saving all keys at the start of the game. Keys that only need this lower level of privilege, should be set at level 4 (encryption).</p> <p>Once you decided you actually need an on-chain transaction, follow these steps:</p> <ol> <li><strong>Figure out the TO, FROM, VALUE and DATA</strong>. These are the basics of any ethereum transaction. <code>from</code> is the compatible contract you want the transaction to be deployed from.</li> <li><strong>Check the privilege level you need:</strong> if the <code>to</code> and <code>from</code> fields are the same contract, ie, if the transaction requires the identity to act upon itself (for instance, when adding or removing a key) then you need level 1 (management), otherwise it's 2 (action). Verify if the key your app owns correspond to the required level.</li> <li><strong>Verify how many keys are required</strong> by calling <code>requiredSignatures(uint level)</code> on the target contract</li> <li><strong>Figure out gasLimit</strong>: Estimate the gas cost of the desired transaction, and add a margin (recommended: add 100k gas)</li> <li><strong>Figure out gasToken and gasPrice</strong>: Check the current gas price considering network congestions and the market price of the token the user is going to pay with. Leave gasToken as 0 for ether. Leave gasPrice as 0 if you are deploying it yourself and subsidizing the costs elsewhere.</li> <li><strong>Sign an executable signed transaction</strong> by following that standard.</li> </ol> <p>After having all the signed executable message, we need to deploy it to the chain. If the transaction only requires a single signature, then the app provider can deploy it themselves. Send the transaction to the <code>from</code> address and attempt to call the function <code>executeSigned</code>, using the parameters and signature you just collected.</p> <p>If the transaction need to collect more signatures or the app doesn't have a deployable server, the app should follow these steps:</p> <ol> <li><strong>Broadcast the transaction on a whisper channel</strong> or some other decentralized network of peers. Details on this step require further discussions</li> <li><strong>If web3 is available</strong> then attempt calling web3.eth.personal_sign. This can be automatic or prompted by user action.</li> <li><strong>Show a QR code</strong>: with the signed transaction and the new data to be signed. That QR code can be clickable to attempt to retry the other options, but it should be done last: if step 1 works, the user should receive a notification on their compatible device and won't need to use the QR code.</li> </ol> <p>The goal is to keep broadcasting signatures via whisper until a node that is willing to deploy them is able to collect all messages.</p> <p>Once you've followed the above steps, watch the transaction pool to any transaction to that address and then take the user to your app. Once you seen the desired transaction, you can stop showing the QR code and proceed with the app, while keeping some indication that the transaction is in progress. Subscribe to the event <code>ExecutedSigned</code> of the desired contract: once you see the transaction with the nonce, you can call it a success. If you see a different transaction with the same or higher nonce (or timestamp) then you consider the transaction permanently failed and restart the process.</p> <h3 id="implementation">Implementation</h3> <p>No working examples of this implementation exists, but many developers have expressed interest in adopting it. This section will be edited in the future to reflect that.</p> <h3 id="conclusion-and-future-improvements">Conclusion and future improvements</h3> <p>This scheme would allow much more lighter apps, that don’t require holding ether, and can keep unlocked private keys on the device to be able to send messages and play games without requesting user prompt every time. More work is needed to standardize common decentralized messaging protocols as well as open source tools for deployment nodes, in order to create a decentralized and reliable layer for message deployment.</p> <h3 id="references">References</h3> <ul> <li><a rel="external" href="https://www.youtube.com/watch?v=qF2lhJzngto">Universal Logins talk at UX Unconf, Toronto</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-04T00:00:00+00:00 2026-02-11T14:49:28+00:00 Paul Bouchonmail@bitpshr.net Erik Markshttps://github.com/rekmarks https://wg-eips.ritovision.com/1102/ <h2 id="simple-summary">Simple summary</h2> <p>This proposal describes a communication protocol between dapps and Ethereum-enabled DOM environments that allows the Ethereum-enabled DOM environment to choose what information to supply the dapp with and when.</p> <h2 id="abstract">Abstract</h2> <p>The previous generation of Ethereum-enabled DOM environments follows a pattern of injecting a provider populated with accounts without user consent. This puts users of such environments at risk because malicious websites can use these accounts to view detailed account information and to arbitrarily initiate unwanted transactions on a user's behalf.</p> <p>This proposal outlines a protocol in which Ethereum-enabled DOM environments can choose to expose no accounts until the user approves account access.</p> <h2 id="specification">Specification</h2> <h3 id="concepts">Concepts</h3> <h4 id="rfc-2119">RFC-2119</h4> <p>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 <a rel="external" href="https://www.ietf.org/rfc/rfc2119.txt">RFC-2119</a>.</p> <h4 id="eth-requestaccounts"><code>eth_requestAccounts</code></h4> <p>Providers exposed by Ethereum-enabled DOM environments define a new RPC method: <code>eth_requestAccounts</code>. Calling this method may trigger a user interface that allows the user to approve or reject account access for a given dapp. This method returns a <code>Promise</code> that is resolved with an <code>Array</code> of accounts or is rejected with an <code>Error</code> if accounts are not available.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-variable z-other">ethereum</span><span>.</span><span class="z-entity z-name">send</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">eth_requestAccounts</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>: </span><span class="z-support">Promise</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">Array</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">string</span><span class="z-keyword">&gt;&gt;</span></span></code></pre><h4 id="provider-enable-deprecated">Provider#enable (DEPRECATED)</h4> <p><strong>Note: This method is deprecated in favor of the RPC method <a href="https://wg-eips.ritovision.com/1102/#eth-requestaccounts"><code>eth_requestAccounts</code></a>.</strong></p> <p>Providers exposed by Ethereum-enabled DOM environments define a new RPC method: <code>ethereum.enable()</code>. Calling this method triggers a user interface that allows the user to approve or reject account access for a given dapp. This method returns a <code>Promise</code> that is resolved with an <code>Array</code> of accounts if the user approves access or rejected with an <code>Error</code> if the user rejects access.</p> <pre class="giallo z-code"><code data-lang="typescript"><span class="giallo-l"><span class="z-variable z-other">ethereum</span><span>.</span><span class="z-entity z-name">enable</span><span>(</span><span>)</span><span>: </span><span class="z-support">Promise</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">any</span><span class="z-keyword">&gt;</span></span></code></pre><h3 id="protocol">Protocol</h3> <h4 id="legacy-dapp-initialization">Legacy dapp initialization</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>START dapp</span></span> <span class="giallo-l"><span>IF web3 is defined</span></span> <span class="giallo-l"><span> CONTINUE dapp</span></span> <span class="giallo-l"><span>IF web3 is undefined</span></span> <span class="giallo-l"><span> STOP dapp</span></span></code></pre><h4 id="proposed-dapp-initialization">Proposed dapp initialization</h4> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>START dapp</span></span> <span class="giallo-l"><span>IF provider is defined</span></span> <span class="giallo-l"><span> REQUEST[1] account access</span></span> <span class="giallo-l"><span> IF user approves</span></span> <span class="giallo-l"><span> RESOLVE[2] account access</span></span> <span class="giallo-l"><span> CONTINUE dapp</span></span> <span class="giallo-l"><span> IF user rejects</span></span> <span class="giallo-l"><span> REJECT[3] account access</span></span> <span class="giallo-l"><span> STOP dapp</span></span> <span class="giallo-l"><span>IF provider is undefined</span></span> <span class="giallo-l"><span> STOP dapp</span></span></code></pre><h5 id="1-request"><code>[1] REQUEST</code></h5> <p>Dapps <strong>MUST</strong> request accounts by calling the <code>eth_requestAccounts</code> RPC method on the provider exposed at <code>window.ethereum</code>. Calling this method <strong>MAY</strong> trigger a user interface that allows the user to approve or reject account access for a given dapp. This method <strong>MUST</strong> return a <code>Promise</code> that is resolved with an array of one or more user accounts or rejected if no accounts are available (e.g., the user rejected account access).</p> <h5 id="2-resolve"><code>[2] RESOLVE</code></h5> <p>The <code>Promise</code> returned when calling the <code>eth_requestAccounts</code> RPC method <strong>MUST</strong> be resolved with an <code>Array</code> of user accounts.</p> <h5 id="3-reject"><code>[3] REJECT</code></h5> <p>The <code>Promise</code> returned when calling the <code>eth_requestAccounts</code> RPC method <strong>MUST</strong> be rejected with an informative <code>Error</code> if no accounts are available for any reason.</p> <h3 id="example-initialization">Example initialization</h3> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-keyword">try</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Request account access if needed</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> accounts</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> ethereum</span><span>.</span><span class="z-entity z-name">send</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">eth_requestAccounts</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Accounts now exposed, use them</span></span> <span class="giallo-l"><span class="z-variable z-other"> ethereum</span><span>.</span><span class="z-entity z-name">send</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">eth_sendTransaction</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span> {</span><span> from</span><span>:</span><span class="z-variable z-other"> accounts</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-punctuation z-definition z-comment"> /*</span><span class="z-comment"> ... </span><span class="z-punctuation z-definition z-comment">*/</span><span> }</span><span>)</span></span> <span class="giallo-l"><span>}</span><span class="z-keyword"> catch</span><span> (</span><span class="z-variable z-other">error</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> User denied account access</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="constraints">Constraints</h3> <ul> <li>Browsers <strong>MUST</strong> expose a provider at <code>window.ethereum</code> .</li> <li>Browsers <strong>MUST</strong> define an <code>eth_requestAccounts</code> RPC method.</li> <li>Browsers <strong>MAY</strong> wait for a user interaction before resolving/rejecting the <code>eth_requestAccounts</code> promise.</li> <li>Browsers <strong>MUST</strong> include at least one account if the <code>eth_requestAccounts</code> promise is resolved.</li> <li>Browsers <strong>MUST</strong> reject the promise with an informative error if no accounts are available.</li> </ul> <h2 id="rationale">Rationale</h2> <p>The pattern of automatic account exposure followed by the previous generation of Ethereum-enabled DOM environments fails to protect user privacy and fails to maintain safe user experience: untrusted websites can both view detailed account information and arbitrarily initiate transactions on a user's behalf. Even though most users may reject unsolicited transactions on untrusted websites, a protocol for account access should make such unsolicited requests impossible.</p> <p>This proposal establishes a new pattern wherein dapps must request access to user accounts. This protocol directly strengthens user privacy by allowing the browser to hide user accounts and preventing unsolicited transaction requests on untrusted sites.</p> <h3 id="immediate-value-add">Immediate value-add</h3> <ul> <li>Users can reject account access on untrusted sites to hide accounts.</li> <li>Users can reject account access on untrusted sites to prevent unsolicited transactions.</li> </ul> <h3 id="long-term-value-add">Long-term value-add</h3> <ul> <li>Dapps could request specific account information based on user consent.</li> <li>Dapps could request specific user information based on user consent (uPort, DIDs).</li> <li>Dapps could request a specific network based on user consent.</li> <li>Dapps could request multiple instances of the above based on user consent.</li> </ul> <h2 id="backwards-compatibility">Backwards compatibility</h2> <p>This proposal impacts dapp developers and requires that they request access to user accounts following the protocol outlined above. Similarly, this proposal impacts dapp browser developers and requires that they only expose user accounts following the protocol defined above.</p> <h2 id="implementation">Implementation</h2> <p>The MetaMask team <a rel="external" href="https://github.com/MetaMask/metamask-extension/pull/4703">has implemented</a> the strategy described above.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-03T00:00:00+00:00 2026-02-11T14:48:25+00:00 Pelle Braendgaardpelle.braendgaard@consensys.net Joel Torstenssonoed@consensys.net https://wg-eips.ritovision.com/1056/ <h2 id="simple-summary">Simple Summary</h2> <p>A registry for key and attribute management of lightweight blockchain identities.</p> <h2 id="abstract">Abstract</h2> <p>This ERC describes a standard for creating and updating identities with a limited use of blockchain resources. An identity can have an unlimited number of <code>delegates</code> and <code>attributes</code> associated with it. Identity creation is as simple as creating a regular key pair ethereum account, which means that it's free (no gas costs) and all ethereum accounts are valid identities. Furthermore this ERC is fully <a rel="external" href="https://w3c-ccg.github.io/did-spec/">DID compliant</a>.</p> <h2 id="motivation">Motivation</h2> <p>As we have been developing identity systems for the last couple of years at uPort it has become apparent that the cost of identity creation is a large issue. The previous Identity proposal <a href="https://wg-eips.ritovision.com/725/">ERC-725</a> faces this exact issue. Our requirements when creating this ERC is that identity creation should be free, and should be possible to do in an offline environment (e.g. refugee scenario). However it must also be possible to rotate keys without changing the primary identifier of the identity. The identity system should be fit to use off-chain as well as on-chain.</p> <h2 id="definitions">Definitions</h2> <ul> <li> <p><code>Identifier</code>: a piece of data that uniquely identifies the identity, an ethereum address</p> </li> <li> <p><code>delegate</code>: an address that is delegated for a specific time to perform some sort of function on behalf of an identity</p> </li> <li> <p><code>delegateType</code>: the type of a delegate, is determined by a protocol or application higher up Examples:</p> <ul> <li><code>did-jwt</code></li> <li><code>raiden</code></li> </ul> </li> <li> <p><code>attribute</code>: a piece of data associated with the identity</p> </li> </ul> <h2 id="specification">Specification</h2> <p>This ERC specifies a contract called <code>EthereumDIDRegistry</code> that is deployed once and can then be commonly used by everyone.</p> <h3 id="identity-ownership">Identity ownership</h3> <p>By default an identity is owned by itself, meaning whoever controls the ethereum account with that address. The owner can be updated to a new key pair account or to a multisig account etc.</p> <h4 id="identityowner">identityOwner</h4> <p>Returns the owner of the given identity.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> identityOwner</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-variable">address</span><span>)</span><span>;</span></span></code></pre><h4 id="changeowner">changeOwner</h4> <p>Sets the owner of the given identity to another ethereum account.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeOwner</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> newOwner</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="changeownersigned">changeOwnerSigned</h4> <p>Same as above but with raw signature.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> changeOwnerSigned</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> uint8</span><span class="z-variable"> sigV</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigR</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigS</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> newOwner</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h3 id="delegate-management">Delegate management</h3> <p>Delegates can be used both on- and off-chain. They all have a <code>delegateType</code> which can be used to specify the purpose of the delegate.</p> <h4 id="validdelegate">validDelegate</h4> <p>Returns true if the given <code>delegate</code> is a delegate with type <code>delegateType</code> of <code>identity</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> validDelegate</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> delegateType</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> delegate</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span>(</span><span class="z-variable">bool</span><span>)</span><span>;</span></span></code></pre><h4 id="adddelegate">addDelegate</h4> <p>Adds a new delegate with the given type. <code>validity</code> indicates the number of seconds that the delegate will be valid for, after which it will no longer be a delegate of <code>identity</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addDelegate</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> delegateType</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> delegate</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> validity</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="adddelegatesigned">addDelegateSigned</h4> <p>Same as above but with raw signature.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> addDelegateSigned</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> uint8</span><span class="z-variable"> sigV</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigR</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigS</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> delegateType</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> delegate</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> validity</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="revokedelegate">revokeDelegate</h4> <p>Revokes the given <code>delegate</code> for the given <code>identity</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revokeDelegate</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> delegateType</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> delegate</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="revokedelegatesigned">revokeDelegateSigned</h4> <p>Same as above but with raw signature.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revokeDelegateSigned</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> uint8</span><span class="z-variable"> sigV</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigR</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigS</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> delegateType</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> delegate</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h3 id="attribute-management">Attribute management</h3> <p>Attributes contain simple data about the identity. They can be managed only by the owner of the identity.</p> <h4 id="setattribute">setAttribute</h4> <p>Sets an attribute with the given <code>name</code> and <code>value</code>, valid for <code>validity</code> seconds.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setAttribute</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> name</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> value</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> validity</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="setattributesigned">setAttributeSigned</h4> <p>Same as above but with raw signature.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setAttributeSigned</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> uint8</span><span class="z-variable"> sigV</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigR</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigS</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> name</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> value</span><span>,</span><span class="z-variable"> uint</span><span class="z-variable"> validity</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="revokeattribute">revokeAttribute</h4> <p>Revokes an attribute.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revokeAttribute</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> name</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> value</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h4 id="revokeattributesigned">revokeAttributeSigned</h4> <p>Same as above but with raw signature.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revokeAttributeSigned</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> identity</span><span>,</span><span class="z-variable"> uint8</span><span class="z-variable"> sigV</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigR</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> sigS</span><span>,</span><span class="z-variable"> bytes32</span><span class="z-variable"> name</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> value</span><span>)</span><span class="z-entity z-name"> public</span><span>;</span></span></code></pre><h3 id="events">Events</h3> <h4 id="didownerchanged">DIDOwnerChanged</h4> <p>MUST be triggered when <code>changeOwner</code> or <code>changeOwnerSigned</code> was successfully called.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> DIDOwnerChanged</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> identity</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> owner</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> previousChange</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="diddelegatechanged">DIDDelegateChanged</h4> <p>MUST be triggered when a change to a delegate was successfully made.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> DIDDelegateChanged</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> identity</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> bytes32</span><span class="z-variable z-other"> delegateType</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> delegate</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> validTo</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> previousChange</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h4 id="didattributechanged">DIDAttributeChanged</h4> <p>MUST be triggered when a change to an attribute was successfully made.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> DIDAttributeChanged</span><span>(</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> identity</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> bytes32</span><span class="z-variable z-other"> name</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> bytes</span><span class="z-variable z-other"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> validTo</span><span>,</span></span> <span class="giallo-l"><span class="z-variable z-other"> uint</span><span class="z-variable z-other"> previousChange</span></span> <span class="giallo-l"><span>)</span><span>;</span></span></code></pre><h3 id="efficient-lookup-of-events-through-linked-identity-events">Efficient lookup of events through linked identity events</h3> <p>Contract Events are a useful feature for storing data from smart contracts exclusively for off-chain use. Unfortunately current ethereum implementations provide a very inefficient lookup mechanism. By using linked events that always link to the previous block with a change for the identity, we can solve this problem with much improved performance. Each identity has its previously changed block stored in the <code>changed</code> mapping.</p> <ol> <li> <p>Lookup <code>previousChange</code> block for identity</p> </li> <li> <p>Lookup all events for given identity address using web3, but only for the <code>previousChange</code> block</p> </li> <li> <p>Do something with the event</p> </li> <li> <p>Find <code>previousChange</code> from the event and repeat</p> </li> </ol> <p>Example code:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">const</span><span class="z-variable z-other z-constant"> history</span><span class="z-keyword"> =</span><span> [</span><span>]</span></span> <span class="giallo-l"><span class="z-variable z-other">previousChange</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> didReg</span><span>.</span><span class="z-entity z-name">changed</span><span>(</span><span class="z-variable z-other">identity</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">while</span><span> (</span><span class="z-variable z-other">previousChange</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> filter</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-variable z-other"> didReg</span><span>.</span><span class="z-entity z-name">allEvents</span><span>(</span><span>{</span><span>topics</span><span>:</span><span> [</span><span class="z-variable z-other">identity</span><span>]</span><span>,</span><span> fromBlock</span><span>:</span><span class="z-variable z-other"> previousChange</span><span>,</span><span> toBlock</span><span>:</span><span class="z-variable z-other"> previousChange</span><span>}</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> const</span><span class="z-variable z-other z-constant"> events</span><span class="z-keyword"> =</span><span class="z-keyword"> await</span><span class="z-entity z-name"> getLogs</span><span>(</span><span class="z-variable z-other">filter</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> previousChange</span><span class="z-keyword"> =</span><span class="z-constant"> undefined</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">let</span><span class="z-variable z-other"> event</span><span class="z-keyword"> of</span><span class="z-variable z-other"> events</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> history</span><span>.</span><span class="z-entity z-name">unshift</span><span>(</span><span class="z-variable z-other">event</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> previousChange</span><span class="z-keyword"> =</span><span class="z-variable z-other"> event</span><span>.</span><span class="z-variable z-other">args</span><span>.</span><span class="z-variable z-other">previousChange</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span><span> </span></span></code></pre><h3 id="building-a-did-document-for-an-identity">Building a DID document for an identity</h3> <p>The primary owner key should be looked up using <code>identityOwner(identity)</code>. This should be the first of the publicKeys listed. Iterate through the <code>DIDDelegateChanged</code> events to build a list of additional keys and authentication sections as needed. The list of delegateTypes to include is still to be determined. Iterate through <code>DIDAttributeChanged</code> events for service entries, encryption public keys and other public names. The attribute names are still to be determined.</p> <h2 id="rationale">Rationale</h2> <p>For on-chain interactions Ethereum has a built in account abstraction that can be used regardless of whether the account is a smart contract or a key pair. Any transaction has a <code>msg.sender</code> as the verified send of the transaction.</p> <p>Since each Ethereum transaction has to be funded, there is a growing trend of on-chain transactions that are authenticated via an externally created signature and not by the actual transaction originator. This allows 3rd party funding services or receiver pays without any fundamental changes to the underlying Ethereum architecture. These kinds of transactions have to be signed by an actual key pair and thus can not be used to represent smart contract based Ethereum accounts.</p> <p>We propose a way of a Smart Contract or regular key pair delegating signing for various purposes to externally managed key pairs. This allows a smart contract to be represented both on-chain as well as off-chain or in payment channels through temporary or permanent delegates.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>All ethereum accounts are valid identities (and DID compatible) using this standard. This means that any wallet provider that uses key pair accounts already supports the bare minimum of this standard, and can implement <code>delegate</code> and <code>attribute</code> functionality by simply using the <code>ethr-did</code> referenced below. As the <strong>DID Auth</strong> standard solidifies it also means that all of these wallets will be compatible with the <a rel="external" href="https://github.com/decentralized-identity">DID decentralized login system</a>.</p> <h2 id="implementation">Implementation</h2> <p><a rel="external" href="https://github.com/uport-project/ethr-did-registry/blob/develop/contracts/EthereumDIDRegistry.sol">ethr-did-registry</a> (<code>EthereumDIDRegistry</code> contract implementation)</p> <p><a rel="external" href="https://github.com/uport-project/ethr-did-resolver">ethr-did-resolver</a> (DID compatible resolver)</p> <p><a rel="external" href="https://github.com/uport-project/ethr-did">ethr-did</a> (javascript library for using the identity)</p> <h3 id="deployment">Deployment</h3> <p>The address for the <code>EthereumDIDRegistry</code> is <code>0xdca7ef03e98e0dc2b855be647c39abe984fcf21b</code> on Mainnet, Ropsten, Rinkeby and Kovan.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 Nick Johnsonarachnid@notdot.net https://wg-eips.ritovision.com/1051/ <h2 id="abstract">Abstract</h2> <p>This EIP adds overflow checking for EVM arithmetic operations, and two new opcodes that check and clear the overflow flags.</p> <h2 id="motivation">Motivation</h2> <p>The correct functioning of many contracts today is dependent on detecting and preventing overflow of arithmetic operations. Since the EVM operates on mod 2^256 integers and provides no built-in overflow detection or prevention, this requires manual checks on every arithmetic operation.</p> <p>In the interests of facilitating efficient and secure contracts, we propose new opcodes that permit efficient detection of overflows, which can be checked periodically rather than after each operation.</p> <h2 id="specification">Specification</h2> <p>Two new flags are added to the EVM state: overflow (<code>ovf</code>) and signed overflow (<code>sovf</code>).</p> <p>The <code>ovf</code> flag is set in the following circumstances:</p> <ul> <li>When an <code>ADD</code> (<code>0x01</code>) opcode, with both inputs treated as unsigned integers, produces an ideal output in excess of 2^256 - 1.</li> <li>When a <code>SUB</code> (<code>0x03</code>) opcode, with both inputs treated as unsigned integers, produces an ideal output less than 0.</li> <li>When a <code>MUL</code> (<code>0x02</code>) opcode, with both inputs treated as unsigned integers, produces an ideal output in excess of 2^256 - 1.</li> </ul> <p>The <code>sovf</code> flag is set whenever the <code>ovf</code> flag is set, and additionally in the following circumstances:</p> <ul> <li>When an <code>ADD</code> opcode with both inputs having the same MSB results in the output having a different MSB (eg, <code>(+a) + (+b) = (-c)</code> or <code>(-a) + (-b) = (+c)</code>).</li> <li>When a <code>SUB</code> opcode occurs and the result has the same MSB as the subtracted (second argument) (eg, <code>(+a) - (-b) = (-c)</code> or <code>(-a) - (+b) = (+c)</code>).</li> <li>When a <code>MUL</code> opcode with both inputs being positive has a negative output.</li> <li>When a <code>MUL</code> opcode with both inputs being negative has a negative output.</li> <li>When a <code>MUL</code> opcode with one negative input and one positive input has a positive output.</li> </ul> <p>A new opcode, <code>OFV</code> is added, with number <code>0x0c</code>. This opcode takes 0 arguments from the stack. When executed, it pushes <code>1</code> if the <code>ovf</code> flag is set, and <code>0</code> otherwise. It then sets the <code>ovf</code> flag to false.</p> <p>A new opcode, <code>SOVF</code> is added, with number <code>0x0d</code>. This opcode takes 0 arguments from the stack. When executed, it pushes <code>1</code> if the <code>sovf</code> flag is set, and <code>0</code> otherwise. It then sets the <code>sovf</code> flag to false.</p> <h2 id="rationale">Rationale</h2> <p>Any change to implement overflow protection needs to preserve behaviour of existing contracts, which precludes many changes to the arithmetic operations themselves. One option would be to provide an opcode that enables overflow protection, causing a throw or revert if an overflow happens. However, this limits the manner in which overflows can be handled.</p> <p>Instead, we replicate functionality from real world CPUs, which typically implement 'carry' and 'overflow' flags.</p> <p>Separate flags for signed and unsigned overflow are necessary due to the fact that a signed overflow may not result in an unsigned overflow.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP introduces no backwards compatibility issues.</p> <h2 id="test-cases">Test Cases</h2> <p>TBD</p> <h2 id="implementation">Implementation</h2> <p>TBD</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-02T00:00:00+00:00 2026-02-11T14:49:28+00:00 Greg Colvingreg@colvin.org Andrea Lanfranchihttps://github.com/AndreaLanfranchi Michael Carterhttps://github.com/bitsbetrippin IfDefElseifdefelse@protonmail.com https://wg-eips.ritovision.com/1057/ <h2 id="simple-summary">Simple Summary</h2> <p>A new Proof-of-Work algorithm to replace Ethash that utilizes almost all parts of commodity GPUs.</p> <h2 id="abstract">Abstract</h2> <p>ProgPoW is a proof-of-work algorithm designed to close the efficiency gap available to specialized ASICs. It utilizes almost all parts of commodity hardware (GPUs), and comes pre-tuned for the most common hardware utilized in the Ethereum network.</p> <p>This document presents an overview of the algorithm and examines what it means to be “ASIC-resistant.” Next, we compare existing PoW designs by analyzing how each algorithm executes in hardware. Finally, we present the detailed implementation by walking through the code.</p> <h2 id="motivation">Motivation</h2> <p>Ever since the first bitcoin mining ASIC was released, many new Proof of Work algorithms have been created with the intention of being “ASIC-resistant”. The goal of “ASIC-resistance” is to resist the centralization of PoW mining power such that these coins couldn’t be so easily manipulated by a few players.</p> <p>Ethereum's approach is to incentivize a geographically-distributed community of miners with a low barrier to entry on commodity hardware. As stated in the <a rel="external" href="https://ethereum.github.io/yellowpaper/paper.pdf">Yellow Paper</a>:</p> <blockquote> <p>11.5. Mining Proof-of-Work. The mining proof-ofwork (PoW) exists as a cryptographically secure nonce that proves beyond reasonable doubt that a particular amount of computation has been expended in the determination of some token value n. It is utilised to enforce the blockchain security by giving meaning and credence to the notion of difficulty (and, by extension, total difficulty). However, since mining new blocks comes with an attached reward, the proof-of-work not only functions as a method of securing confidence that the blockchain will remain canonical into the future, but also as a wealth distribution mechanism.</p> </blockquote> <blockquote> <p>For both reasons, there are two important goals of the proof-of-work function; firstly, it should be as accessible as possible to as many people as possible. The requirement of, or reward from, specialised and uncommon hardware should be minimised. This makes the distribution model as open as possible, and, ideally, makes the act of mining a simple swap from electricity to Ether at roughly the same rate for anyone around the world.</p> </blockquote> <blockquote> <p>Secondly, it should not be possible to make super-linear profits, and especially not so with a high initial barrier. Such a mechanism allows a well-funded adversary to gain a troublesome amount of the network’s total mining power and as such gives them a super-linear reward (thus skewing distribution in their favour) as well as reducing the network security...</p> </blockquote> <blockquote> <p>... While ASICs exist for a proof-of-work function, both goals are placed in jeopardy. Because of this, a proof-of-work function that is ASIC-resistant (i.e. difficult or economically inefficient to implement in specialised compute hardware) has been identified as the proverbial silver bullet.</p> </blockquote> <p>It is from these premises that Ethash was designed as an ASIC-resistant proof-of-work:</p> <blockquote> <p>Two directions exist for ASIC resistance; firstly make it sequential memory-hard, i.e. engineer the function such that the determination of the nonce requires a lot of memory and bandwidth such that the memory cannot be used in parallel to discover multiple nonces simultaneously. The second is to make the type of computation it would need to do general-purpose; the meaning of “specialised hardware” for a general-purpose task set is, naturally, general purpose hardware and as such commodity desktop computers are likely to be pretty close to “specialised hardware” for the task. For Ethereum 1.0 we have chosen the first path.</p> </blockquote> <p>5 years of experience with the Ethereum blockchain have demonstrated the success of our approach. This success cannot be taken for granted.</p> <ul> <li>11 years of experience with PoW Blockchains have shown a centralization in hardware development, resulting in a <a rel="external" href="https://www.asicminervalue.com/">few companies</a> controlling the lifecycle of new hardware with limited distribution.</li> <li>New ASICs for Ethash are providing higher efficiency than GPUs, such as the <a rel="external" href="https://shop.bitmain.com/product/detail?pid=00020181031134626816gh0zYNKC06A3">Antminer E3</a>.</li> <li>As much as 40% of the Ethereum network may now be secured by ASICs.</li> </ul> <p>ProgPow restores Ethash' ASIC-resistance by extending Ethash with a GPU-specific approach to the second path — making the “specialised hardware” for the PoW task commodity hardware.</p> <h3 id="progpow-overview">ProgPoW Overview</h3> <p>The design goal of ProgPoW is to have the algorithm’s requirements match what is available on commodity GPUs: If the algorithm were to be implemented on a custom ASIC there should be little opportunity for efficiency gains compared to a commodity GPU.</p> <p>The main elements of the algorithm are:</p> <ul> <li>Changes keccak_f1600 (with 64-bit words) to keccak_f800 (with 32-bit words) to reduce impact on total power</li> <li>Increases mix state.</li> <li>Adds a random sequence of math in the main loop.</li> <li>Adds reads from a small, low-latency cache that supports random addresses.</li> <li>Increases the DRAM read from 128 bytes to 256 bytes.</li> </ul> <p>The random sequence changes every <code>PROGPOW_PERIOD</code> (about 2 to 12 minutes depending on the configured value). When mining source code is generated for the random sequence and compiled on the host CPU. The GPU will execute the compiled code where what math to perform and what mix state to use are already resolved.</p> <p>While a custom ASIC to implement this algorithm is still possible, the efficiency gains available are minimal. The majority of a commodity GPU is required to support the above elements. The only optimizations available are:</p> <ul> <li>Remove the graphics pipeline (displays, geometry engines, texturing, etc)</li> <li>Remove floating point math</li> <li>A few ISA tweaks, like instructions that exactly match the merge() function</li> </ul> <p>These would result in minimal, roughly 1.1-1.2x, efficiency gains. This is much less than the 2x for Ethash or 50x for Cryptonight.</p> <h3 id="rationale-for-pow-on-commodity-hardware">Rationale for PoW on Commodity Hardware</h3> <p>With the growth of large mining pools, the control of hashing power has been delegated to the top few pools to provide a steadier economic return for small miners. While some have made the argument that large centralized pools defeats the purpose of “ASIC resistance,” it’s important to note that ASIC based coins are even more centralized for several reasons.</p> <ol> <li>No natural distribution: There isn’t an economic purpose for ultra-specialized hardware outside of mining and thus no reason for most people to have it.</li> <li>No reserve group: Thus, there’s no reserve pool of hardware or reserve pool of interested parties to jump in when coin price is volatile and attractive for manipulation.</li> <li>High barrier to entry: Initial miners are those rich enough to invest capital and ecological resources on the unknown experiment a new coin may be. Thus, initial coin distribution through mining will be very limited causing centralized economic bias.</li> <li>Delegated centralization vs implementation centralization: While pool centralization is delegated, hardware monoculture is not: only the limited buyers of this hardware can participate so there isn’t even the possibility of divesting control on short notice.</li> <li>No obvious decentralization of control even with decentralized mining: Once large custom ASIC makers get into the game, designing back-doored hardware is trivial. ASIC makers have no incentive to be transparent or fair in market participation.</li> </ol> <p>While the goal of “ASIC resistance” is valuable, the entire concept of “ASIC resistance” is a bit of a fallacy. CPUs and GPUs are themselves ASICs. Any algorithm that can run on a commodity ASIC (a CPU or GPU) by definition can have a customized ASIC created for it with slightly less functionality. Some algorithms are intentionally made to be “ASIC friendly” - where an ASIC implementation is drastically more efficient than the same algorithm running on general purpose hardware. The protection that this offers when the coin is unknown also makes it an attractive target for a dedicated mining ASIC company as soon as it becomes useful.</p> <p>Therefore, ASIC resistance is: the efficiency difference of specialized hardware versus hardware that has a wider adoption and applicability. A smaller efficiency difference between custom vs general hardware mean higher resistance and a better algorithm. This efficiency difference is the proper metric to use when comparing the quality of PoW algorithms. Efficiency could mean absolute performance, performance per watt, or performance per dollar - they are all highly correlated. If a single entity creates and controls an ASIC that is drastically more efficient, they can gain 51% of the network hashrate and possibly stage an attack.</p> <h3 id="review-of-existing-pow-algorithms">Review of Existing PoW Algorithms</h3> <h4 id="sha256">SHA256</h4> <ul> <li>Potential ASIC efficiency gain ~ 1000X</li> </ul> <p>The SHA algorithm is a sequence of simple math operations - additions, logical ops, and rotates.</p> <p>To process a single op on a CPU or GPU requires fetching and decoding an instruction, reading data from a register file, executing the instruction, and then writing the result back to a register file. This takes significant time and power.</p> <p>A single op implemented in an ASIC takes a handful of transistors and wires. This means every individual op takes negligible power, area, or time. A hashing core is built by laying out the sequence of required ops.</p> <p>The hashing core can execute the required sequence of ops in much less time, and using less power or area, than doing the same sequence on a CPU or GPU. A bitcoin ASIC consists of a number of identical hashing cores and some minimal off-chip communication.</p> <h4 id="scrypt-and-neoscrypt">Scrypt and NeoScrypt</h4> <ul> <li>Potential ASIC efficiency gain ~ 1000X</li> </ul> <p>Scrypt and NeoScrypt are similar to SHA in the arithmetic and bitwise operations used. Unfortunately, popular coins such as Litecoin only use a scratchpad size between 32kb and 128kb for their PoW mining algorithm. This scratch pad is small enough to trivially fit on an ASIC next to the math core. The implementation of the math core would be very similar to SHA, with similar efficiency gains.</p> <h4 id="x11-and-x16r">X11 and X16R</h4> <ul> <li>Potential ASIC efficiency gain ~ 1000X</li> </ul> <p>X11 (and similar X##) require an ASIC that has 11 unique hashing cores pipelined in a fixed sequence. Each individual hashing core would have similar efficiency to an individual SHA core, so the overall design will have the same efficiency gains.</p> <p>X16R requires the multiple hashing cores to interact through a simple sequencing state machine. Each individual core will have similar efficiency gains and the sequencing logic will take minimal power, area, or time.</p> <p>The Baikal BK-X is an existing ASIC with multiple hashing cores and a programmable sequencer. It has been upgraded to enable new algorithms that sequence the hashes in different orders.</p> <h4 id="equihash">Equihash</h4> <ul> <li>Potential ASIC efficiency gain ~ 100X</li> </ul> <p>The ~150mb of state is large but possible on an ASIC. The binning, sorting, and comparing of bit strings could be implemented on an ASIC at extremely high speed.</p> <h4 id="cuckoo-cycle">Cuckoo Cycle</h4> <ul> <li>Potential ASIC efficiency gain ~ 100X</li> </ul> <p>The amount of state required on-chip is not clear as there are Time/Memory Tradeoff attacks. A specialized graph traversal core would have similar efficiency gains to a SHA compute core.</p> <h4 id="cryptonight">CryptoNight</h4> <ul> <li>Potential ASIC efficiency gain ~ 50X</li> </ul> <p>Compared to Scrypt, CryptoNight does much less compute and requires a full 2mb of scratch pad (there is no known Time/Memory Tradeoff attack). The large scratch pad will dominate the ASIC implementation and limit the number of hashing cores, limiting the absolute performance of the ASIC. An ASIC will consist almost entirely of just on-die SRAM.</p> <h4 id="ethash">Ethash</h4> <ul> <li>Potential ASIC efficiency gain ~ 2X</li> </ul> <p>Ethash requires external memory due to the large size of the DAG. However that is all that it requires - there is minimal compute that is done on the result loaded from memory. As a result a custom ASIC could remove most of the complexity, and power, of a GPU and be just a memory interface connected to a small compute engine.</p> <h2 id="specification">Specification</h2> <p>ProgPoW can be tuned using the following parameters. The proposed settings have been tuned for a range of existing, commodity GPUs:</p> <ul> <li><code>PROGPOW_PERIOD</code>: Number of blocks before changing the random program</li> <li><code>PROGPOW_LANES</code>: The number of parallel lanes that coordinate to calculate a single hash instance</li> <li><code>PROGPOW_REGS</code>: The register file usage size</li> <li><code>PROGPOW_DAG_LOADS</code>: Number of uint32 loads from the DAG per lane</li> <li><code>PROGPOW_CACHE_BYTES</code>: The size of the cache</li> <li><code>PROGPOW_CNT_DAG</code>: The number of DAG accesses, defined as the outer loop of the algorithm (64 is the same as Ethash)</li> <li><code>PROGPOW_CNT_CACHE</code>: The number of cache accesses per loop</li> <li><code>PROGPOW_CNT_MATH</code>: The number of math operations per loop</li> </ul> <p>The values of these parameters have been tweaked between the original version and the version proposed here for Ethereum adoption. See <a rel="external" href="https://medium.com/@ifdefelse/progpow-progress-da5bb31a651b">this medium post</a> for details.</p> <table><thead><tr><th>Parameter</th><th>0.9.2</th><th>0.9.3</th></tr></thead><tbody> <tr><td><code>PROGPOW_PERIOD</code></td><td><code>50</code></td><td><code>10</code></td></tr> <tr><td><code>PROGPOW_LANES</code></td><td><code>16</code></td><td><code>16</code></td></tr> <tr><td><code>PROGPOW_REGS</code></td><td><code>32</code></td><td><code>32</code></td></tr> <tr><td><code>PROGPOW_DAG_LOADS</code></td><td><code>4</code></td><td><code>4</code></td></tr> <tr><td><code>PROGPOW_CACHE_BYTES</code></td><td><code>16x1024</code></td><td><code>16x1024</code></td></tr> <tr><td><code>PROGPOW_CNT_DAG</code></td><td><code>64</code></td><td><code>64</code></td></tr> <tr><td><code>PROGPOW_CNT_CACHE</code></td><td><code>12</code></td><td><code>11</code></td></tr> <tr><td><code>PROGPOW_CNT_MATH</code></td><td><code>20</code></td><td><code>18</code></td></tr> </tbody></table> <table><thead><tr><th>DAG Parameter</th><th>0.9.2</th><th>0.9.3</th></tr></thead><tbody> <tr><td><code>ETHASH_DATASET_PARENTS</code></td><td><code>256</code></td><td><code>256</code></td></tr> </tbody></table> <p>The random program changes every <code>PROGPOW_PERIOD</code> blocks (default <code>10</code>, roughly 2 minutes) to ensure the hardware executing the algorithm is fully programmable. If the program only changed every DAG epoch (roughly 5 days) certain miners could have time to develop hand-optimized versions of the random sequence, giving them an undue advantage.</p> <p>Sample code is written in C++, this should be kept in mind when evaluating the code in the specification. All numerics are computed using unsigned 32 bit integers. Any overflows are trimmed off before proceeding to the next computation. Languages that use numerics not fixed to bit lengths (such as Python and JavaScript) or that only use signed integers (such as Java) will need to keep their languages' quirks in mind. The extensive use of 32 bit data values aligns with modern GPUs internal data architectures.</p> <p>ProgPoW uses a 32-bit variant of <strong>FNV1a</strong> for merging data. The existing Ethash uses a similar variant of FNV1 for merging, but FNV1a provides better distribution properties.</p> <p>Test vectors can be found <a href="https://wg-eips.ritovision.com/1057/assets/test-vectors/#fnv1a">in the test vectors file</a>.</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-storage">const</span><span class="z-storage z-type"> uint32_t</span><span> FNV_PRIME </span><span class="z-keyword">=</span><span class="z-keyword"> 0x</span><span class="z-constant">1000193</span><span>;</span></span> <span class="giallo-l"><span class="z-storage">const</span><span class="z-storage z-type"> uint32_t</span><span> FNV_OFFSET_BASIS </span><span class="z-keyword">=</span><span class="z-keyword"> 0x</span><span class="z-constant">811c9dc5</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">uint32_t</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span class="z-storage z-type">uint32_t</span><span class="z-variable"> h</span><span>,</span><span class="z-storage z-type"> uint32_t</span><span class="z-variable"> d</span><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>h </span><span class="z-keyword">^</span><span> d</span><span>)</span><span class="z-keyword"> *</span><span> FNV_PRIME</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>ProgPow uses <a rel="external" href="https://en.wikipedia.org/wiki/KISS_(algorithm)">KISS99</a> for random number generation. This is the simplest (fewest instruction) random generator that passes the TestU01 statistical test suite. A more complex random number generator like Mersenne Twister can be efficiently implemented on a specialized ASIC, providing an opportunity for efficiency gains.</p> <p>Test vectors can be found <a href="https://wg-eips.ritovision.com/1057/assets/test-vectors/#kiss99">in the test vectors file</a>.</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-keyword">typedef</span><span class="z-storage z-type"> struct</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span> z</span><span>,</span><span> w</span><span>,</span><span> jsr</span><span>,</span><span> jcong</span><span>;</span></span> <span class="giallo-l"><span>}</span><span class="z-entity z-name"> kiss99_t</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> KISS99 is simple, fast, and passes the TestU01 suite</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> https://en.wikipedia.org/wiki/KISS_(algorithm)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> http://www.cse.yorku.ca/~oz/marsaglia-rng.html</span></span> <span class="giallo-l"><span class="z-storage z-type">uint32_t</span><span class="z-entity z-name"> kiss99</span><span>(</span><span class="z-support">kiss99_t</span><span class="z-storage"> &amp;</span><span class="z-variable">st</span><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">z</span><span class="z-keyword"> =</span><span class="z-constant"> 36969</span><span class="z-keyword"> *</span><span> (</span><span class="z-variable z-other">st</span><span>.</span><span class="z-variable z-other">z</span><span class="z-keyword"> &amp;</span><span class="z-constant"> 65535</span><span>)</span><span class="z-keyword"> +</span><span> (</span><span class="z-variable z-other">st</span><span>.</span><span class="z-variable z-other">z</span><span class="z-keyword"> &gt;&gt;</span><span class="z-constant"> 16</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">w</span><span class="z-keyword"> =</span><span class="z-constant"> 18000</span><span class="z-keyword"> *</span><span> (</span><span class="z-variable z-other">st</span><span>.</span><span class="z-variable z-other">w</span><span class="z-keyword"> &amp;</span><span class="z-constant"> 65535</span><span>)</span><span class="z-keyword"> +</span><span> (</span><span class="z-variable z-other">st</span><span>.</span><span class="z-variable z-other">w</span><span class="z-keyword"> &gt;&gt;</span><span class="z-constant"> 16</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span> MWC </span><span class="z-keyword">=</span><span> (</span><span>(</span><span class="z-variable z-other">st</span><span>.</span><span class="z-variable z-other">z</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 16</span><span>)</span><span class="z-keyword"> +</span><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">w</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">jsr</span><span class="z-keyword"> ^=</span><span> (</span><span class="z-variable z-other">st</span><span>.</span><span class="z-variable z-other">jsr</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 17</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">jsr</span><span class="z-keyword"> ^=</span><span> (</span><span class="z-variable z-other">st</span><span>.</span><span class="z-variable z-other">jsr</span><span class="z-keyword"> &gt;&gt;</span><span class="z-constant"> 13</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">jsr</span><span class="z-keyword"> ^=</span><span> (</span><span class="z-variable z-other">st</span><span>.</span><span class="z-variable z-other">jsr</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 5</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">jcong</span><span class="z-keyword"> =</span><span class="z-constant"> 69069</span><span class="z-keyword"> *</span><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">jcong</span><span class="z-keyword"> +</span><span class="z-constant"> 1234567</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> (</span><span>(</span><span>MWC</span><span class="z-keyword">^</span><span class="z-variable z-other">st</span><span>.</span><span class="z-variable z-other">jcong</span><span>)</span><span class="z-keyword"> +</span><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">jsr</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <code>fill_mix</code> function populates an array of <code>int32</code> values used by each lane in the hash calculations.</p> <p>Test vectors can be found <a href="https://wg-eips.ritovision.com/1057/assets/test-vectors/#fill-mix">in the test vectors file</a>.</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-storage z-type">void</span><span class="z-entity z-name"> fill_mix</span><span>(</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint64_t</span><span class="z-variable"> seed</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span class="z-variable"> lane_id</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span class="z-variable"> mix</span><span>[</span><span>PROGPOW_REGS</span><span>]</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Use FNV to expand the per-warp seed to per-lane</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Use KISS to expand the per-lane seed to fill mix</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span> fnv_hash </span><span class="z-keyword">=</span><span> FNV_OFFSET_BASIS</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> kiss99_t</span><span> st</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">z</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span>fnv_hash</span><span>,</span><span> seed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">w</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span>fnv_hash</span><span>,</span><span> seed </span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">jsr</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span>fnv_hash</span><span>,</span><span> lane_id</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> st</span><span>.</span><span class="z-variable z-other">jcong</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span>fnv_hash</span><span>,</span><span> lane_id</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> PROGPOW_REGS</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> mix</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> kiss99</span><span>(</span><span>st</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Like Ethash Keccak is used to seed the sequence per-nonce and to produce the final result. The keccak-f800 variant is used as the 32-bit word size matches the native word size of modern GPUs. The implementation is a variant of SHAKE with width=800, bitrate=576, capacity=224, output=256, and no padding. The result of keccak is treated as a 256-bit big-endian number - that is result byte 0 is the MSB of the value.</p> <p>As with Ethash the input and output of the keccak function are fixed and relatively small. This means only a single "absorb" and "squeeze" phase are required. For a pseudo-code implementation of the <code>keccak_f800_round</code> function see the <code>Round[b](A,RC)</code> function in the "Pseudo-code description of the permutations" section of the <a rel="external" href="https://keccak.team/keccak_specs_summary.html">official Keccak specs</a>.</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-support">hash32_t</span><span class="z-entity z-name"> keccak_f800_progpow</span><span>(</span><span class="z-storage z-type">uint32_t</span><span class="z-storage">*</span><span class="z-variable"> state</span><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> keccak_f800 call for the single absorb pass</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> r </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> r </span><span class="z-keyword">&lt;</span><span class="z-constant"> 22</span><span>;</span><span> r</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> keccak_f800_round</span><span>(</span><span>st</span><span>,</span><span> r</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Squeeze phase for fixed 8 words of output</span></span> <span class="giallo-l"><span class="z-support"> hash32_t</span><span> ret</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span> i</span><span class="z-keyword">&lt;</span><span class="z-constant">8</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> ret</span><span>.</span><span class="z-variable z-other">uint32s</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> st</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> ret</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The inner loop uses FNV and KISS99 to generate a random sequence from the <code>prog_seed</code>. This random sequence determines which mix state is accessed and what random math is performed.</p> <p>Since the <code>prog_seed</code> changes only once per <code>PROGPOW_PERIOD</code> (10 blocks or about 2 minutes) it is expected that while mining <code>progPowLoop</code> will be evaluated on the CPU to generate source code for that period's sequence. The source code will be compiled on the CPU before running on the GPU. You can see an example sequence and generated source code in <a rel="external" href="https://github.com/ifdefelse/ProgPOW/blob/824cd791634204c4cc7e31f84bb76c0c84895bd3/test/kernel.cu">kernel.cu</a>.</p> <p>Test vectors can be found <a href="https://wg-eips.ritovision.com/1057/assets/test-vectors/#progpowinit">in the test vectors file</a>.</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-support">kiss99_t</span><span class="z-entity z-name"> progPowInit</span><span>(</span><span class="z-storage z-type">uint64_t</span><span class="z-variable"> prog_seed</span><span>,</span><span class="z-storage z-type"> int</span><span class="z-variable"> mix_seq_dst</span><span>[</span><span>PROGPOW_REGS</span><span>]</span><span>,</span><span class="z-storage z-type"> int</span><span class="z-variable"> mix_seq_src</span><span>[</span><span>PROGPOW_REGS</span><span>]</span><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> kiss99_t</span><span> prog_rnd</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> prog_rnd</span><span>.</span><span class="z-variable z-other">z</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span>FNV_OFFSET_BASIS</span><span>,</span><span> prog_seed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> prog_rnd</span><span>.</span><span class="z-variable z-other">w</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span class="z-variable z-other">prog_rnd</span><span>.</span><span class="z-variable z-other">z</span><span>,</span><span> prog_seed </span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> prog_rnd</span><span>.</span><span class="z-variable z-other">jsr</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span class="z-variable z-other">prog_rnd</span><span>.</span><span class="z-variable z-other">w</span><span>,</span><span> prog_seed</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> prog_rnd</span><span>.</span><span class="z-variable z-other">jcong</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span class="z-variable z-other">prog_rnd</span><span>.</span><span class="z-variable z-other">jsr</span><span>,</span><span> prog_seed </span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 32</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Create a random sequence of mix destinations for merge() and mix sources for cache reads</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> guarantees every destination merged once</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> guarantees no duplicate cache reads, which could be optimized away</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Uses Fisher-Yates shuffle</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> PROGPOW_REGS</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> mix_seq_dst</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> i</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> mix_seq_src</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> i</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span> PROGPOW_REGS </span><span class="z-keyword">-</span><span class="z-constant"> 1</span><span>;</span><span> i </span><span class="z-keyword">&gt;</span><span class="z-constant"> 0</span><span>;</span><span> i</span><span class="z-keyword">--</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> j</span><span>;</span></span> <span class="giallo-l"><span> j </span><span class="z-keyword">=</span><span class="z-entity z-name"> kiss99</span><span>(</span><span>prog_rnd</span><span>)</span><span class="z-keyword"> %</span><span> (</span><span>i </span><span class="z-keyword">+</span><span class="z-constant"> 1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> swap</span><span>(</span><span class="z-variable z-other">mix_seq_dst</span><span>[</span><span>i</span><span>]</span><span>,</span><span class="z-variable z-other"> mix_seq_dst</span><span>[</span><span>j</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> j </span><span class="z-keyword">=</span><span class="z-entity z-name"> kiss99</span><span>(</span><span>prog_rnd</span><span>)</span><span class="z-keyword"> %</span><span> (</span><span>i </span><span class="z-keyword">+</span><span class="z-constant"> 1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> swap</span><span>(</span><span class="z-variable z-other">mix_seq_src</span><span>[</span><span>i</span><span>]</span><span>,</span><span class="z-variable z-other"> mix_seq_src</span><span>[</span><span>j</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> prog_rnd</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The math operations that merges values into the mix data are ones chosen to maintain entropy.</p> <p>Test vectors can be found <a href="https://wg-eips.ritovision.com/1057/assets/test-vectors/#math">in the test vectors file</a>.</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Merge new data from b into the value in a</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Assuming A has high entropy only do ops that retain entropy</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> even if B is low entropy</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> (IE don&#39;t do A&amp;B)</span></span> <span class="giallo-l"><span class="z-storage z-type">uint32_t</span><span class="z-entity z-name"> merge</span><span>(</span><span class="z-storage z-type">uint32_t</span><span class="z-variable"> a</span><span>,</span><span class="z-storage z-type"> uint32_t</span><span class="z-variable"> b</span><span>,</span><span class="z-storage z-type"> uint32_t</span><span class="z-variable"> r</span><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> switch</span><span> (</span><span>r </span><span class="z-keyword">%</span><span class="z-constant"> 4</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 0</span><span>:</span><span class="z-keyword"> return</span><span> (</span><span>a </span><span class="z-keyword">*</span><span class="z-constant"> 33</span><span>)</span><span class="z-keyword"> +</span><span> b</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 1</span><span>:</span><span class="z-keyword"> return</span><span> (</span><span>a </span><span class="z-keyword">^</span><span> b</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 33</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> prevent rotate by 0 which is a NOP</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 2</span><span>:</span><span class="z-keyword"> return</span><span class="z-entity z-name"> ROTL32</span><span>(</span><span>a</span><span>,</span><span> (</span><span>(</span><span>r </span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 16</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> 31</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> ^</span><span> b</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 3</span><span>:</span><span class="z-keyword"> return</span><span class="z-entity z-name"> ROTR32</span><span>(</span><span>a</span><span>,</span><span> (</span><span>(</span><span>r </span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 16</span><span>)</span><span class="z-keyword"> %</span><span class="z-constant"> 31</span><span>)</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> ^</span><span> b</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The math operations chosen for the random math are ones that are easy to implement in CUDA and OpenCL, the two main programming languages for commodity GPUs. The <a rel="external" href="https://www.khronos.org/registry/OpenCL/sdk/1.1/docs/man/xhtml/mul_hi.html">mul_hi</a>, <a rel="external" href="https://www.khronos.org/registry/OpenCL/sdk/2.0/docs/man/xhtml/integerMax.html">min</a>, <a rel="external" href="https://www.khronos.org/registry/OpenCL/sdk/1.1/docs/man/xhtml/clz.html">clz</a>, and <a rel="external" href="https://www.khronos.org/registry/OpenCL/sdk/2.0/docs/man/xhtml/popcount.html">popcount</a> functions match the corresponding OpenCL functions. ROTL32 matches the OpenCL <a rel="external" href="https://www.khronos.org/registry/OpenCL/sdk/1.0/docs/man/xhtml/rotate.html">rotate</a> function. ROTR32 is rotate right, which is equivalent to <code>rotate(i, 32-v)</code>.</p> <p>Test vectors can be found <a href="https://wg-eips.ritovision.com/1057/assets/test-vectors/#math">in the test vectors file</a>.</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> Random math between two input values</span></span> <span class="giallo-l"><span class="z-storage z-type">uint32_t</span><span class="z-entity z-name"> math</span><span>(</span><span class="z-storage z-type">uint32_t</span><span class="z-variable"> a</span><span>,</span><span class="z-storage z-type"> uint32_t</span><span class="z-variable"> b</span><span>,</span><span class="z-storage z-type"> uint32_t</span><span class="z-variable"> r</span><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> switch</span><span> (</span><span>r </span><span class="z-keyword">%</span><span class="z-constant"> 11</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 0</span><span>:</span><span class="z-keyword"> return</span><span> a </span><span class="z-keyword">+</span><span> b</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 1</span><span>:</span><span class="z-keyword"> return</span><span> a </span><span class="z-keyword">*</span><span> b</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 2</span><span>:</span><span class="z-keyword"> return</span><span class="z-entity z-name"> mul_hi</span><span>(</span><span>a</span><span>,</span><span> b</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 3</span><span>:</span><span class="z-keyword"> return</span><span class="z-entity z-name"> min</span><span>(</span><span>a</span><span>,</span><span> b</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 4</span><span>:</span><span class="z-keyword"> return</span><span class="z-entity z-name"> ROTL32</span><span>(</span><span>a</span><span>,</span><span> b</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 5</span><span>:</span><span class="z-keyword"> return</span><span class="z-entity z-name"> ROTR32</span><span>(</span><span>a</span><span>,</span><span> b</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 6</span><span>:</span><span class="z-keyword"> return</span><span> a </span><span class="z-keyword">&amp;</span><span> b</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 7</span><span>:</span><span class="z-keyword"> return</span><span> a </span><span class="z-keyword">|</span><span> b</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 8</span><span>:</span><span class="z-keyword"> return</span><span> a </span><span class="z-keyword">^</span><span> b</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 9</span><span>:</span><span class="z-keyword"> return</span><span class="z-entity z-name"> clz</span><span>(</span><span>a</span><span>)</span><span class="z-keyword"> +</span><span class="z-entity z-name"> clz</span><span>(</span><span>b</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> case</span><span class="z-constant"> 10</span><span>:</span><span class="z-keyword"> return</span><span class="z-entity z-name"> popcount</span><span>(</span><span>a</span><span>)</span><span class="z-keyword"> +</span><span class="z-entity z-name"> popcount</span><span>(</span><span>b</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The flow of the inner loop is:</p> <ul> <li>Lane <code>(loop % LANES)</code> is chosen as the leader for that loop iteration</li> <li>The leader's <code>mix[0]</code> value modulo the number of 256-byte DAG entries is used to select where to read from the full DAG</li> <li>Each lane reads <code>DAG_LOADS</code> sequential words, using <code>(lane ^ loop) % LANES</code> as the starting offset within the entry.</li> <li>The random sequence of math and cache accesses is performed</li> <li>The DAG data read at the start of the loop is merged at the end of the loop</li> </ul> <p><code>prog_seed</code> and <code>loop</code> come from the outer loop, corresponding to the current program seed (which is block_number/PROGPOW_PERIOD) and the loop iteration number. <code>mix</code> is the state array, initially filled by <code>fill_mix</code>. <code>dag</code> is the bytes of the Ethash DAG grouped into 32 bit unsigned ints in little-endian format. On little-endian architectures this is just a normal int32 pointer to the existing DAG.</p> <p><code>DAG_BYTES</code> is set to the number of bytes in the current DAG, which is generated identically to the existing Ethash algorithm.</p> <p>Test vectors can be found <a href="https://wg-eips.ritovision.com/1057/assets/test-vectors/#progpowloop">in the test vectors file</a>.</p> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-storage z-type">void</span><span class="z-entity z-name"> progPowLoop</span><span>(</span></span> <span class="giallo-l"><span class="z-storage"> const</span><span class="z-storage z-type"> uint64_t</span><span class="z-variable"> prog_seed</span><span>,</span></span> <span class="giallo-l"><span class="z-storage"> const</span><span class="z-storage z-type"> uint32_t</span><span class="z-variable"> loop</span><span>,</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span class="z-variable"> mix</span><span>[</span><span>PROGPOW_LANES</span><span>]</span><span>[</span><span>PROGPOW_REGS</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-storage"> const</span><span class="z-storage z-type"> uint32_t</span><span class="z-storage"> *</span><span class="z-variable">dag</span><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> dag_entry holds the 256 bytes of data loaded from the DAG</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span class="z-variable z-other"> dag_entry</span><span>[</span><span>PROGPOW_LANES</span><span>]</span><span>[</span><span>PROGPOW_DAG_LOADS</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> On each loop iteration rotate which lane is the source of the DAG address.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> The source lane&#39;s mix[0] value is used to ensure the last loop&#39;s DAG data feeds into this loop&#39;s address.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> dag_addr_base is which 256-byte entry within the DAG will be accessed</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span> dag_addr_base </span><span class="z-keyword">=</span><span class="z-variable z-other"> mix</span><span>[</span><span>loop</span><span class="z-keyword">%</span><span>PROGPOW_LANES</span><span>]</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword"> %</span></span> <span class="giallo-l"><span> (</span><span>DAG_BYTES </span><span class="z-keyword">/</span><span> (</span><span>PROGPOW_LANES</span><span class="z-keyword">*</span><span>PROGPOW_DAG_LOADS</span><span class="z-keyword">*</span><span class="z-keyword">sizeof</span><span>(</span><span class="z-storage z-type">uint32_t</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> l </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> l </span><span class="z-keyword">&lt;</span><span> PROGPOW_LANES</span><span>;</span><span> l</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Lanes access DAG_LOADS sequential words from the dag entry</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Shuffle which portion of the entry each lane accesses each iteration by XORing lane and loop.</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> This prevents multi-chip ASICs from each storing just a portion of the DAG</span></span> <span class="giallo-l"><span class="z-storage z-type"> size_t</span><span> dag_addr_lane </span><span class="z-keyword">=</span><span> dag_addr_base </span><span class="z-keyword">*</span><span> PROGPOW_LANES </span><span class="z-keyword">+</span><span> (</span><span>l </span><span class="z-keyword">^</span><span> loop</span><span>)</span><span class="z-keyword"> %</span><span> PROGPOW_LANES</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> PROGPOW_DAG_LOADS</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> dag_entry</span><span>[</span><span>l</span><span>]</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> dag</span><span>[</span><span>dag_addr_lane </span><span class="z-keyword">*</span><span> PROGPOW_DAG_LOADS </span><span class="z-keyword">+</span><span> i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Initialize the program seed and sequences</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> When mining these are evaluated on the CPU and compiled away</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span class="z-variable z-other"> mix_seq_dst</span><span>[</span><span>PROGPOW_REGS</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span class="z-variable z-other"> mix_seq_src</span><span>[</span><span>PROGPOW_REGS</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> mix_seq_dst_cnt </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> mix_seq_src_cnt </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> kiss99_t</span><span> prog_rnd </span><span class="z-keyword">=</span><span class="z-entity z-name"> progPowInit</span><span>(</span><span>prog_seed</span><span>,</span><span> mix_seq_dst</span><span>,</span><span> mix_seq_src</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> max_i </span><span class="z-keyword">=</span><span class="z-entity z-name"> max</span><span>(</span><span>PROGPOW_CNT_CACHE</span><span>,</span><span> PROGPOW_CNT_MATH</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> max_i</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>i </span><span class="z-keyword">&lt;</span><span> PROGPOW_CNT_CACHE</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Cached memory access</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> lanes access random 32-bit locations within the first portion of the DAG</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> src </span><span class="z-keyword">=</span><span class="z-variable z-other"> mix_seq_src</span><span>[</span><span>(</span><span>mix_seq_src_cnt</span><span class="z-keyword">++</span><span>)</span><span class="z-keyword">%</span><span>PROGPOW_REGS</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> dst </span><span class="z-keyword">=</span><span class="z-variable z-other"> mix_seq_dst</span><span>[</span><span>(</span><span>mix_seq_dst_cnt</span><span class="z-keyword">++</span><span>)</span><span class="z-keyword">%</span><span>PROGPOW_REGS</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> sel </span><span class="z-keyword">=</span><span class="z-entity z-name"> kiss99</span><span>(</span><span>prog_rnd</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> l </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> l </span><span class="z-keyword">&lt;</span><span> PROGPOW_LANES</span><span>;</span><span> l</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span> offset </span><span class="z-keyword">=</span><span class="z-variable z-other"> mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>src</span><span>]</span><span class="z-keyword"> %</span><span> (</span><span>PROGPOW_CACHE_BYTES</span><span class="z-keyword">/</span><span class="z-keyword">sizeof</span><span>(</span><span class="z-storage z-type">uint32_t</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>dst</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> merge</span><span>(</span><span class="z-variable z-other">mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>dst</span><span>]</span><span>,</span><span class="z-variable z-other"> dag</span><span>[</span><span>offset</span><span>]</span><span>,</span><span> sel</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>i </span><span class="z-keyword">&lt;</span><span> PROGPOW_CNT_MATH</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Random Math</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Generate 2 unique sources</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> src_rnd </span><span class="z-keyword">=</span><span class="z-entity z-name"> kiss99</span><span>(</span><span>prog_rnd</span><span>)</span><span class="z-keyword"> %</span><span> (</span><span>PROGPOW_REGS </span><span class="z-keyword">*</span><span> (</span><span>PROGPOW_REGS</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> src1 </span><span class="z-keyword">=</span><span> src_rnd </span><span class="z-keyword">%</span><span> PROGPOW_REGS</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 0 &lt;= src1 &lt; PROGPOW_REGS</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> src2 </span><span class="z-keyword">=</span><span> src_rnd </span><span class="z-keyword">/</span><span> PROGPOW_REGS</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 0 &lt;= src2 &lt; PROGPOW_REGS - 1</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>src2 </span><span class="z-keyword">&gt;=</span><span> src1</span><span>)</span><span class="z-keyword"> ++</span><span>src2</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> src2 is now any reg other than src1</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> sel1 </span><span class="z-keyword">=</span><span class="z-entity z-name"> kiss99</span><span>(</span><span>prog_rnd</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> dst </span><span class="z-keyword">=</span><span class="z-variable z-other"> mix_seq_dst</span><span>[</span><span>(</span><span>mix_seq_dst_cnt</span><span class="z-keyword">++</span><span>)</span><span class="z-keyword">%</span><span>PROGPOW_REGS</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> sel2 </span><span class="z-keyword">=</span><span class="z-entity z-name"> kiss99</span><span>(</span><span>prog_rnd</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> l </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> l </span><span class="z-keyword">&lt;</span><span> PROGPOW_LANES</span><span>;</span><span> l</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span> data </span><span class="z-keyword">=</span><span class="z-entity z-name"> math</span><span>(</span><span class="z-variable z-other">mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>src1</span><span>]</span><span>,</span><span class="z-variable z-other"> mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>src2</span><span>]</span><span>,</span><span> sel1</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>dst</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> merge</span><span>(</span><span class="z-variable z-other">mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>dst</span><span>]</span><span>,</span><span> data</span><span>,</span><span> sel2</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Consume the global load data at the very end of the loop to allow full latency hiding</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Always merge into mix[0] to feed the offset calculation</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> PROGPOW_DAG_LOADS</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> dst </span><span class="z-keyword">=</span><span> (</span><span>i</span><span class="z-keyword">==</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> ?</span><span class="z-constant"> 0</span><span class="z-keyword"> :</span><span class="z-variable z-other"> mix_seq_dst</span><span>[</span><span>(</span><span>mix_seq_dst_cnt</span><span class="z-keyword">++</span><span>)</span><span class="z-keyword">%</span><span>PROGPOW_REGS</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> int</span><span> sel </span><span class="z-keyword">=</span><span class="z-entity z-name"> kiss99</span><span>(</span><span>prog_rnd</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> l </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> l </span><span class="z-keyword">&lt;</span><span> PROGPOW_LANES</span><span>;</span><span> l</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>dst</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> merge</span><span>(</span><span class="z-variable z-other">mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>dst</span><span>]</span><span>,</span><span class="z-variable z-other"> dag_entry</span><span>[</span><span>l</span><span>]</span><span>[</span><span>i</span><span>]</span><span>,</span><span> sel</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The flow of the overall algorithm is:</p> <ul> <li>A keccak hash of the header + nonce to create a digest of 256 bits from keccak_f800 (padding is consistent with custom one in ethash)</li> <li>Use first two words of digest as seed to generate initial mix data</li> <li>Loop multiple times, each time hashing random loads and random math into the mix data</li> <li>Hash all the mix data into a single 256-bit value</li> <li>A final keccak hash using carry-over digest from initial data + mix_data final 256 bit value (padding is consistent with custom one in ethash)</li> <li>When mining this final value is compared against a <code>hash32_t</code> target</li> </ul> <pre class="giallo z-code"><code data-lang="cpp"><span class="giallo-l"><span class="z-support">hash32_t</span><span class="z-entity z-name"> progPowHash</span><span>(</span></span> <span class="giallo-l"><span class="z-storage"> const</span><span class="z-storage z-type"> uint64_t</span><span class="z-variable"> prog_seed</span><span>,</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> value is (block_number/PROGPOW_PERIOD)</span></span> <span class="giallo-l"><span class="z-storage"> const</span><span class="z-storage z-type"> uint64_t</span><span class="z-variable"> nonce</span><span>,</span></span> <span class="giallo-l"><span class="z-storage"> const</span><span class="z-support"> hash32_t</span><span class="z-variable"> header</span><span>,</span></span> <span class="giallo-l"><span class="z-storage"> const</span><span class="z-storage z-type"> uint32_t</span><span class="z-storage"> *</span><span class="z-variable">dag</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> gigabyte DAG located in framebuffer - the first portion gets cached</span></span> <span class="giallo-l"><span>)</span></span> <span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> hash32_t</span><span> hash_init</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> hash32_t</span><span> hash_final</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span class="z-variable z-other"> mix</span><span>[</span><span>PROGPOW_LANES</span><span>]</span><span>[</span><span>PROGPOW_REGS</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /*</span><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> ========================================</span></span> <span class="giallo-l"><span class="z-comment"> Absorb phase for initial keccak pass</span></span> <span class="giallo-l"><span class="z-comment"> ========================================</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span class="z-variable z-other"> state</span><span>[</span><span class="z-constant">25</span><span>]</span><span class="z-keyword"> =</span><span> {</span><span class="z-keyword">0x</span><span class="z-constant">0</span><span>}</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 1st fill with header data (8 words)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span class="z-constant"> 8</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> header</span><span>.</span><span class="z-variable z-other">uint32s</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 2nd fill with nonce (2 words)</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span>[</span><span class="z-constant">8</span><span>]</span><span class="z-keyword"> =</span><span> nonce</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span>[</span><span class="z-constant">9</span><span>]</span><span class="z-keyword"> =</span><span> nonce </span><span class="z-keyword">&gt;&gt;</span><span class="z-constant"> 32</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 3rd apply padding</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span>[</span><span class="z-constant">10</span><span>]</span><span class="z-keyword"> =</span><span class="z-keyword"> 0x</span><span class="z-constant">00000001</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span>[</span><span class="z-constant">18</span><span>]</span><span class="z-keyword"> =</span><span class="z-keyword"> 0x</span><span class="z-constant">80008081</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> keccak(header..nonce)</span></span> <span class="giallo-l"><span> hash_init </span><span class="z-keyword">=</span><span class="z-entity z-name"> keccak_f800_progpow</span><span>(</span><span>state</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> get the seed to initialize mix</span></span> <span class="giallo-l"><span> seed </span><span class="z-keyword">=</span><span> (</span><span>(</span><span class="z-storage z-type">uint64_t</span><span>)</span><span class="z-variable z-other">hash_init</span><span>.</span><span class="z-variable z-other">uint32s</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> &lt;&lt;</span><span class="z-constant"> 32</span><span>)</span><span class="z-keyword"> |</span><span class="z-variable z-other"> hash_init</span><span>.</span><span class="z-variable z-other">uint32s</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> initialize mix for all lanes</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> l </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> l </span><span class="z-keyword">&lt;</span><span> PROGPOW_LANES</span><span>;</span><span> l</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> fill_mix</span><span>(</span><span>seed</span><span>,</span><span> l</span><span>,</span><span class="z-variable z-other"> mix</span><span>[</span><span>l</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> execute the randomly generated inner loop</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> PROGPOW_CNT_DAG</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-entity z-name"> progPowLoop</span><span>(</span><span>prog_seed</span><span>,</span><span> i</span><span>,</span><span> mix</span><span>,</span><span> dag</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Reduce mix data to a per-lane 32-bit digest</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span class="z-variable z-other"> digest_lane</span><span>[</span><span>PROGPOW_LANES</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> l </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> l </span><span class="z-keyword">&lt;</span><span> PROGPOW_LANES</span><span>;</span><span> l</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> digest_lane</span><span>[</span><span>l</span><span>]</span><span class="z-keyword"> =</span><span> FNV_OFFSET_BASIS</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> PROGPOW_REGS</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> digest_lane</span><span>[</span><span>l</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span class="z-variable z-other">digest_lane</span><span>[</span><span>l</span><span>]</span><span>,</span><span class="z-variable z-other"> mix</span><span>[</span><span>l</span><span>]</span><span>[</span><span>i</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Reduce all lanes to a single 256-bit digest</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span class="z-constant"> 8</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> digest</span><span>.</span><span class="z-variable z-other">uint32s</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span> FNV_OFFSET_BASIS</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> l </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> l </span><span class="z-keyword">&lt;</span><span> PROGPOW_LANES</span><span>;</span><span> l</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> digest</span><span>.</span><span class="z-variable z-other">uint32s</span><span>[</span><span>l</span><span class="z-keyword">%</span><span class="z-constant">8</span><span>]</span><span class="z-keyword"> =</span><span class="z-entity z-name"> fnv1a</span><span>(</span><span class="z-variable z-other">digest</span><span>.</span><span class="z-variable z-other">uint32s</span><span>[</span><span>l</span><span class="z-keyword">%</span><span class="z-constant">8</span><span>]</span><span>,</span><span class="z-variable z-other"> digest_lane</span><span>[</span><span>l</span><span>]</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /*</span><span class="z-comment"> </span></span> <span class="giallo-l"><span class="z-comment"> ========================================</span></span> <span class="giallo-l"><span class="z-comment"> Absorb phase for final keccak pass</span></span> <span class="giallo-l"><span class="z-comment"> ========================================</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> uint32_t</span><span class="z-variable z-other"> state</span><span>[</span><span class="z-constant">25</span><span>]</span><span class="z-keyword"> =</span><span> {</span><span class="z-keyword">0x</span><span class="z-constant">0</span><span>}</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 1st fill with hash_init (8 words)</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span class="z-constant"> 8</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> hash_init</span><span>.</span><span class="z-variable z-other">uint32s</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 2nd fill with digest from main loop</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-storage z-type">int</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 8</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span class="z-constant"> 16</span><span>;</span><span> i</span><span class="z-keyword">++</span><span>)</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span>[</span><span>i</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable z-other"> digest</span><span>.</span><span class="z-variable z-other">uint32s</span><span>[</span><span>i </span><span class="z-keyword">-</span><span class="z-constant"> 8</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> 3rd apply padding</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span>[</span><span class="z-constant">17</span><span>]</span><span class="z-keyword"> =</span><span class="z-keyword"> 0x</span><span class="z-constant">00000001</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> state</span><span>[</span><span class="z-constant">24</span><span>]</span><span class="z-keyword"> =</span><span class="z-keyword"> 0x</span><span class="z-constant">80008081</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> keccak(header..nonce)</span></span> <span class="giallo-l"><span> hash_final </span><span class="z-keyword">=</span><span class="z-entity z-name"> keccak_f800_progpow</span><span>(</span><span>state</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Compare hash final to target</span></span> <span class="giallo-l"><span> [</span><span>...</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="security-considerations">Security Considerations</h2> <p>This proposal has been software and hardware audited:</p> <ul> <li><a rel="external" href="https://leastauthority.com/static/publications/LeastAuthority-ProgPow-Algorithm-Final-Audit-Report.pdf">Least Authority — ProgPoW Software Audit PDF</a></li> <li><a rel="external" href="https://github.com/ethereum-cat-herders/progpow-audit/raw/master/Bob%20Rao%20-%20ProgPOW%20Hardware%20Audit%20Report%20Final.pdf">Bob Rao - ProgPoW Hardware Audit PDF</a></li> </ul> <p>Least Authority in their findings suggest a change to DAG generation -- modification of <code>ETHASH_DATASET_PARENTS</code> from a value of 256 to the new value of 512 -- in order to mitigate vulnerability to a "Light Evaluation" attack. Due to this the DAG memory file used by ProgPoW is would no longer compatible with the one used by Ethash (epoch length and size increase ratio remain the same though).</p> <p>We do not recommend implementing this fix at this time. Ethash will not be exploitable for years, and it's not clear ProgPoW will ever be exploitable. It's better to deploy the audited code.</p> <p>After the completion of the audits a clever finding by <a rel="external" href="https://github.com/kik/">Kik</a> disclosed a vulnerability to <a rel="external" href="https://github.com/kik/progpow-exploit">bypassing ProgPoW memory hardness</a>. The vulnerability is present in Ethash as well but is near-impossible to exploit. In progPoW it is not possible to exploit -- it assumes the ability to create variants of the candidate block's header hash in a fashion similar to bitcoin, which is actually not possible in Ethereum. An attacker would need modified block headers, would need customized nodes able to accept the modified block headers, and uses extraNonce/extraData as entropy -- which isn’t the standard. And the required brute-force search would be difficult to accomplish in one blocktime. And even if supported by a customized node the block propagation of such mined blocks would be immediately blocked by other peers as the header hash is invalid.</p> <p>The authors have since found another vulnerability similar to Kik's, but it adds too much overhead to be ASIC-friendly. See Lanfranchi's full explanation <a rel="external" href="https://github.com/ifdefelse/ProgPOW/issues/51#issuecomment-690155355">here</a>. To completely prevent such exploits we could change the condition modifying the input state of the last keccak pass from</p> <ul> <li>header (256 bits) +</li> <li>seed for mix initiator (64 bits) +</li> <li>mix from main loop (256 bits)</li> <li>no padding</li> </ul> <p>to</p> <ul> <li>digest from initial keccak (256 bits) +</li> <li>mix from main loop (256 bits) +</li> <li>padding</li> </ul> <p>thus widening the constraint to target in keccak <a rel="external" href="https://github.com/kik/progpow-exploit">brute force keccak linear searches</a> from 64 to 256 bits.</p> <p>This fix is available as a PR to the reference implementation. Again, we do not recommend implementing this fix at this time. Kik's vulnerability and others like it cannot be exploited now and likely never will be. It's better to deploy the audited code.</p> <p>Note that these vulnerabilities cannot be exploited to deny service, double spend, or otherwise damage the network. They could at worst give their deployer an efficiency advantage over other miners.</p> <h2 id="test-cases">Test Cases</h2> <p>The random sequence generated for block 30,000 (prog_seed 3,000) can been seen in <a rel="external" href="https://github.com/ifdefelse/ProgPOW/blob/824cd791634204c4cc7e31f84bb76c0c84895bd3/test/kernel.cu">kernel.cu</a>.</p> <p>The algorithm run on block 30,000 produces the following digest and result:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>Header : 0xffeeddccbbaa9988776655443322110000112233445566778899aabbccddeeff</span></span> <span class="giallo-l"><span>Nonce : 0x123456789abcdef0</span></span> <span class="giallo-l"><span>Hash init : 0xee304846ddd0a47b98179e96b60ec5ceeae2727834367e593de780e3e6d1892f</span></span> <span class="giallo-l"><span>Mix seed : 0x7ba4d0dd464830ee</span></span> <span class="giallo-l"><span>Mix hash : 0x493c13e9807440571511b561132834bbd558dddaa3b70c09515080a6a1aff6d0</span></span> <span class="giallo-l"><span>Hash final : 0x46b72b75f238bea3fcfd227e0027dc173dceaa1fb71744bd3d5e030ed2fed053</span></span></code></pre> <p>Additional test vectors can be found <a href="https://wg-eips.ritovision.com/1057/assets/test-vectors/#progpowhash">in the test vectors file</a>.</p> <p>Machine-readable test vectors (T.B.D)</p> <h2 id="implementation">Implementation</h2> <p>The reference ProgPoW mining implementation is located at <a rel="external" href="https://github.com/ifdefelse/ProgPOW">the @ifdefelse ProgPOW repository</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> <p>The reference ProgPoW mining implementation located at <a rel="external" href="https://github.com/ifdefelse/ProgPOW">ProgPOW</a> is a derivative of ethminer so retains the GPL license.</p> 2018-05-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Phyrex Tsaiphyrex@portal.network Portal Network Team https://wg-eips.ritovision.com/1062/ <h2 id="simple-summary">Simple Summary</h2> <p>To specify the mapping protocol between resources stored on IPFS and ENS(Ethereum Naming Service).</p> <h2 id="abstract">Abstract</h2> <p>The following standard details the implementation of how to combine the IPFS cryptographic hash unique fingerprint with ENS public resolver. This standard provides a functionality to get and set IPFS online resources to ENS resolver.</p> <p>We think that this implementation is not only aim to let more developers and communities to provide more use cases, but also leverage the human-readable features to gain more user adoption accessing decentralized resources. We considered the IPFS ENS resolver mapping standard a cornerstone for building future Web3.0 service.</p> <h2 id="motivation">Motivation</h2> <p>To build a fully decentralized web service, it’s necessary to have a decentralized file storage system. Here comes the IPFS, for three following advantages :</p> <ul> <li>Address large amounts of data, and has unique cryptographic hash for every record.</li> <li>Since IPFS is also based on peer to peer network, it can be really helpful to deliver large amounts of data to users, in a safer way and lower the millions of cost for the bandwidth.</li> <li>IPFS stores files in high efficient way via tracking version history for every file, and removing the duplications across the network.</li> </ul> <p>Those features makes perfect match for integrating into ENS, and these make users can easily access content through ENS, and show up in the normal browser.</p> <h2 id="specification">Specification</h2> <p>The condition now is that the IPFS file fingerprint using base58 and in the meantime, the Ethereum uses hex in API to encode the binary data. So that need a way to process the condition requires not only we need to transfer from IPFS to Ethereum, but also need to convert it back.</p> <p>To solve these requirements, we can use binary buffer bridging that gap.<br /> When mapping the IPFS base58 string to ENS resolver, first we convert the Base58 to binary buffer, turn the buffer to hex encrypted format, and save to the contract. Once we want to get the IPFS resources address represented by the specific ENS, we can first find the mapping information stored as hex format before, extract the hex format to binary buffer, and finally turn that to IPFS Base58 address string.</p> <h2 id="rationale">Rationale</h2> <p>To implement the specification, need two methods from ENS public resolver contract, when we want to store IPFS file fingerprint to contract, convert the Base58 string identifier to the hex format and invoke the <code>setMultihash</code> method below :</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setMultihash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> hash</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-entity z-name"> only_owner</span><span>(</span><span class="z-entity z-name">node</span><span>)</span><span>;</span></span></code></pre> <p>Whenever users need to visit the ENS content, we call the <code>multihash</code> method to get the IPFS hex data, transfer to the Base58 format, and return the IPFS resources to use.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> multihash</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes</span><span>)</span><span>;</span></span></code></pre><h2 id="test-cases">Test Cases</h2> <p>To implement the way to transfer from base58 to hex format and the reverse one, using the ‘multihashes’ library to deal with the problem.<br /> The library link : <a rel="external" href="https://www.npmjs.com/package/multihashes">https://www.npmjs.com/package/multihashes</a><br /> To implement the method transfer from IPFS(Base58) to hex format :</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-keyword">import</span><span class="z-variable z-other"> multihash</span><span class="z-keyword"> from</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">multihashes</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">export</span><span class="z-storage z-type"> const</span><span class="z-entity z-name"> toHex</span><span class="z-keyword"> =</span><span class="z-storage z-type"> function</span><span>(</span><span class="z-variable">ipfsHash</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> buf</span><span class="z-keyword"> =</span><span class="z-variable z-other"> multihash</span><span>.</span><span class="z-entity z-name">fromB58String</span><span>(</span><span class="z-variable z-other">ipfsHash</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">0x</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> +</span><span class="z-variable z-other"> multihash</span><span>.</span><span class="z-entity z-name">toHexString</span><span>(</span><span class="z-variable z-other">buf</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>To implement the method transfer from hex format to IPFS(Base58) :</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-keyword">import</span><span class="z-variable z-other"> multihash</span><span class="z-keyword"> from</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">multihashes</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">export</span><span class="z-storage z-type"> const</span><span class="z-entity z-name"> toBase58</span><span class="z-keyword"> =</span><span class="z-storage z-type"> function</span><span>(</span><span class="z-variable">contentHash</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> hex</span><span class="z-keyword"> =</span><span class="z-variable z-other"> contentHash</span><span>.</span><span class="z-entity z-name">substring</span><span>(</span><span class="z-constant">2</span><span>)</span></span> <span class="giallo-l"><span class="z-storage z-type"> let</span><span class="z-variable z-other"> buf</span><span class="z-keyword"> =</span><span class="z-variable z-other"> multihash</span><span>.</span><span class="z-entity z-name">fromHexString</span><span>(</span><span class="z-variable z-other">hex</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> multihash</span><span>.</span><span class="z-entity z-name">toB58String</span><span>(</span><span class="z-variable z-other">buf</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>The use case can be implemented as browser extension. Users can easily download the extension, and easily get decentralized resources by just typing the ENS just like we normally type the DNS to browser the website. Solve the current pain for normal people can not easily visit the total decentralized website.</p> <p>The workable implementation repository : <a rel="external" href="https://github.com/PortalNetwork/portal-network-browser-extension">https://github.com/PortalNetwork/portal-network-browser-extension</a></p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-05-02T00:00:00+00:00 2026-02-11T14:48:25+00:00 Bradley Leatherwoodbradleat@inkibra.com https://wg-eips.ritovision.com/1080/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for tokens that support chargebacks, theft prevention, and lost &amp; found resolutions.</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows for the implementation of a standard API for tokens extending ERC-20 or ERC-791. This standard provides basic functionality to recover stolen or lost accounts, as well as provide for the chargeback of tokens.</p> <h2 id="motivation">Motivation</h2> <p>To mitigate the effects of reasonably provable token or asset loss or theft and to help resolve other conflicts. Ethereum's protocol should not be modified because of loss, theft, or conflicts, but it is possible to solve these problems in the smart contract layer.</p> <h2 id="specification">Specification</h2> <h2 id="recoverabletoken">RecoverableToken</h2> <h3 id="methods">Methods</h3> <h4 id="claimlost">claimLost</h4> <p>Reports the <code>lostAccount</code> address as being lost. MUST trigger the <code>AccountClaimedLost</code> event.</p> <p>After the time configured in <code>getLostAccountRecoveryTimeInMinutes</code> the implementer MUST provide a mechanism for determining the correct owner of the tokens held and moving the tokens to a new account.</p> <p>Account recoveries must trigger the <code>AccountRecovered</code> event.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> claimLost</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> lostAccount</span><span>)</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="cancellostclaim">cancelLostClaim</h4> <p>Reports the <code>msg.sender</code>'s account as being not being lost. MUST trigger the <code>AccountClaimedLostCanceled</code> event.</p> <p>MUST fail if an account recovery process has already begun.</p> <p>Otherwise, this method MUST stop a dispute from being started to recover funds.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> claimLost</span><span>(</span><span>)</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="reportstolen">reportStolen</h4> <p>Reports the current address as being stolen. MUST trigger the <code>AccountFrozen</code> event. Successful calls MUST result in the <code>msg.sender</code>'s tokens being frozen.</p> <p>The implementer MUST provide a mechanism for determining the correct owner of the tokens held and moving the tokens to a new account.</p> <p>Account recoveries must trigger the <code>AccountRecovered</code> event.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> reportStolen</span><span>(</span><span>)</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="chargeback">chargeback</h4> <p>Requests a reversal of transfer on behalf of <code>msg.sender</code>.</p> <p>The implementer MUST provide a mechanism for determining the correct owner of the tokens disputed and moving the tokens to the correct account.</p> <p>MUST comply with sender's chargeback window as value configured by <code>setPendingTransferTimeInMinutes</code>.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> chargeback</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> pendingTransferNumber</span><span>)</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="getpendingtransfertimeinminutes">getPendingTransferTimeInMinutes</h4> <p>Get the time an account has to chargeback a transfer.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getPendingTransferTime</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> account</span><span>)</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> minutes</span><span>)</span></span></code></pre><h4 id="setpendingtransfertimeinminutes">setPendingTransferTimeInMinutes</h4> <p>Sets the time <code>msg.sender</code>'s account has to chargeback a transfer.</p> <p>MUST NOT change the time if the account has any pending transfers.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setPendingTransferTime</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> minutes</span><span>)</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="getlostaccountrecoverytimeinminutes">getLostAccountRecoveryTimeInMinutes</h4> <p>Get the time account has to wait before a lost account dispute can start.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getLostAccountRecoveryTimeInMinutes</span><span>(</span><span class="z-variable">address</span><span class="z-variable"> account</span><span>)</span><span class="z-entity z-name"> view</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> minutes</span><span>)</span></span></code></pre><h4 id="setlostaccountrecoverytimeinminutes">setLostAccountRecoveryTimeInMinutes</h4> <p>Sets the time <code>msg.sender</code>'s account has to sit before a lost account dispute can start.</p> <p>MUST NOT change the time if the account has open disputes.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> setLostAccountRecoveryTimeInMinutes</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> minutes</span><span>)</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h3 id="events">Events</h3> <h4 id="accountrecovered">AccountRecovered</h4> <p>The recovery of an account that was lost or stolen.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> AccountClaimedLost</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> account</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> newAccount</span><span>)</span></span></code></pre><h4 id="accountclaimedlostcanceled">AccountClaimedLostCanceled</h4> <p>An account claimed as being lost.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> AccountClaimedLost</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> account</span><span>)</span></span></code></pre><h4 id="accountclaimedlost">AccountClaimedLost</h4> <p>An account claimed as being lost.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> AccountClaimedLost</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> account</span><span>)</span></span></code></pre><h4 id="pendingtransfer">PendingTransfer</h4> <p>A record of a transfer pending.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> PendingTransfer</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> from</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> value</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> pendingTransferNumber</span><span>)</span></span></code></pre><h4 id="chargebackrequested">ChargebackRequested</h4> <p>A record of a chargeback being requested.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> ChargebackRequested</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> from</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> value</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> pendingTransferNumber</span><span>)</span></span></code></pre><h4 id="chargeback-1">Chargeback</h4> <p>A record of a transfer being reversed.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> Chargeback</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> from</span><span>,</span><span class="z-variable z-other"> address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> to</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> value</span><span>,</span><span class="z-variable z-other"> uint256</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> pendingTransferNumber</span><span>)</span></span></code></pre><h4 id="accountfrozen">AccountFrozen</h4> <p>A record of an account being frozen. MUST trigger when an account is frozen.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> AccountFrozen</span><span>(</span><span class="z-variable z-other">address</span><span class="z-variable z-other"> indexed</span><span class="z-variable z-other"> reported</span><span>)</span></span></code></pre><h2 id="rationale">Rationale</h2> <ul> <li>A recoverable token standard can provide configurable safety for users or contracts who desire this safety.</li> <li>Implementations of this standard will give users the ability to select a dispute resolution process on an opt-in basis and benefit the community by decreasing the necessity of consideration of token recovery actions.</li> </ul> <h2 id="implementation">Implementation</h2> <p>Pending.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-04-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Danny Ryanhttps://github.com/djrtwo Chih-Cheng Lianghttps://github.com/ChihChengLiang https://wg-eips.ritovision.com/1011/ <h2 id="simple-summary">Simple Summary</h2> <p>Specification of the first step to transition Ethereum main net from Proof of Work (PoW) to Proof of Stake (PoS). The resulting consensus model is a PoW/PoS hybrid.</p> <h2 id="abstract">Abstract</h2> <p>This EIP specifies a hybrid PoW/PoS consensus model for Ethereum main net. Existing PoW mechanics are used for new block creation, and a novel PoS mechanism called Casper the Friendly Finality Gadget (FFG) is layered on top using a smart contract.</p> <p>Through the use of Ether deposits, slashing conditions, and a modified fork choice, FFG allows the underlying PoW blockchain to be finalized. As network security is greatly shifted from PoW to PoS, PoW block rewards are reduced.</p> <p>This EIP does not contain safety and liveness proofs or validator implementation details, but these can be found in the <a rel="external" href="https://arxiv.org/abs/1710.09437">Casper FFG paper</a> and <a rel="external" href="https://github.com/ethereum/casper/blob/master/VALIDATOR_GUIDE.md">Validator Implementation Guide</a> respectively.</p> <h2 id="glossary">Glossary</h2> <ul> <li><strong>epoch</strong>: The span of blocks between checkpoints. Epochs are numbered starting at the hybrid casper fork, incrementing by one at the start of each epoch.</li> <li><strong>finality</strong>: The point at which a block has been decided upon by a client to <em>never</em> revert. Proof of Work does not have the concept of finality, only of further deep block confirmations.</li> <li><strong>checkpoint</strong>: The block/hash under consideration for finality for a given epoch. This block is the <em>last</em> block of the previous epoch. Rather than dealing with every block, Casper FFG only considers checkpoints for finalization. When a checkpoint is explicitly finalized, all ancestor blocks of the checkpoint are implicitly finalized.</li> <li><strong>validator</strong>: A participant in the Casper FFG consensus that has deposited ether in the casper contract and has the responsibility to vote and finalize checkpoints.</li> <li><strong>validator set</strong>: The set of validators in the casper contract at any given time.</li> <li><strong>dynasty</strong>: The number of finalized checkpoints in the chain from root to the parent of a block. The dynasty is used to define when a validator starts and ends validating. The current dynasty only increments when a checkpoint is finalized as opposed to epoch numbers that increment regardless of finality.</li> <li><strong>slash</strong>: The burning of some amount of a validator's deposit along with an immediate logout from the validator set. Slashing occurs when a validator signs two conflicting <code>vote</code> messages that violate a slashing condition. For an in-depth discussion of slashing conditions, see the <a rel="external" href="https://arxiv.org/abs/1710.09437">Casper FFG Paper</a>.</li> </ul> <h2 id="motivation">Motivation</h2> <p>Transitioning the Ethereum network from PoW to PoS has been on the roadmap and in the <a rel="external" href="https://github.com/ethereum/yellowpaper">Yellow Paper</a> since the launch of the protocol. Although effective in coming to a decentralized consensus, PoW consumes an incredible amount of energy, has no economic finality, and has no effective strategy in resisting cartels. Excessive energy consumption, issues with equal access to mining hardware, mining pool centralization, and an emerging market of ASICs each provide a distinct motivation to make the transition as soon as possible.</p> <p>Until recently, the proper way to make this transition was still an open area of research. In October of 2017 <a rel="external" href="https://arxiv.org/abs/1710.09437">Casper the Friendly Finality Gadget</a> was published, solving open questions of economic finality through validator deposits and crypto-economic incentives. For a detailed discussion and proofs of "accountable safety" and "plausible liveness", see the <a rel="external" href="https://arxiv.org/abs/1710.09437">Casper FFG</a> paper.</p> <p>The Casper FFG contract can be layered on top of any block proposal mechanism, providing finality to the underlying chain. This EIP proposes layering FFG on top of the existing PoW block proposal mechanism as a conservative step-wise approach in the transition to full PoS. The new FFG staking mechanism requires minimal changes to the protocol, allowing the Ethereum network to fully test and evaluate Casper FFG on top of PoW before moving to a validator based block proposal mechanism.</p> <h2 id="parameters">Parameters</h2> <ul> <li><code>HYBRID_CASPER_FORK_BLKNUM</code>: TBD</li> <li><code>CASPER_ADDR</code>: TBD</li> <li><code>CASPER_CODE</code>: see below</li> <li><code>CASPER_BALANCE</code>: 1.25e24 wei (1,250,000 ETH)</li> <li><code>MSG_HASHER_ADDR</code>: TBD</li> <li><code>MSG_HASHER_CODE</code>: see below</li> <li><code>PURITY_CHECKER_ADDR</code>: TBD</li> <li><code>PURITY_CHECKER_CODE</code>: see below</li> <li><code>NULL_SENDER</code>: <code>2**160 - 1</code></li> <li><code>NEW_BLOCK_REWARD</code>: 6e17 wei (0.6 ETH)</li> <li><code>REWARD_STEPDOWN_BLOCK_COUNT</code>: 5.5e5 blocks (~3 months)</li> <li><code>CASPER_INIT_DATA</code>: TBD</li> <li><code>VOTE_BYTES</code>: <code>0xe9dc0614</code></li> <li><code>INITIALIZE_EPOCH_BYTES</code>: <code>0x5dcffc17</code></li> <li><code>NON_REVERT_MIN_DEPOSIT</code>: amount in wei configurable by client</li> </ul> <h3 id="casper-contract-parameters">Casper Contract Parameters</h3> <ul> <li><code>EPOCH_LENGTH</code>: 50 blocks</li> <li><code>WARM_UP_PERIOD</code>: 1.8e5 blocks (~1 month)</li> <li><code>WITHDRAWAL_DELAY</code>: 1.5e4 epochs</li> <li><code>DYNASTY_LOGOUT_DELAY</code>: 700 dynasties</li> <li><code>BASE_INTEREST_FACTOR</code>: 7e-3</li> <li><code>BASE_PENALTY_FACTOR</code>: 2e-7</li> <li><code>MIN_DEPOSIT_SIZE</code>: 1.5e21 wei (1500 ETH)</li> </ul> <h2 id="specification">Specification</h2> <h4 id="deploying-casper-contract">Deploying Casper Contract</h4> <p>If <code>block.number == HYBRID_CASPER_FORK_BLKNUM</code>, then when processing the block before processing any transactions:</p> <ul> <li>set the code of <code>MSG_HASHER_ADDR</code> to <code>MSG_HASHER_CODE</code></li> <li>set the code of <code>PURITY_CHECKER_ADDR</code> to <code>PURITY_CHECKER_CODE</code></li> <li>set the code of <code>CASPER_ADDR</code> to <code>CASPER_CODE</code></li> <li>set balance of <code>CASPER_ADDR</code> to <code>CASPER_BALANCE</code></li> </ul> <p>Then execute a <code>CALL</code> with the following parameters before executing any normal block transactions:</p> <ul> <li><code>SENDER</code>: <code>NULL_SENDER</code></li> <li><code>GAS</code>: 3141592</li> <li><code>TO</code>: <code>CASPER_ADDR</code></li> <li><code>VALUE</code>: 0</li> <li><code>NONCE</code>: 0</li> <li><code>GASPRICE</code>: 0</li> <li><code>DATA</code>: <code>CASPER_INIT_DATA</code></li> </ul> <p>This <code>CALL</code> utilizes no gas and does not increment the nonce of <code>NULL_SENDER</code></p> <h4 id="initialize-epochs">Initialize Epochs</h4> <p>If <code>block.number &gt;= (HYBRID_CASPER_FORK_BLKNUM + WARM_UP_PERIOD)</code> and <code>block.number % EPOCH_LENGTH == 0</code>, execute a <code>CALL</code> with the following parameters before executing any normal block transactions:</p> <ul> <li><code>SENDER</code>: <code>NULL_SENDER</code></li> <li><code>GAS</code>: 3141592</li> <li><code>TO</code>: <code>CASPER_ADDR</code></li> <li><code>VALUE</code>: 0</li> <li><code>NONCE</code>: 0</li> <li><code>GASPRICE</code>: 0</li> <li><code>DATA</code>: <code>INITIALIZE_EPOCH_BYTES</code> followed by the 32-byte encoding of <code>floor(block.number / EPOCH_LENGTH)</code></li> </ul> <p>This <code>CALL</code> utilizes no gas and does not increment the nonce of <code>NULL_SENDER</code></p> <h4 id="casper-votes">Casper Votes</h4> <p>A <code>vote</code> transaction is defined as a transaction with the following parameters:</p> <ul> <li><code>TO</code>: <code>CASPER_ADDR</code></li> <li><code>DATA</code>: Begins with <code>VOTE_BYTES</code></li> </ul> <p>If <code>block.number &gt;= HYBRID_CASPER_FORK_BLKNUM</code>, then:</p> <ul> <li>A valid <code>vote</code> transaction to <code>CASPER_ADDR</code> must satisfy each of the following: <ul> <li>Must have the following signature <code>(CHAIN_ID, 0, 0)</code> (ie. <code>r = s = 0, v = CHAIN_ID</code>)</li> <li>Must have <code>value == nonce == gasprice == 0</code></li> </ul> </li> <li>When producing and validating a block, when handling <code>vote</code> transactions to <code>CASPER_ADDR</code>: <ul> <li>Only include "valid" <code>vote</code> transactions as defined above</li> <li>Place all <code>vote</code> transactions at the end of the block</li> <li>Track cumulative gas used by votes separately from cumulative gas used by normal transactions via <code>vote_gas_used</code></li> <li>Total <code>vote_gas_used</code> of <code>vote</code> transactions cannot exceed the <code>block_gas_limit</code>, independent of gas used by normal block transactions</li> </ul> </li> <li>When applying <code>vote</code> transactions to <code>CASPER_ADDR</code> to vm state: <ul> <li>Set sender to <code>NULL_SENDER</code></li> <li>Count gas of <code>vote</code> toward <code>vote_gas_used</code></li> <li>Do not count gas of <code>vote</code> toward the normal <code>gas_used</code>. For all <code>vote</code> transaction receipts, cumulative gas used is equal to last non-<code>vote</code> transaction receipt</li> <li>Do not increment the nonce of <code>NULL_SENDER</code></li> </ul> </li> <li>All unsuccessful <code>vote</code> transactions to <code>CASPER_ADDR</code> are invalid and must not be included in the block</li> </ul> <h4 id="fork-choice-and-finalization">Fork Choice and Finalization</h4> <p>If <code>block.number &gt;= HYBRID_CASPER_FORK_BLKNUM</code>, the fork choice rule is the logic represented by the following pseudocode. Note that options <code>--casper-fork-choice</code> and <code>--exclude</code> are discussed below in "Client Settings".</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> handle_block</span><span>(</span><span class="z-variable z-parameter z-function">new_block</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> not</span><span> is_new_head</span><span>(</span><span>new_block</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> set_head</span><span>(</span><span>new_block</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-invalid z-illegal"> --</span><span>casper</span><span class="z-keyword">-</span><span>fork</span><span class="z-keyword">-</span><span>choice</span><span class="z-keyword"> is</span><span> on</span><span>:</span></span> <span class="giallo-l"><span> check_and_finalize_new_checkpoint</span><span>(</span><span>new_block</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> is_new_head</span><span>(</span><span class="z-variable z-parameter z-function">new_block</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-invalid z-illegal"> --</span><span>casper</span><span class="z-keyword">-</span><span>fork</span><span class="z-keyword">-</span><span>choice</span><span class="z-keyword"> is</span><span> off</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> old pure PoW chain scoring rule</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> new_block</span><span>.</span><span>total_difficuty</span><span class="z-keyword"> &gt;</span><span> current_head</span><span>.</span><span>total_difficulty</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> new_block</span><span class="z-keyword"> is</span><span class="z-keyword"> in</span><span class="z-invalid z-illegal"> --</span><span>exclude</span><span class="z-support"> list</span><span class="z-keyword"> or</span><span> one</span><span> of</span><span> its</span><span> descendants</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> don&#39;t revert finalized blocks</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> db</span><span>.</span><span>last_finalized_block</span><span class="z-keyword"> is</span><span class="z-keyword"> not</span><span class="z-keyword"> in</span><span> new_block</span><span>.</span><span>ancestors</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> new casper chain scoring rule</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> highest_justified_epoch</span><span>(</span><span>new_block</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 10</span><span class="z-keyword">**</span><span class="z-constant">40</span><span class="z-keyword"> +</span><span> new_block</span><span>.</span><span>total_difficuty</span><span class="z-keyword"> &gt;</span></span> <span class="giallo-l"><span> highest_justified_epoch</span><span>(</span><span>current_head</span><span>)</span><span class="z-keyword"> *</span><span class="z-constant"> 10</span><span class="z-keyword">**</span><span class="z-constant">40</span><span class="z-keyword"> +</span><span> current_head</span><span>.</span><span>total_difficulty</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> highest_justified_epoch</span><span>(</span><span class="z-variable z-parameter z-function">block</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> casper</span><span class="z-keyword"> =</span><span> block</span><span>.</span><span>post_state</span><span>.</span><span>casper_contract</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> casper</span><span>.</span><span>highest_justified_epoch</span><span>(</span><span class="z-constant">NON_REVERT_MIN_DEPOSITS</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> check_and_finalize_new_checkpoint</span><span>(</span><span class="z-variable z-parameter z-function">new_block</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> casper</span><span class="z-keyword"> =</span><span> new_block</span><span>.</span><span>post_state</span><span>.</span><span>casper_contract</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> If no finalized blocks, db.last_finalized_epoch initialized to -1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> finalized_epoch</span><span class="z-keyword"> =</span><span> casper</span><span>.</span><span>highest_finalized_epoch</span><span>(</span><span class="z-constant">NON_REVERT_MIN_DEPOSITS</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> finalized_epoch</span><span class="z-keyword"> &gt;</span><span> db</span><span>.</span><span>last_finalized_epoch</span><span>:</span></span> <span class="giallo-l"><span> finalized_hash</span><span class="z-keyword"> =</span><span> casper</span><span>.</span><span>checkpoint_hashes</span><span>(</span><span>finalized_epoch</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> ensure not trivially finalized</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> finalized_hash</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-constant">\x00</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> *</span><span class="z-constant"> 32</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> db</span><span>.</span><span>last_finalized_epoch</span><span class="z-keyword"> =</span><span> finalized_epoch</span></span> <span class="giallo-l"><span> db</span><span>.</span><span>last_finalized_block</span><span class="z-keyword"> =</span><span> finalized_hash</span></span></code></pre> <p>The new chain scoring rule queries the casper contract to find the highest justified epoch that meets the client's minimum deposit requirement (<code>NON_REVERT_MIN_DEPOSITS</code>). The <code>10**40</code> multiplier ensures that the justified epoch takes precedence over block mining difficulty. <code>total_difficulty</code> only serves as a tie breaker if the two blocks in question have an equivalent <code>highest_justified_epoch</code>.</p> <p><em>Note</em>: If the client has no justified checkpoints, the contract returns <code>highest_justified_epoch</code> as <code>0</code> essentially reverting the fork choice rule to pure PoW.</p> <p>When assessing a new block as the chain's head, clients must <em>never revert finalized blocks</em> as seen by the code commented as "don't revert finalized blocks".</p> <p>When a new block is added as the chain's head, clients then check for a new finalized block. This is handled by the <code>check_and_finalized_new_checkpoint(new_block)</code> method above. If the highest finalized epoch in the casper contract is greater than the previous finalized epoch, then the client finalizes the block with the hash <code>casper.checkpoint_hashes(finalized_epoch)</code>, storing this block and the related epoch number in the client database as finalized.</p> <p>Clients only consider checkpoints justified or finalized if deposits were greater than <code>NON_REVERT_MIN_DEPOSIT</code> <em>during the epoch in question</em>. This logic is encapsulated in <code>casper.highest_justified_epoch(NON_REVERT_MIN_DEPOSIT)</code> and <code>casper.highest_finalized_epoch(NON_REVERT_MIN_DEPOSIT)</code>, respectively.</p> <h4 id="block-reward">Block Reward</h4> <p>If <code>block.number &gt;= HYBRID_CASPER_FORK_BLKNUM</code>, then <code>block_reward</code> is defined by the following logic and utilizes the same formulas for ommer rewards but with the updated <code>block_reward</code>.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">if</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> &lt;</span><span class="z-constant"> HYBRID_CASPER_FORK_BLKNUM</span><span class="z-keyword"> +</span><span class="z-constant"> REWARD_STEPDOWN_BLOCK_COUNT</span><span>:</span></span> <span class="giallo-l"><span> block_reward</span><span class="z-keyword"> =</span><span class="z-constant"> 5</span><span class="z-keyword"> *</span><span class="z-constant"> NEW_BLOCK_REWARD</span></span> <span class="giallo-l"><span class="z-keyword">elif</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> &lt;</span><span class="z-constant"> HYBRID_CASPER_FORK_BLKNUM</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span class="z-keyword">*</span><span class="z-constant">REWARD_STEPDOWN_BLOCK_COUNT</span><span>:</span></span> <span class="giallo-l"><span> block_reward</span><span class="z-keyword"> =</span><span class="z-constant"> 4</span><span class="z-keyword"> *</span><span class="z-constant"> NEW_BLOCK_REWARD</span></span> <span class="giallo-l"><span class="z-keyword">elif</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> &lt;</span><span class="z-constant"> HYBRID_CASPER_FORK_BLKNUM</span><span class="z-keyword"> +</span><span class="z-constant"> 3</span><span class="z-keyword">*</span><span class="z-constant">REWARD_STEPDOWN_BLOCK_COUNT</span><span>:</span></span> <span class="giallo-l"><span> block_reward</span><span class="z-keyword"> =</span><span class="z-constant"> 3</span><span class="z-keyword"> *</span><span class="z-constant"> NEW_BLOCK_REWARD</span></span> <span class="giallo-l"><span class="z-keyword">elif</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> &lt;</span><span class="z-constant"> HYBRID_CASPER_FORK_BLKNUM</span><span class="z-keyword"> +</span><span class="z-constant"> 4</span><span class="z-keyword">*</span><span class="z-constant">REWARD_STEPDOWN_BLOCK_COUNT</span><span>:</span></span> <span class="giallo-l"><span> block_reward</span><span class="z-keyword"> =</span><span class="z-constant"> 2</span><span class="z-keyword"> *</span><span class="z-constant"> NEW_BLOCK_REWARD</span></span> <span class="giallo-l"><span class="z-keyword">else</span><span>:</span></span> <span class="giallo-l"><span> block_reward</span><span class="z-keyword"> =</span><span class="z-constant"> NEW_BLOCK_REWARD</span></span></code></pre><h4 id="validators">Validators</h4> <p>The mechanics and responsibilities of validators are not specified in this EIP because they rely upon network transactions to the contract at <code>CASPER_ADDR</code> rather than on protocol level implementation and changes. See the <a rel="external" href="https://github.com/ethereum/casper/blob/master/VALIDATOR_GUIDE.md">Validator Implementation Guide</a> for validator details.</p> <h4 id="msg-hasher-code">MSG_HASHER_CODE</h4> <p>The source code for <code>MSG_HASHER_CODE</code> is located <a rel="external" href="https://github.com/ethereum/casper/blob/master/casper/contracts/msg_hash.se.py">here</a>. The source is to be migrated to Vyper LLL before the bytecode is finalized for this EIP.</p> <p>The EVM init code is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>TBD</span></span></code></pre> <p>The EVM bytecode that the contract should be set to is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>TBD</span></span></code></pre><h4 id="purity-checker-code">PURITY_CHECKER_CODE</h4> <p>The source code for <code>PURITY_CHECKER_CODE</code> is located <a rel="external" href="https://github.com/ethereum/research/blob/master/impurity/check_for_impurity.se">here</a>. The source is to be migrated to Vyper LLL before the bytecode is finalized for this EIP.</p> <p>The EVM init code is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>TBD</span></span></code></pre> <p>The EVM bytecode that the contract should be set to is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>TBD</span></span></code></pre><h4 id="casper-code">CASPER_CODE</h4> <p>The source code for <code>CASPER_CODE</code> is located at <a rel="external" href="https://github.com/ethereum/casper/blob/master/casper/contracts/simple_casper.v.py">here</a>. The contract is to be formally verified and further tested before the bytecode is finalized for this EIP.</p> <p>The EVM init code with the above specified params is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>TBD</span></span></code></pre> <p>The EVM bytecode that the contract should be set to is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>TBD</span></span></code></pre><h4 id="client-settings">Client Settings</h4> <p>Clients should be implemented with the following configurable settings:</p> <h5 id="enable-casper-fork-choice">Enable Casper Fork Choice</h5> <p>The ability to enable/disable the Casper Fork Choice. A suggested implementation is <code>--casper-fork-choice</code>.</p> <p>This setting should ship as default disabled in client versions during the initial casper fork. This setting should ship as default enabled in subsequent client versions.</p> <h5 id="non-revert-min-deposit">NON_REVERT_MIN_DEPOSIT</h5> <p>The minimum size of total deposits that the client must observe in the FFG contract for the state of the contract to affect the client's fork choice. A suggested implementation is <code>--non-revert-min-deposit WEI_VALUE</code>.</p> <p>The suggested default value that clients should ship with is at least 2e23 wei (200K ETH).</p> <p>See "Fork Choice" more details.</p> <h5 id="exclusion">Exclusion</h5> <p>The ability to exclude a specified blockhash and all of its descendants from a client's fork choice. A suggested implementation is <code>--exclude BLOCKHASHES</code>, where <code>BLOCK_HASHES</code> is a comma delimited list of blockhashes to exclude.</p> <p>Note: this <em>can</em> by design override a client's forkchoice and revert finalized blocks.</p> <h5 id="join-fork">Join Fork</h5> <p>The ability to manually join a fork specified by a blockhash. A suggested implementation is <code>--join-fork BLOCKHASH</code> where the client automatically sets the head to the block defined by<code>BLOCKHASH</code> and locally finalizes it.</p> <p>Note: this <em>can</em> by design override a client's forkchoice and revert finalized blocks.</p> <h5 id="monitor-votes">Monitor Votes</h5> <p>The ability to monitor incoming <code>vote</code> transactions for slashing conditions and submit proof to the casper contract for a finder's fee if found. A suggested implementation is <code>--monitor-votes</code>.</p> <p>The setting should default to disabled.</p> <p>The following pseudocode defines when two <code>vote</code> messages violate a slashing condition. A <code>vote</code> message is the singular argument included in a <code>vote</code> transaction.</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> decode_rlp_list</span><span>(</span><span class="z-variable z-parameter z-function">vote_msg</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> #</span><span class="z-comment"> [validator_index, target_hash, target_epoch, source_epoch, signature]</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> RLPList</span><span>(</span><span>vote_msg</span><span>,</span><span> [</span><span class="z-support">int</span><span>,</span><span class="z-support"> bytes</span><span>,</span><span class="z-support"> int</span><span>,</span><span class="z-support"> int</span><span>,</span><span class="z-support"> bytes</span><span>]</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> same_target_epoch</span><span>(</span><span class="z-variable z-parameter z-function">vote_msg_1</span><span>,</span><span class="z-variable z-parameter z-function"> vote_msg_2</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> decoded_values_1</span><span class="z-keyword"> =</span><span> decode_rlp_msg</span><span>(</span><span>vote_msg_1</span><span>)</span></span> <span class="giallo-l"><span> target_epoch_1</span><span class="z-keyword"> =</span><span> decoded_values_1</span><span>[</span><span class="z-constant">2</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> decoded_values_2</span><span class="z-keyword"> =</span><span> decode_rlp_msg</span><span>(</span><span>vote_msg_2</span><span>)</span></span> <span class="giallo-l"><span> target_epoch_2</span><span class="z-keyword"> =</span><span> decoded_values_2</span><span>[</span><span class="z-constant">2</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> target_epoch_1</span><span class="z-keyword"> ==</span><span> target_epoch_2</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> surrounds</span><span>(</span><span class="z-variable z-parameter z-function">vote_msg_1</span><span>,</span><span class="z-variable z-parameter z-function"> vote_msg_2</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> decoded_values_1</span><span class="z-keyword"> =</span><span> decode_rlp_msg</span><span>(</span><span>vote_msg_1</span><span>)</span></span> <span class="giallo-l"><span> target_epoch_1</span><span class="z-keyword"> =</span><span> decoded_values_1</span><span>[</span><span class="z-constant">2</span><span>]</span></span> <span class="giallo-l"><span> source_epoch_1</span><span class="z-keyword"> =</span><span> decoded_values_1</span><span>[</span><span class="z-constant">3</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> decoded_values_2</span><span class="z-keyword"> =</span><span> decode_rlp_msg</span><span>(</span><span>vote_msg_2</span><span>)</span></span> <span class="giallo-l"><span> target_epoch_2</span><span class="z-keyword"> =</span><span> decoded_values_2</span><span>[</span><span class="z-constant">2</span><span>]</span></span> <span class="giallo-l"><span> source_epoch_1</span><span class="z-keyword"> =</span><span> decoded_values_1</span><span>[</span><span class="z-constant">3</span><span>]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> vote_1_surrounds_vote_2</span><span class="z-keyword"> =</span><span> target_epoch_1</span><span class="z-keyword"> &gt;</span><span> target_epoch_2</span><span class="z-keyword"> and</span><span> source_epoch_1</span><span class="z-keyword"> &lt;</span><span> source_epoch_2</span></span> <span class="giallo-l"><span> vote_2_surrounds_vote_1</span><span class="z-keyword"> =</span><span> target_epoch_2</span><span class="z-keyword"> &gt;</span><span> target_epoch_1</span><span class="z-keyword"> and</span><span> source_epoch_2</span><span class="z-keyword"> &lt;</span><span> source_epoch_1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> vote_1_surrounds_vote_2</span><span class="z-keyword"> or</span><span> vote_2_surrounds_vote_1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> violates_slashing_condition</span><span>(</span><span class="z-variable z-parameter z-function">vote_msg_1</span><span>,</span><span class="z-variable z-parameter z-function"> vote_msg_2</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> same_target_epoch</span><span>(</span><span>vote_msg_1</span><span>,</span><span> vote_msg_2</span><span>)</span><span class="z-keyword"> or</span><span> surrounds</span><span>(</span><span>vote_msg_1</span><span>,</span><span> vote_msg_2</span><span>)</span></span></code></pre> <p>The casper contract also provides a helper method <code>slashable(vote_msg_1, vote_msg_2)</code> to check if two votes violate a slashing condition. Clients should use the above pseudocode in combination with <code>casper.slashable()</code> as a final check when deciding whether to submit a <code>slash</code> to the contract.</p> <p>The <code>--monitor-votes</code> setting is to be used for clients that wish to monitor vote transactions for slashing conditions. If a slashing condition is found, the client creates and sends a transaction to <code>slash</code> on the casper contract. The first transaction to include the slashing condition proof slashes the validator in question and sends a 4% finder's fee to the transaction sender.</p> <h2 id="rationale">Rationale</h2> <p>Naive PoS specifications and implementations have existed since early blockchain days, but most are vulnerable to serious attacks and do not hold up under crypto-economic analysis. Casper FFG solves problems such as "Nothing at Stake" and "Long Range Attacks" through requiring validators to post slashable deposits and through defining economic finality.</p> <h4 id="minimize-consensus-changes">Minimize Consensus Changes</h4> <p>The finality gadget is designed to minimize changes across clients. For this reason, FFG is implemented within the EVM, so that the contract byte code encapsulates most of the complexity of the fork.</p> <p>Most other decisions were made to minimize changes across clients. For example, it would be possible to allow <code>CASPER_ADDR</code> to mint Ether each time it paid rewards (as compared to creating the contract with <code>CASPER_BALANCE</code>), but this would be more invasive and error-prone than relying on existing EVM mechanics.</p> <h4 id="deploying-casper-contract-1">Deploying Casper Contract</h4> <p>The <code>MSG_HASHER_CODE</code> and <code>PURITY_CHECKER_CODE</code> both do not require any initialization so the EVM bytecode can simply be placed at <code>MSG_HASHER_ADDR</code> and <code>PURITY_CHECKER_ADDR</code>. On the other hand, the casper contract <em>does</em> require passing in parameters and initialization of state. This initialization would normally occur by the EVM init code interacting with the CREATE opcode. Due to the nature of this contract being deployed outside of normal block transactions and to a particular address, the EVM init code/CREATE method requires client specific "hacks" to make it work. For simplicity of specifying across clients, the EVM bytecode -- <code>CASPER_CODE</code> -- is placed at <code>CASPER_ADDR</code> followed by an explicit <code>CALL</code> to a one-time <code>init</code> method on the casper contract. <code>init</code> handles all of the logic that a constructor normally would, accepting contract parameters as arguments and setting initial variable values, and can only be run <em>once</em>.</p> <p><code>CASPER_INIT_DATA</code> is composed of the byte signature of the <code>init</code> method of the casper contract concatenated with the 32-byte encodings of the following variables in the following order:</p> <ul> <li><code>EPOCH_LENGTH</code></li> <li><code>WITHDRAWAL_DELAY</code></li> <li><code>DYNASTY_LOGOUT_DELAY</code></li> <li><code>MSG_HASHER_ADDR</code></li> <li><code>PURITY_CHECKER_ADDR</code></li> <li><code>BASE_INTEREST_FACTOR</code></li> <li><code>BASE_PENALTY_FACTOR</code></li> <li><code>MIN_DEPOSIT_SIZE</code></li> </ul> <p>The entirety of this data is provided as a bytestring -- <code>CASPER_INIT_DATA</code> -- to reduce the chance of encoding errors across clients, especially regarding fixed decimal types which are new in vyper and not yet supported by all clients.</p> <h4 id="casper-contract-params">Casper Contract Params</h4> <p><code>EPOCH_LENGTH</code> is set to 50 blocks as a balance between time to finality and message overhead.</p> <p><code>WARM_UP_PERIOD</code> is set to 1.8e5 blocks to provide validators with an approximate 1 month period to make initial deposits before full contract functionality and voting begin. This helps prevent degenerate cases such as having very few or even just one validator in the initial dynasty. This 1 month period also gives the network time to observe on the order of how many validators will initially be participating in consensus. If for some reason there is an unexpectedly low turnout, the community might choose to delay validation and consider design alternatives.</p> <p><code>WITHDRAWAL_DELAY</code> is set to 15000 epochs to freeze a validator's funds for approximately 4 months after logout. This allows for at least a 4 month window to identify and slash a validator for attempting to finalize two conflicting checkpoints. This also defines the window of time with which a client must log on to sync the network due to weak subjectivity.</p> <p><code>DYNASTY_LOGOUT_DELAY</code> is set to 700 dynasties to prevent immediate logout in the event of an attack from being a viable strategy.</p> <p><code>BASE_INTEREST_FACTOR</code> is set to 7e-3 such that if there are ~10M ETH in total deposits, then validators earn approximately 5% per year in ETH rewards under optimal FFG conditions.</p> <p><code>BASE_PENALTY_FACTOR</code> is set to 2e-7 such that if 50% of deposits go offline, then offline validators lose half of their deposits in approximately 3 weeks, at which the online portion of validators becomes a 2/3 majority and can begin finalizing checkpoints again.</p> <p><code>MIN_DEPOSIT_SIZE</code> is set to 1500 ETH to form a natural upper bound on the total number of validators, bounding the overhead due to <code>vote</code> messages. Using formulas found <a rel="external" href="https://medium.com/@VitalikButerin/parametrizing-casper-the-decentralization-finality-time-overhead-tradeoff-3f2011672735">here</a> under "From validator count to minimum staking ETH", we estimate that with 1500 ETH minimum deposit at an assumed ~10M in total deposits there will be approximately 900 validators at any given time. <code>vote</code>s are only sent after the first quarter of an epoch so 900 votes have to fit into 37 blocks or ~24 <code>vote</code>s per block. We have experimented with more dynamic models for <code>MIN_DEPOSIT_SIZE</code>, but these tend to introduce significant complexities and without data from a live network seem to be premature optimizations.</p> <h4 id="initialize-epochs-1">Initialize Epochs</h4> <p>The call to the method at <code>INITIALIZE_EPOCH_BYTES</code> at <code>CASPER_ADDR</code> at the start of each epoch is a call to the <code>initialize_epoch</code> method in the casper contract. This method can only be called once per epoch and is guaranteed by the protocol to be called at the start block of each epoch by <code>NULL_SENDER</code>. This method performs a number of bookkeeping tasks around incrementing variables, updating rewards, etc.</p> <p>Any call to this method fails prior to the end of the <code>WARM_UP_PERIOD</code>. Thus the protocol does not begin executing <code>initialize_epoch</code> calls until <code>block.number &gt;= HYBRID_CASPER_FORK_BLKNUM + WARM_UP_PERIOD</code>.</p> <h4 id="issuance">Issuance</h4> <p>A fixed amount of 1.25M ETH was chosen as <code>CASPER_BALANCE</code> to fund the casper contract. This gives the contract enough runway to operate for approximately 2 years (assuming ~10M ETH in validator deposits). Acting similarly to the "difficulty bomb", this "funding crunch" forces the network to hardfork in the relative near future to further fund the contract. This future hardfork is an opportunity to upgrade the contract and transition to full PoS.</p> <p>The PoW block reward is reduced from 3.0 to 0.6 ETH/block over the course of approximately one year because the security of the chain is greatly shifted from PoW difficulty to PoS finality and because rewards are now issued to both validators and miners. Rewards are stepped down by 0.6 ETH/block every 3 months (<code>REWARD_STEPDOWN_BLOCK_COUNT</code>) to provide for a conservative transition period from full PoW to hybrid PoS/PoW. This gives validators time to become familiar with the new technology and begin logging on and also provides the network with more leeway in case of any unforeseen issues. If any major issues do arise, the Ethereum network will still have substantial PoW security to rely upon while decisions are made and/or patches are deployed. See <a rel="external" href="https://gist.github.com/djrtwo/bc864c0d0a275170183803814b207b9a">here</a> for further analysis of the current PoW security and of the effect of PoW block reward reduction in the context of Hybrid Casper FFG.</p> <p>In addition to block rewards, miners now receive an issuance reward for including successful <code>vote</code> transactions into the block on time. This reward is equal to 1/8th that of the reward the validator receives for a successful <code>vote</code> transaction. Under optimal FFG conditions after group validator reward adjustments are made, miners receive approximately 1/5th of the total ETH issued by the Casper contract.</p> <p>Below is a table of deposit sizes with associated annual interest rate and approximate time until funding crunch:</p> <table><thead><tr><th>Deposit Size</th><th>Annual Validator Interest</th><th>Funding Crunch</th></tr></thead><tbody> <tr><td>2.5M ETH</td><td>10.12%</td><td>~4 years</td></tr> <tr><td>10M ETH</td><td>5.00%</td><td>~2 years</td></tr> <tr><td>20M ETH</td><td>3.52%</td><td>~1.4 years</td></tr> <tr><td>40M ETH</td><td>2.48%</td><td>~1 year</td></tr> </tbody></table> <h4 id="gas-changes">Gas Changes</h4> <p>Normal block transactions cannot affect casper <code>vote</code> validation results, but casper <code>vote</code> validation results can affect normal block transaction execution. Due to this asymmetrical relationship, <code>vote</code> transactions can be processed in parallel with normal block transactions if <code>vote</code> transactions are placed after all normal block transactions. Because <code>vote</code> transactions can be processed in parallel to normal block transactions, <code>vote</code> transactions cost 0 gas for validators, ensuring that validators can submit votes even in highly congested or high gas-price periods.</p> <p><code>vote_gas_used</code> is introduced to ensure that <code>vote</code> transactions do not put an undue burden on block processing. The additional overhead from <code>vote</code> transactions is capped at the same limit as normal block transactions so that, when run in parallel, neither sets of transactions exceed the overhead defined by the <code>block_gas_limit</code>.</p> <p>The call to <code>initialize_epoch</code> at the beginning of each epoch requires 0 gas so that this protocol state transition does not take any gas allowance away from normal transactions.</p> <h4 id="null-sender-and-account-abstraction">NULL_SENDER and Account Abstraction</h4> <p>This EIP implements a limited version of account abstraction for validators' <code>vote</code> transactions. The general design was borrowed from <a href="https://wg-eips.ritovision.com/86/">EIP-86</a>. Rather than relying upon native transaction signatures, each validator specifies a signature contract when sending their <code>deposit</code> to <code>CASPER_ADDR</code>. When casting a <code>vote</code>, the validator bundles and signs the parameters of their <code>vote</code> according to the requirements of their signature contract. The <code>vote</code> method of the casper contract checks the signature of the parameters against the validator's signature contract, exiting the transaction as unsuccessful if the signature is not successfully verified.</p> <p>This allows validators to customize their own signing scheme for votes. Use cases include:</p> <ul> <li>quantum-secure signature schemes</li> <li>multisig wallets</li> <li>threshold schemes</li> </ul> <p>For more details on validator account abstraction, see the <a rel="external" href="https://github.com/ethereum/casper/blob/master/VALIDATOR_GUIDE.md">Validator Implementation Guide</a>.</p> <h4 id="client-settings-1">Client Settings</h4> <h5 id="enable-casper-fork-choice-1">Enable Casper Fork Choice</h5> <p>Releasing client versions with the casper fork choice as initially default disabled allows for a more conservative transition to hybrid Casper FFG. Under normal operating conditions there are no disparities between the PoW fork choice and the hybrid Casper FFG fork choice. The two fork choice rules can only diverge if either 51% of miners or 51% of validators are faulty.</p> <p>Validators will begin to log on, vote, and finalize the FFG contract before the majority of the network begins explicitly relying upon the new finality mechanism. Once a significant number of validators have logged on and the finality mechanism has been tested on the live network, new client software versions that change the default to enabled will be released.</p> <h5 id="non-revert-min-deposit-1">NON_REVERT_MIN_DEPOSIT</h5> <p><code>NON_REVERT_MIN_DEPOSIT</code> is defined and configurable locally by each client. Clients are in charge of deciding upon the minimum deposits (security) at which they will accept the chain as finalized. In the general case, differing values in the choice of this local constant will not create any fork inconsistencies because clients with very strict finalization requirements will revert to follow the longest PoW chain.</p> <p>Arguments have been made to hardcode a value into clients or the contract, but we cannot reasonably define security required for all clients especially in the context of massive fluctuations in the value of ETH.</p> <h5 id="exclusion-1">Exclusion</h5> <p>This setting is useful in coordinating minority forks in cases of majority collusion.</p> <h5 id="join-fork-1">Join Fork</h5> <p>This setting is to be used by new clients that are syncing the network for the first time. Due to weak subjectivity, a blockhash should be supplied to successfully sync the network when initially starting a node.</p> <p>This setting is also useful for coordinating minority forks in cases of majority collusion.</p> <h5 id="monitor-votes-1">Monitor Votes</h5> <p>Monitoring the network for slashing conditions is key to Casper FFG's "accountable safety" as submitting proof of nefarious activity burns a validator's deposit.</p> <p>This setting is suggested default disabled because the block producer will almost certainly frontrun anyone else submitting a <code>slash</code> transaction. To prevent every client on the network from submitting a <code>slash</code> transaction in the event of a slashing condition, this setting should only be enabled by block producers and those clients who explicitly choose to monitor votes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is not forward compatible and introduces backwards incompatibilities in the state, fork choice rule, block reward, transaction validity, and gas calculations on certain transactions. Therefore, all changes should be included in a scheduled hardfork at <code>HYBRID_CASPER_FORK_BLKNUM</code>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-04-20T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Van de Sandeavsa@ethereum.org https://wg-eips.ritovision.com/1015/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP changes the block reward step by instead of setting it to be hard coded on the clients and to be given to the miner/validator etherbase, it should instead go to an address decided by an on-chain contract, with hard limits on how it would be issued (six month lock-in; issuance can only decrease or be maintained, but not increase;). A decision method is suggested but not essential to the notion of this EIP. This would <strong>not be a generic governance solution</strong>, which is a much broader and harder topic, would <strong>not</strong> affect technical upgrade decisions or other hard forks, but seen as <em>a forum to attempt to prevent contentious hard forks</em> that can be solved with the issuance.</p> <h2 id="summary">Summary</h2> <h3 id="thesis-many-controversial-issues-boil-down-to-resources">Thesis: many controversial issues boil down to resources</h3> <p>These are current EIPs that are being developed or debated. They might seem unrelated but they have something in common, that they can be resolved by proper channel of funds.</p> <h4 id="casper-and-pos">Casper and PoS</h4> <p>Moving to PoS has been on the roadmap since day 0 for ethereum, along with a reduction in issuance to a cost equivalent to the Validator's cost of security (considered to be more efficient than PoW). But the exact issuance necessary for PoS has yet to be determined and is currently being researched. Casper validation will be an on chain contract and therefore it will need to be funded. It's unlikely that a definitive final answer on how much issuance is needed for validation will be reached in the next years as new research will uncover new arguments, so it would make sense to allow some flexibility on this matter</p> <h4 id="issuance-cap-at-120-million">Issuance Cap at 120 Million</h4> <p><a rel="external" href="https://github.com/ethereum/EIPs/issues/960">EIP-960</a>, Vitalik's not so jokey april's fool has been taken seriously. It proposes the issuance to be slowly reduced until it reaches 120 million ether. One of the main counterpoints by Vlad can be simplified by <a rel="external" href="https://medium.com/@Vlad_Zamfir/against-vitaliks-fixed-supply-eip-eip-960-18e182a7e5bd">we don't know enough to know what that ether can be used for</a> and Vitalik's counterpoint is that <a rel="external" href="https://medium.com/@VitalikButerin/to-be-clear-im-not-necessarily-wedded-to-a-finite-supply-cap-a7aa48ab880c">reducing emissions can be a way to reduce future abuse of these funds by finding a schelling point at 0</a>. Issuance has already been reduced once, from 5 ether to the current 3 ether per block. The main point of a hard cap is that a lot of people consider <em>not issuing</em> as having a positive contribution, that can outweigh other actions. Burning ether is also a valid issuance decision.</p> <h4 id="asics-and-advantages-of-pow">Asics and advantages of PoW</h4> <p><a rel="external" href="https://eips.ethereum.org/EIPS/eip-969">EIP-960</a> proposes a change in algorithm to avoid mining being dominated by ASICS. Counter arguments by Phil Daian argue among others than <a rel="external" href="https://pdaian.com/blog/anti-asic-forks-considered-harmful/">resisting economies of scale is futile and there might be specific security advantages to specialized hardware</a>. One of the main arguments for PoW mining, even when it doesn't provide security, it is useful as a fair distribution mechanism, that <strong>PoW allows any person with a computer, internet access and electricity to obtain currency without having to deal with government imposed currency controls</strong>.</p> <h4 id="recovery-forks">Recovery Forks</h4> <p>After the Parity Multisig library self destruction, three different strategies have been attempted to recover the funds: <a rel="external" href="https://gist.github.com/5chdn/a9bb8617cc8523a030126a3d1c60baf3">a general protocol improvement to allow reviving self destructed contracts</a> (which was considered dangerous), a <a rel="external" href="https://github.com/ethereum/EIPs/pull/867">general process to recover funds</a> and a <a href="https://wg-eips.ritovision.com/999/">specific recovery of the multisig library</a>. The latter two are finding a lot of resistance from the community, but it's unlikely that these issues are going away soon. The affected parties have a large incentive (fluctuating at almost half a billion dollars) to keep trying, and it's an issue that is likely to occur again in the future. If they get reimbursed, <a rel="external" href="https://github.com/ethereum/EIPs/issues/156">there are many other special cases of ether provably burnt or stuck</a> that might deserve the same treatment. If they get shut down, they have an incentive to move forward a fork implementation: even if they are a minority chain, it's likely they'll recover an amount larger than 0, which is what they would otherwise, and it means the main ethereum community might lose a valuable team of developers.</p> <h4 id="other-public-goods">Other Public Goods</h4> <p>There are many other types of public goods that could be funded by issuance. By <em>Public Good</em>, I'm using a strict definition of something that brings value to everyone, both those who funded it and free-loaders, making it hard to fund it exclusively by traditional private incentives. They can be research, whole network security, <a href="https://wg-eips.ritovision.com/908/">incentivize full clients and networking</a>, fair distribution of tokens etc.</p> <h2 id="proposed-solution">Proposed Solution</h2> <h3 id="issuance-contract">Issuance Contract</h3> <p>This EIP proposes a future hard fork where block reward is not issued to miners/validators etherbase, but instead to a single contract, that then will activate the default function (with a fixed amount of gas) and then it will forward the ether to other contracts which will finally distribute to their final destinations.</p> <h4 id="limits-on-the-contract">Limits on the contract</h4> <h5 id="it-can-only-deal-with-issuance">It can only deal with issuance</h5> <p>It's not meant to be a general governance contract. The contract <strong>should NOT be used</strong> to decide software updates, to freeze funds, change contract balances or anything on the consensus layer other than the strict definition of <em>where block rewards go</em>. It should be seen as a platform to settle disputes to avoid the implementation of contentious hard forks, not as a mean to remove the power of users and developers to execute them.</p> <h5 id="it-cannot-only-decrease-issuance-and-once-decreased-it-cannot-be-increased-again">It cannot only decrease issuance, and once decreased it cannot be increased again</h5> <p>In order to reduce future abuse and uncertainty, <strong>once issuance is reduced, it cannot be increased</strong>. To prevent a single action reducing it to 0, the reduction is limited up to a percentage per time, so if the <strong>decision assembly</strong> is aggressively to reduce issuance to zero, it would take a known number of years.</p> <h5 id="results-are-locked-for-s">Results are locked for s</h5> <p>Whenever a new decision on either reducing the issuance or changing the target is made, the effects will have a six-month delay to it. Once a decision is made it is final, it will take place six months after that, but if it's shortly reversed, then that change will be short lived. The rationale behind is that it allows time to anyone disagreeing with the decision to:</p> <ul> <li>Sell their coins so that if a bad actor takes over they will have a reduced reward</li> <li>Attempt to revert the decision as soon as possible, to reduce the duration that the change will take place</li> <li>Organize to create counter measures against the decision</li> <li>Implement a hard fork changing the decision contract or to remove the issuance contract altogether, as a last resort measure</li> </ul> <h5 id="interface">Interface</h5> <p>It would have the following interface:</p> <p><code>function targetContract() returns (address)</code></p> <p>There's a single target contract that should ether issued to. At each new block, that contract would have the default function called so it would forward to the intended addresses.</p> <p><code>function decisionAssembly() returns (address)</code></p> <p>A contract that would represent the internal governance of decisions. More on this later.</p> <p><code>function reduceIssuance(uint)</code></p> <p>Can only be called by <strong>decision assembly</strong>. The contract is allowed to reduce or maintain the issuance per block. <strong>Change is not executed immediately, effects only happen six months later, but once a decision is committed it is irrevocable</strong>.</p> <p><code>function changeTargetContract(address)</code></p> <p>Can only be called by <strong>decision assembly</strong>. It changes the contract that will receive the funds in the future. Only one contract can be appointed, but if the community desires to split issuance or even burn a part of it (in a non-irrevocable manner) it can be done in that contract. Change is not executed immediately, <strong>effects only happen six months later</strong>, but once a decision is committed it is certain, even if it's later reverted: if a new target contract is changed after a few hours, then it still means that in six month's time, it would issue for that contract for a few hours.</p> <p><code>function executeDecision(uint)</code></p> <p>Can be called by anyone: it executes a change to issuance amount or target that had been scheduled six months prior.</p> <h5 id="decision-assembly">Decision Assembly</h5> <p>A contract that has the power to decide the changes to issuance, the core of the governance of these decisions. The exact format of this governance is open to debate, but what follows is a suggestion:</p> <p>The decision would be made by multiple signalling contracts, each one implemented by separate groups and representing one aspect of the community or one sort of measurement. Each signaling process would have a <code>int</code> bound in which they could vote and they would have their own internal process to decide that. As new governance methods are tested and debated, new signalling contracts should be added and removed. Suggested signalling contracts:</p> <ul> <li>Futarchy and prediction markets based on multiple measures</li> <li>Votes weighted by ether balance (optionally with multipliers if the voters were committed to locking votes)</li> <li>Token votes, weighted by their own relative ether exchange rate</li> <li>Votes by individual humans if a good sybil resistance, coercion mechanism is developed</li> <li>Block-signalling, as a way to measure validators/miners choices</li> <li>Some sort of signalling representing developers, exchanges or other stakeholders</li> <li>Any other proposed manner</li> </ul> <p>Since adding and removing signalling contracts, as well as changing their total weight would be controlled by the contract itself, it would be crucial that the first signalling contracts were a diverse set of interests, and that they were open to adding more signals as new governance is experimented as well as removing signals that stop representing the community.</p> <h3 id="questions-to-be-debated">Questions to be debated</h3> <p>A lot of things are suggested in this EIP, so I would like to propose these questions to be debated:</p> <ol> <li>Do we want to have dynamically changing block rewards, instead of having them be hard coded in the protocol?</li> <li>If the answer above is yes, then what would be the best governance process to decide it, and what sorts of limits would we want that governance contract to have?</li> <li>If the answer is a multi-signalling contract, then what sorts of signals would we want, what sort of relative weight should they have and what would be the process to add and remove them?</li> </ol> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-04-18T00:00:00+00:00 2026-02-11T14:49:27+00:00 Anderson Wesleyhttps://github.com/andywesley https://wg-eips.ritovision.com/1010/ <h2 id="simple-summary">Simple Summary</h2> <p>This document proposes to improve the uniformity of ether distribution between wallet address <code>0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B</code> and wallet address <code>0x15E55EF43efA8348dDaeAa455F16C43B64917e3c</code> which are currently experiencing a significant non-uniformity.</p> <h2 id="abstract">Abstract</h2> <p>As of the date of this EIP, the difference in balance between address <code>0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B</code> and address <code>0x15E55EF43efA8348dDaeAa455F16C43B64917e3c</code> is far from equitable or uniform, with the former having more than 365,000 ether more than the latter. The distribution of ether between these two addresses must be improved in order to protect the Ethereum economy from centralized control. This will be accomplished by transferring 100,000 ether from the former address to the latter. This is a properly motivated improvement in keeping with the core Ethereum philosophy of decentralization.</p> <h2 id="motivation">Motivation</h2> <p>This proposal is necessary because the Ethereum protocol does not allow the owner of an address which does not own an equitable amount of ether to claim their share of ether from an address which owns a dangerously centralized quantity. Rather than proposing an overly complicated generic mechanism for any user to claim ether to which they believe they are equitably entitled, this proposal will take the simple route of a one-time transfer of 100,000 ether from <code>0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B</code> to <code>0x15E55EF43efA8348dDaeAa455F16C43B64917e3c</code>. This avoids duplicating the effort of other proposals and provides a net improvement to the Ethereum project and community.</p> <h2 id="specification">Specification</h2> <p>The balance of <code>0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B</code> will be decreased by 100,000 ether. The balance of <code>0x15E55EF43efA8348dDaeAa455F16C43B64917e3c</code> will be increased by 100,000 ether. No net change in the amount of extant ether will occur unless at the time of implementation the former address does not contain sufficient ether for such a deduction.</p> <h2 id="rationale">Rationale</h2> <p>The value 100,000 was chosen after careful technically sound analysis of various economic theories developed over the past century. In spite of the fact that it is a convenient round number, it is actually the exact output of a complex statistical process iterated to determine the optimal distribution of ether between these addresses.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Clients that fail to implement this change will not be aware of the correct balances for these addresses. This will create a hard fork. The implementation of this change consistently among all clients as intended by the proposal process will be sufficient to ensure that backwards compatibility is not a concern.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-04-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 David Stanfilldavid@airsquirrels.com https://wg-eips.ritovision.com/969/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP modifies ethash in order to break ASIC miners specialized for the current ethash mining algorithm.</p> <h2 id="abstract">Abstract</h2> <p>There are companies who currently have dedicated hardware based ethereum miners in production, and may be actively mining. This EIP aims to "poison the well" by modifying the block mining algorithm in a low risk manner that may <em>"break"</em> these miners if they are in-fact built as traditional ASICs.</p> <h2 id="motivation">Motivation</h2> <p>ASIC-based miners will have lower operational costs than GPU-based miners, which will result in GPU-based mining quickly becoming unprofitable. Given that production of ASIC-based miners has a high barrier to entry and few market players, this will cause a trend towards centralization of mining power.</p> <p>Risks include market dominance by a single manufacturer that may utilize production stock to mine themselves, introduce backdoors in their hardware, or facilitate a 51% attack that would otherwise be infeasible.</p> <p>This trend towards centralization has a negative effect on network security, putting significant control of the network in the hands of only a few entities.</p> <p>Ethash remains ASIC-resistant, however ASIC manufacturer technology is advancing and ethash may require further changes in order to remain resistant to unforeseen design techniques. This EIP seeks explicitly to buy time during which newly-developed ASIC technology will face a barrier while more long-term mechanisms to ensure continued ASIC resistance can be explored.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= ASIC_MITIGATION_FORK_BLKNUM</code>, require that the ethash solution sealing the block has been mined using <code>ethashV2</code>.</p> <h2 id="ethashv2">EthashV2</h2> <p><code>ethashV2</code> will be identical in specification to the current <code>ethash</code>(v1) algorithm, with the exception of the implementation of <code>fnv</code>.</p> <p>The new algorithm replaces the 5 current uses of <code>fnv</code> inside <code>hashimoto</code> with 5 separate instances defined as <code>fnvA</code>, <code>fnvB</code>, <code>fnvC</code>, <code>fnvD</code>, and <code>fnvE</code>, utilizing</p> <pre class="giallo z-code"><code data-lang="c"><span class="giallo-l"><span>FNV_PRIME_A</span><span class="z-keyword">=</span><span class="z-keyword">0x</span><span class="z-constant">10001a7</span></span> <span class="giallo-l"><span>FNV_PRIME_B</span><span class="z-keyword">=</span><span class="z-keyword">0x</span><span class="z-constant">10001ab</span></span> <span class="giallo-l"><span>FNV_PRIME_C</span><span class="z-keyword">=</span><span class="z-keyword">0x</span><span class="z-constant">10001cf</span></span> <span class="giallo-l"><span>FNV_PRIME_D</span><span class="z-keyword">=</span><span class="z-keyword">0x</span><span class="z-constant">10001e3</span></span> <span class="giallo-l"><span>FNV_PRIME_E</span><span class="z-keyword">=</span><span class="z-keyword">0x</span><span class="z-constant">10001f9</span></span></code></pre> <p><code>fnvA</code> replaces <code>fnv</code> in the DAG item selection step; <code>fnvB</code> replaces <code>fnv</code> in the DAG item mix step; <code>fnvC(fnvD(fnvE</code> replaces <code>fnv(fnv(fnv(</code> in the compress mix step.</p> <p><code>fnv</code> as utilized in DAG-item creation should remain unchanged.</p> <h2 id="agent-changes-optional-variant">Agent Changes (Optional Variant)</h2> <p>The JSON-RPC <code>eth_GetWork</code> call may optionally return the proposed blocks algorithm. While a miner or pool may infer the requirement for <code>ethashV2</code> based on the computed epoch of the provided seedHash, it is beneficial to explicitly provide this field so a miner does not require special configuration when mining on a chain that chooses not to implement the <code>ASIC_Mitigation</code> hardfork.</p> <p>Due to compatibility concerns with implementations that already add additional parameters to <code>GetWork</code>, it is desired to add <code>BlockNumber</code> as an explicit 4th parameter as suggested in https://github.com/ethereum/go-ethereum/issues/2333. Algorithm should then be returned as either <code>"ethash"</code> or <code>"ethashV2"</code> according to the <code>block.number &gt;= ASIC_MITIGATION_FORK_BLKNUM</code> criteria.</p> <h2 id="rationale">Rationale</h2> <p>This EIP is aimed at breaking existing ASIC-based miners via small changes to the existing ethash algorithm. We hope to accomplish the following:</p> <ol> <li>Break existing ASIC-based miners.</li> <li>Demonstrate a willingness to fork in the event of future ASIC miner production.</li> </ol> <p>Goal #1 is something that we can only do probabilistically without detailed knowledge of existing ASIC miner design. The known released miner is available for purchase <a rel="external" href="https://shop.bitmain.com/product/detail?pid=00020180403174908564M8dMJKtz06B7">here</a>, with delivery slated for mid-summer 2018.</p> <p>Our approach should balance the inherent security risks involved with changing the mining algorithm with the risk that the change we make does not break existing ASIC miners. This EIP leans towards minimizing the security risks by making minimal changes to the algorithm, accepting the risk that the change may not break dedicated hardware miners that utilize partially- or fully-configurable logic.</p> <p>Furthermore, we do not wish to introduce significant algorithm changes that may alter the power utilization or performance profile of existing GPU hardware.</p> <p>The change of FNV constant is a minimal change that can be quickly implemented across the various network node and miner implementations.</p> <p>It is proposed that <code>ASIC_MITIGATION_FORK_BLKNUM</code> be no more than 5550000 (epoch 185), giving around 30 days of notice to node and miner developers and a sufficient window for formal analysis of the changes by experts. We must weigh this window against the risk introduced by allowing ASICs that may exist to continue to propagate on the network, as well as the risk of providing too much advanced warning to ASIC developers.</p> <p>It is further understood that this change will not prevent redesign of existing dedicated hardware with new ASIC chips. The intention of this change is only to disable currently active or mid-production hardware and provide time for POS development as well as larger algorithm changes to be well analyzed by experts.</p> <p>The choice of FNV constants is made based on the formal specification at https://tools.ietf.org/html/draft-eastlake-fnv-14#section-2.1</p> <p>@goobur provided the following python code to output primes matching this criteria:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span>candidates</span><span class="z-keyword"> =</span><span> [</span><span class="z-constant">2</span><span class="z-keyword">**</span><span class="z-constant">24</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">8</span><span class="z-keyword"> +</span><span> _</span><span class="z-keyword"> for</span><span> _</span><span class="z-keyword"> in</span><span class="z-variable"> xrange</span><span>(</span><span class="z-constant">256</span><span>)</span><span>]</span></span> <span class="giallo-l"><span>candidates</span><span class="z-keyword"> =</span><span> [</span><span>_</span><span class="z-keyword"> for</span><span> _</span><span class="z-keyword"> in</span><span> candidates</span><span class="z-keyword"> if</span><span> is_prime</span><span>(</span><span>_</span><span>)</span><span>]</span></span> <span class="giallo-l"><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x</span><span class="z-constant">%x</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> %</span><span> _</span><span class="z-keyword"> for</span><span> _</span><span class="z-keyword"> in</span><span> candidates</span><span class="z-keyword"> if</span><span> _</span><span class="z-keyword"> %</span><span> (</span><span class="z-constant">2</span><span class="z-keyword">**</span><span class="z-constant">40</span><span class="z-keyword"> -</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">24</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>)</span><span class="z-keyword"> &gt;</span><span> (</span><span class="z-constant">2</span><span class="z-keyword">**</span><span class="z-constant">24</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">8</span><span class="z-keyword"> +</span><span class="z-constant"> 2</span><span class="z-keyword">**</span><span class="z-constant">7</span><span>)</span><span>]</span></span></code></pre> <p>The minimal prime constraint was relaxed, as has already been the case in <code>ethashV1</code>.</p> <p>Typical ASIC synthesis tools would optimize multiplication of a constant in the FNV algorithm, while reducing the area needed for the multiplier according to the hamming weight of the constant. To reduce the chance of ASIC adaptation through minor mask changes, we propose choosing new constants with a larger hamming weight, however care should be taken not to choose constants with too large of a weight.</p> <p>The current FNV prime, <code>0x1000193</code>, has a hamming weight of 6.</p> <pre class="giallo z-code"><code data-lang="c"><span class="giallo-l"><span class="z-entity z-name">HammingWeight</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">10001a7</span><span>)</span><span class="z-keyword"> =</span><span class="z-constant"> 7</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">HammingWeight</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">10001ab</span><span>)</span><span class="z-keyword"> =</span><span class="z-constant"> 7</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">HammingWeight</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">10001cf</span><span>)</span><span class="z-keyword"> =</span><span class="z-constant"> 8</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">HammingWeight</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">10001e3</span><span>)</span><span class="z-keyword"> =</span><span class="z-constant"> 7</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">HammingWeight</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">10001ef</span><span>)</span><span class="z-keyword"> =</span><span class="z-constant"> 9</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Not chosen</span></span> <span class="giallo-l"><span class="z-entity z-name">HammingWeight</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">10001f9</span><span>)</span><span class="z-keyword"> =</span><span class="z-constant"> 8</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name">HammingWeight</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">10001fb</span><span>)</span><span class="z-keyword"> =</span><span class="z-constant"> 9</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> Not chosen</span></span></code></pre> <p>An analysis can be done regarding the dispersion of these constants as compared to <code>0x01000193</code>, using the following snippet.</p> <pre class="giallo z-code"><code data-lang="c"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">//</span><span class="z-comment"> https://eips.ethereum.org/EIPS/eip-969</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">include</span><span class="z-punctuation z-definition z-string"> &lt;</span><span class="z-string">stdlib.h</span><span class="z-punctuation z-definition z-string">&gt;</span></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">include</span><span class="z-punctuation z-definition z-string"> &lt;</span><span class="z-string">stdio.h</span><span class="z-punctuation z-definition z-string">&gt;</span></span> <span class="giallo-l"><span class="z-keyword">#</span><span class="z-keyword">include</span><span class="z-punctuation z-definition z-string"> &lt;</span><span class="z-string">string.h</span><span class="z-punctuation z-definition z-string">&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type">int</span><span class="z-entity z-name"> main</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> u_int32_t</span><span> candidate </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> u_int32_t</span><span> dups </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> u_int32_t</span><span> fnv_candidate </span><span class="z-keyword">=</span><span class="z-keyword"> 0x</span><span class="z-constant">10001a7</span><span>;</span><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> MODIFY!</span></span> <span class="giallo-l"><span class="z-support"> u_int8_t</span><span class="z-keyword"> *</span><span>counts </span><span class="z-keyword">=</span><span class="z-entity z-name"> malloc</span><span>(</span><span class="z-keyword">0x</span><span class="z-constant">FFFFFFFF</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> memset</span><span>(</span><span>counts</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-constant">\0</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-keyword"> 0x</span><span class="z-constant">FFFFFFFF</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span>candidate </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> candidate </span><span class="z-keyword">&lt;</span><span class="z-keyword"> 0x</span><span class="z-constant">FFFFFFFF</span><span>;</span><span> candidate</span><span class="z-keyword">++</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> u_int32_t</span><span> result </span><span class="z-keyword">=</span><span> (</span><span class="z-support">u_int32_t</span><span>)</span><span>(</span><span>candidate </span><span class="z-keyword">*</span><span> fnv_candidate</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> u_int8_t</span><span> oldCount </span><span class="z-keyword">=</span><span class="z-variable"> counts</span><span>[</span><span>result</span><span>]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable"> counts</span><span>[</span><span>result</span><span>]</span><span class="z-keyword"> =</span><span class="z-variable"> counts</span><span>[</span><span>result</span><span>]</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>oldCount </span><span class="z-keyword">!=</span><span class="z-constant"> 0</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> dups</span><span class="z-keyword">++</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> ////</span><span class="z-comment"> progress display: remove comment to speed down</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">if ((candidate &amp; 0xFFFFF) == 0xFFFFF) printf(&quot;0x%08x\n&quot;, candidate);</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> printf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant">\n</span><span class="z-string">FNV candidate 0x</span><span class="z-constant">%08x</span><span class="z-string"> : </span><span class="z-constant">%i</span><span class="z-string"> dups</span><span class="z-constant">\n</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span> fnv_candidate</span><span>,</span><span> dups</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>It can be empirically confirmed that no more than 1 duplicate occurs in the 32-bit word space with these constants.</p> <p>It is worth noting that FNV is not a cryptographic hash, and it is not used as such in ethash. That said, a more invasive hash algorithm change could be considered.</p> <p>One suggestion has been <a rel="external" href="https://github.com/aappleby/smhasher/blob/master/src/MurmurHash3.cpp">MurmurHash3</a>.</p> <p><a rel="external" href="https://twitter.com/el33th4xor/status/981292363627810818">Other suggestions have been made</a>: <a rel="external" href="https://github.com/P-H-C/phc-winner-argon2">Argon2</a>, <a rel="external" href="https://blog.z.cash/why-equihash/">Equihash</a> of Zcash fame, and <a rel="external" href="https://crypto.stanford.edu/balloon/">Balloon Hashing</a>.</p> <p>Another possible candidate is <a rel="external" href="https://github.com/tromp/cuckoo">Cuckoo Cycle</a>, although there are some concerns regarding unaddressed optimization vulnerabilities. One review can be found <a rel="external" href="https://da-data.blogspot.com/2014/03/a-public-review-of-cuckoo-cycle.html">here</a>.</p> <p>This may be considered once the exact mechanism of the released ASICs is known and their effectiveness against its optimisations can be fully evaluated.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This change implements a backwards incompatible change to proof of work based block mining. All existing miners will be required to update to clients which implement this new algorithm, and all nodes will require updates to accept solutions from the new proof of work algorithm.</p> <h2 id="test-cases">Test Cases</h2> <p>TODO: will need to generate test cases for <code>ethereum/tests</code> repository corresponding to the consensus changes.</p> <h2 id="implementation">Implementation</h2> <p>TODO</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-03-31T00:00:00+00:00 2026-02-11T14:49:28+00:00 Alexandre Bellingalexandrebelling8@gmail.com https://wg-eips.ritovision.com/1895/ <h2 id="simple-summary">Simple Summary</h2> <p>The EVM currently supports elliptic curves operations for curve <em>alt-bn128</em> thanks to precompiles <code>ecadd</code> and <code>ecmul</code> and <code>ecpairing</code>. The classes MNT4 and 6 contain cycles of curves. Those cycles enable doing operations on one curve inside a SNARK on the other curve (and reversely). This EIP suggests adding support for those curves.</p> <h2 id="abstract">Abstract</h2> <p>Adds supports for the following operations through precompiles:</p> <ul> <li><code>ecadd</code> on MNT4</li> <li><code>ecmul</code> on MNT4</li> <li><code>ecpairing</code> on MNT4</li> </ul> <h2 id="motivation">Motivation</h2> <p>Elliptic curve is the basic block of recursive SNARKs (ie: verifying a SNARK inside a SNARK) and this addresses the issue of scalable zero-knowledge. More generally this addresses partly the scalability issue as SNARKs verification are constant time in the size of the circuit being verified.</p> <p>More concretely, today if the EVM has to deal with 1000s of SNARK verification it would take around 1.5 billion gas and would be impractical for Ethereum. Recursive SNARKs for instance make it possible to aggregate multiple proofs into a single one that can be verified like any other SNARK. It results in a massive cost reduction for the verification.</p> <p>However, this is impossible using <em>alt-bn128</em> and in my knowledge, the only family of pairing-friendly curves known to produce cycles are MNT4 and MNT6. A complete characterization of the cycles existing between those two families is proposed in <a rel="external" href="https://arxiv.org/pdf/1803.02067.pdf">On cycles of pairing-friendly elliptic curves </a></p> <h2 id="specification">Specification</h2> <h3 id="the-curve">The curve</h3> <p>The proposed cycle has been introduced in <a rel="external" href="https://eprint.iacr.org/2014/595.pdf">Scalable Zero Knowledge via Cycles of Elliptic Curves</a>.</p> <h3 id="mnt4-definition">MNT4 definition</h3> <p>The groups <code>G_1</code> and <code>G_2</code> are cyclic groups of prime order :</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>q = 475922286169261325753349249653048451545124878552823515553267735739164647307408490559963137</span></span></code></pre> <p><code>G_1</code> is defined over the field <code>F_p</code> of prime order :</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>p = 475922286169261325753349249653048451545124879242694725395555128576210262817955800483758081</span></span></code></pre> <p>with generator P:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>P = (</span></span> <span class="giallo-l"><span> 60760244141852568949126569781626075788424196370144486719385562369396875346601926534016838,</span></span> <span class="giallo-l"><span> 363732850702582978263902770815145784459747722357071843971107674179038674942891694705904306</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>Both p and q can be written in 298 bits.</p> <p>The group G_1 is defined on the curve defined by the equation <code>Y² = X³ + aX + b</code> where:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> a = 2</span></span> <span class="giallo-l"><span> b = 423894536526684178289416011533888240029318103673896002803341544124054745019340795360841685</span></span></code></pre> <p>The twisted group G_2 is defined over the field <code>F_p^2 = F_p / &lt;&lt;To be completed&gt;&gt;</code></p> <p>The twisted group G_2 is defined on the curve defined by the equation <code>Y² = X² + aX + b</code> where :</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> a = 34 + i * 0</span></span> <span class="giallo-l"><span> b = 0 + i * 67372828414711144619833451280373307321534573815811166723479321465776723059456513877937430</span></span></code></pre> <p>G_2 generator is generated by :</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> P2 = (</span></span> <span class="giallo-l"><span> 438374926219350099854919100077809681842783509163790991847867546339851681564223481322252708 +</span></span> <span class="giallo-l"><span> i * 37620953615500480110935514360923278605464476459712393277679280819942849043649216370485641,</span></span> <span class="giallo-l"><span> 37437409008528968268352521034936931842973546441370663118543015118291998305624025037512482 +</span></span> <span class="giallo-l"><span> i * 424621479598893882672393190337420680597584695892317197646113820787463109735345923009077489</span></span> <span class="giallo-l"><span> )</span></span></code></pre><h3 id="the-operations-and-gas-cost">The operations and gas cost</h3> <p>The following operations and their gas cost would be implemented</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>MNT_X_ADD = &lt;&lt;To be estimated&gt;&gt;</span></span> <span class="giallo-l"><span>MNT_X_MUL = &lt;&lt;To be estimated&gt;&gt;</span></span> <span class="giallo-l"><span>MNT_X_PAIRING = &lt;&lt;To be estimated&gt;&gt;</span></span></code></pre> <p>Where <code>X</code> is either 4.</p> <h3 id="encoding">Encoding</h3> <p>The curves points P(X, Y) over F_p are represented in their compressed form C(X, Y):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> C = X | s</span></span></code></pre> <p>where <code>s</code> represents <code>Y</code> as follow:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> | `s&#39;` | `Y` |</span></span> <span class="giallo-l"><span> |--------|--------------------------|</span></span> <span class="giallo-l"><span> | `0x00` | Point at infinity |</span></span> <span class="giallo-l"><span> | `0x02` | Solution with `y` even |</span></span> <span class="giallo-l"><span> | `0x03` | Solution with `y` odd |</span></span></code></pre> <p>Compression operation from affine coordinate is trivial:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> s = 0x02 | (s &amp; 0x01)</span></span></code></pre> <p>In the EVM the compressed form allows us to represents curve points with 2 uint256 instead of 3.</p> <h3 id="edge-cases">Edge cases</h3> <ul> <li>Several acceptable representations for the point at infinity</li> </ul> <h2 id="rationale">Rationale</h2> <p>The curve has 80 bits of security (whereas MNT6 has 120 bits) which might not be considered enough for critical security level, (for instance transferring several billions), but enough for others. If it turns out this is not enough security for adoption, there is another option : another cycle is being used by Coda but is defined over a 753 bits sized field which might also be prohibitively low (no reference to this curve from Coda's publications found).</p> <p>Independently of the cycle chosen, the groups and field elements are represented with integers larger than 256 bits (even for the 80 bits of security), therefore it might be necessary to also add support for larger field size operations.</p> <p>We currently don't know more efficient pairing-friendly cycles and don't know if there are. It might be possible to circumvent this problem though by relaxing the constraint that all the curves of the cycle must be pairing friendly). If we had a cycle with only one pairing friendly curve we would still be able to compose proofs by alternating between SNARKs and any other general purpose zero-knowledge cryptosystems.</p> <p>Assuming we find a convenient cycle, we don't need to implement support for all the curves it contains, only one. The best choice would be the fastest one as the overall security of the recursive snark do not depends on which curve the verification is made.</p> <p>Proper benchmarks will be done in order to make this choice and to price the operations in gas.</p> <h2 id="test-cases">Test Cases</h2> <h2 id="references">References</h2> <ul> <li><em>Eli-Ben-Sasson, Alessandro Chiesa, Eran Tromer, Madars Virza, [BCTV14], April 28, 2015, Scalable Zero Knowledge via Cycles of Elliptic Curves : https://eprint.iacr.org/2014/595.pdf</em></li> <li><em>Alessandro Chiesa, Lynn Chua, Matthew Weidner, [CCW18], November 5, 2018, On cycles of pairing-friendly elliptic curves : https://arxiv.org/pdf/1803.02067.pdf</em></li> </ul> <h2 id="implementation">Implementation</h2> <ul> <li><a rel="external" href="https://github.com/AlexandreBelling/go-boojum">go-boojum</a> : A PoC demo of an application of recursive SNARKs</li> <li><a rel="external" href="https://github.com/scipr-lab/libff">libff</a> : a C++ library for finite fields and elliptic curves</li> <li><a rel="external" href="https://github.com/CodaProtocol/coda">coda</a> : a new cryptocurrency protocol with a lightweight, constant sized blockchain.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-03-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/1872/ <h2 id="simple-summary">Simple Summary</h2> <p>A proposal to define a limited number of annual time windows in which network upgrades (aka hard forks) should be performed within. Policies for scheduling network upgrades outside these windows are also described.</p> <h2 id="abstract">Abstract</h2> <p>Four different weeks, spaced roughly evenly throughout the year, are targeted for network upgrades to be launched. Regular network upgrades should announce their intention to launch in a particular window early in their process and choose a block number four to six weeks prior to that window. If a network upgrade is cancelled then it would be rescheduled for the next window. Not all windows will be used. Priority upgrades outside the roadmap may be scheduled in the third week of any month, but such use is discouraged. Critical upgrades are scheduled as needed.</p> <h2 id="motivation">Motivation</h2> <p>The aim of this EIP is to provide some level of regularity and predictability to the Ethereum network upgrade/hard fork process. This will allow service providers such as exchanges and node operators a predictable framework to schedule activities around. This also provides a framework to regularize the delivery of network upgrades.</p> <h2 id="specification">Specification</h2> <p>Scheduling is defined for three categories of network upgrades. First are <code>Roadmap</code> network upgrades that include deliberate protocol improvements. Next are <code>Priority</code> network updates, where there are technical reasons that necessitate a prompt protocol change but these reasons do not present a systemic risk to the protocol or the ecosystem. Finally, <code>Critical</code> network upgrades are to address issues that present a systemic risk to the protocol or the ecosystem.</p> <h3 id="roadmap-network-upgrades">Roadmap Network Upgrades</h3> <p>Roadmap network upgrades are network upgrades that are deliberate and measured to improve the protocol and ecosystem. Historical examples are Homestead, Byzantium, and Constantinople.</p> <p>Roadmap network upgrades should be scheduled in one of four windows: the week with the third Wednesday in January, April, July, and October. When initiating a network upgrade or early in the planning process a particular window should be targeted.</p> <blockquote> <p><strong>Note to reviewers:</strong> The months and week chosen are to provide an initial recommendation and are easily modifiable prior to final call. They thread the needle between many third quarter and fourth quarter holidays.</p> </blockquote> <p>Implementors are expected to have software for a Roadmap network upgrade ready two to four weeks prior to the upgrade. Hence a block number for the network upgrade should be chosen four to six weeks prior to the network upgrade window. Scheduling details such as whether this choice is made prior to or after testnet deployment are out of scope of this EIP.</p> <p>Depending on the release cadence of Roadmap network upgrades some windows will not be used. For example if a six month release cadence is chosen a roadmap upgrade would not occur in adjacent upgrade windows. Hence for a six month cadence if a roadmap upgrade occurred in April then the July window would not be used for network upgrades.</p> <p>If a planned roadmap upgrade needs to be rescheduled then strong consideration should be given to rescheduling the upgrade for the next window in three months time. For the case of a six month cadence this may cause releases to be in adjacent release windows. For a three month cadence the next network upgrade would be merged with the current upgrade or the next network upgrade would be delayed.</p> <p>To be compatible with the scheduled release windows the cadence of the Roadmap Network Upgrades should be a multiple of three months. Whether it is three, six, nine, or more month cadence is out of scope of this EIP.</p> <h3 id="priority-network-upgrades">Priority Network Upgrades</h3> <p>Priority network upgrades are reserved for upgrades that require more urgency than a roadmap network upgrade yet do not present a systemic risk to the network or the ecosystem. To date there have been no examples of a priority upgrade. Possible examples may include roadmap upgrades that need to occur in multiple upgrades or for security risks that have a existing mitigation in place that would be better served by a network upgrade. Another possible reason may be to defuse the difficulty bomb due to postponed roadmap upgrades.</p> <p>Priority network upgrades are best launched in unused roadmap launch windows, namely the third week of January, April, July, and October. If necessary they may be launched in the third week of any month, but strong consideration and preference should be given to unused roadmap launch windows.</p> <p>Priority network upgrades should be announced and a block chosen far enough in advance so major clients implementors can release software with the needed block number in a timely fashion. These releases should occur at least a week before the launch window. Hence priority launch windows should be chosen two to four weeks in advance.</p> <h3 id="critical-network-upgrades">Critical Network Upgrades</h3> <p>Critical network upgrades are network upgrades that are designed to address systemic risks to the protocol or to the ecosystem. Historical examples include Dao Fork, Tangerine Whistle, and Spurious Dragon.</p> <p>This EIP provides neither guidance nor restrictions to the development and deployment of these emergency hard forks. These upgrades are typically launched promptly after a solution to the systemic risk is agreed upon between the client implementors.</p> <p>It is recommended that such upgrades perform the minimum amount of changes needed to address the issues that caused the need for the Critical network upgrade and that other changes be integrated into subsequent Priority and Roadmap network upgrades.</p> <h3 id="network-upgrade-block-number-choice">Network Upgrade Block Number Choice</h3> <p>When choosing an activation block the number can be used to communicate the role of a particular network in the Ethereum Ecosystem. Networks that serve as a value store or are otherwise production grade have different stability concerns than networks that serve as technology demonstration or are explicitly designated for testing.</p> <p>To date all Mainnet activation blocks have ended in three or more zeros, including Critical Network Upgrades. Ropsten and Kovan initially started with three zeros but switched to palindromic numbers. Rinkeby has always had palindromic activation blocks. Goerli has yet to perform a network upgrade.</p> <p>To continue this pattern network upgrade activation block numbers for mainnet deployments and production grade networks should chose a number whose base 10 representation ends with three or more zeros.</p> <p>For testnet and testing or development grades network operators are encouraged to choose a block activation number that is a palindrome in base 10.</p> <p>Block numbers for Roadmap and Priority network upgrades should be chosen so that it is forecast to occur relatively close to Wednesday at 12:00 UTC+0 during the launch window. This should result in an actual block production occurring sometime between Monday and Friday of the chosen week.</p> <h2 id="rationale">Rationale</h2> <p>The rationale for defining launch windows is to give business running Ethereum infrastructure a predictable schedule for when upgrades may or may not occur. Knowing when a upgrade is not going to occur gives the businesses a clear time frame within which to perform internal upgrades free from external changes. It also provides a timetable for developers and IT professionals to schedule time off against.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Except for the specific launch windows the previous network upgrades would have complied with these policies. Homestead, Byzantium, and Constantinople would have been Roadmap Network Upgrades. There were no Priority Network Upgrades, although Spurious Dragon would have been a good candidate. Dao Fork was a Critical Network Upgrade in response to TheDao. Tangerine Whistle and Spurious Dragon were critical upgrades in response to the Shanghai Spam Attacks. Constantinople Fix (as it is termed in the reference tests) was in response to the EIP-1283 security issues.</p> <p>If this policy were in place prior to Constantinople then the initial 2018 launch would likely have been bumped to the next window after the Ropsten testnet consensus failures. The EIP-1283 issues likely would have resulted in an out of window upgrade because of the impact of the difficulty bomb.</p> <!-- ## Test Cases --> <!-- no test cases are relevant for this EIP --> <h2 id="implementation">Implementation</h2> <p>The windows in this EIP are expected to start after the Istanbul Network upgrade, which is the next planned Roadmap upgrade. Istanbul is currently slated for mainnet launch on 2019-10-16, which is compatible with the schedule in this EIP.</p> <p>The Roadmap Upgrade windows starting with Istanbul would be as follows:</p> <table><thead><tr><th>Block Target</th><th>Launch Week Range</th></tr></thead><tbody> <tr><td>2019-10-16</td><td>2019-10-14 to 2019-10-18</td></tr> <tr><td>2020-01-15</td><td>2020-01-13 to 2020-01-17</td></tr> <tr><td>2020-04-15</td><td>2020-04-13 to 2020-04-17</td></tr> <tr><td>2020-07-15</td><td>2020-07-13 to 2020-07-17</td></tr> <tr><td>2020-10-21</td><td>2020-10-19 to 2020-10-23</td></tr> <tr><td>2021-01-20</td><td>2021-01-18 to 2021-01-22</td></tr> <tr><td>2021-04-21</td><td>2021-04-19 to 2021-04-23</td></tr> <tr><td>2021-07-21</td><td>2021-07-19 to 2021-07-23</td></tr> <tr><td>2021-10-20</td><td>2021-10-18 to 2021-10-22</td></tr> <tr><td>2022-01-19</td><td>2022-01-17 to 2022-01-21</td></tr> <tr><td>2022-04-20</td><td>2022-04-18 to 2022-04-22</td></tr> <tr><td>2022-07-20</td><td>2022-07-18 to 2022-07-22</td></tr> <tr><td>2022-10-19</td><td>2022-10-17 to 2022-10-21</td></tr> </tbody></table> <p>The Priority windows through next year, excluding Roadmap windows, are as follows:</p> <table><thead><tr><th>Block Target</th><th>Launch Week Range</th></tr></thead><tbody> <tr><td>2019-11-20</td><td>2019-11-18 to 2019-11-22</td></tr> <tr><td>2019-12-18</td><td>2019-12-16 to 2019-12-20</td></tr> <tr><td>2020-02-19</td><td>2020-02-17 to 2020-02-21</td></tr> <tr><td>2020-03-18</td><td>2020-03-16 to 2020-03-20</td></tr> <tr><td>2020-05-20</td><td>2020-05-18 to 2020-05-22</td></tr> <tr><td>2020-06-17</td><td>2020-06-15 to 2020-06-19</td></tr> <tr><td>2020-08-19</td><td>2020-08-18 to 2020-08-21</td></tr> <tr><td>2020-09-16</td><td>2020-09-14 to 2020-09-18</td></tr> <tr><td>2020-11-18</td><td>2020-11-16 to 2020-11-20</td></tr> <tr><td>2020-12-16</td><td>2020-12-14 to 2020-12-18</td></tr> </tbody></table> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-03-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Tobias Obersteintobias.oberstein@crossbario.com https://wg-eips.ritovision.com/665/ <h2 id="simple-summary">Simple Summary</h2> <p>Support performant and cheap verification of Ed25519 cryptographic signatures in smart contracts in general by adding a precompiled contract for Ed25519 signature verification to the EVM.</p> <h2 id="abstract">Abstract</h2> <p>Verification of Ed25519 cryptographic signatures is obviously possible in EVM bytecode. However, the gas cost will be very high, and computationally expensive, as such tight, wide word operations intensive code as required for Ed25519 is not a good fit for the EVM bytecode model.</p> <p>The addition of a native compiled function, in a precompiled contract, to the EVM solves both cost and performance problems.</p> <h2 id="motivation">Motivation</h2> <p>Ed25519 and Ed448 (that is, EdDSA using Curve25519 or Curve448) are IETF recommendations (<a rel="external" href="https://tools.ietf.org/html/rfc7748">RFC7748</a>) with some attractive properties:</p> <ul> <li>Ed25519 is intended to operate at around the 128-bit security level and Ed448 at around the 224-bit security level</li> <li>EdDSA uses small public keys (32 or 57 octets) and signatures (64 or 114 octets) for Ed25519 and Ed448, respectively</li> <li>Ed25519/Ed448 are designed so that fast, constant-time (timing attack resistant) and generally side-channel resistant implementations are easier to produce</li> </ul> <p>Despite being around only for some years, post-Snowden, these curves <a rel="external" href="https://ianix.com/pub/ed25519-deployment.html">have gained wide use</a> quickly in various protocols and systems:</p> <ul> <li>TLS / ECDH(E) (session keys)</li> <li>TLS / x.509 (client and server certificates)</li> <li>DNSSEC (zone signing)</li> <li>OpenSSH (user keys)</li> <li>GNUPG/OpenPGP (user keys)</li> <li>OpenBSD Signify (software signing)</li> </ul> <p>One motivation for Ed25519 signature verification in smart contracts is to <strong>associate</strong> existing off-chain systems, records or accounts that use Ed25519 (like above) with blockchain addresses or <strong>delegate</strong> by allowing to sign data with Ed25519 (only), and then submit this Ed25519-signed data anonymously (via any Eth sender address) to the blockchain, having the contract check the Ed25519 signature of the transaction.</p> <p>Another motivation is the processing of external, Ed25519 proof-of-stake based blockchains within Ethereum smart contracts.</p> <p>When a transactions contains data that comes with an Ed25519 signature, that proves that the sender of the Ethereum transaction was also in control of the private key (and the data), and this allows the contract to establish an association between the blockchain and the external system or account, and the external system establish the reverse relation.</p> <p>For example, a contract might check a Ed25519 signed piece of data submitted to the Ethereum transaction like the current block number. That proves to the contract, that the sender is in possession of both the Ethereum private key and the Ed25519 private key, and hence the contract will accept an association between both. This again can be the root anchor for various powerful applications, as now a potentially crypto holding key owner has proven to be in control of some external off-chain system or account, like e.g. a DNS server, a DNS domain, a cluster node and so on.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= CONSTANTINOPLE_FORK_BLKNUM</code>, add a precompiled contract for Ed25519 signature verification (<code>ED25519VFY</code>).</p> <p>The proposal adds a new precompiled function <code>ED25519VFY</code> with the following input and output.</p> <p><code>ED25519VFY</code> takes as <strong>input 128 octets</strong>:</p> <ol> <li><strong>message</strong>: the 32-octet message that was signed</li> <li><strong>public key</strong>: the 32-octet Ed25519 public key of the signer</li> <li><strong>signature</strong>: the 64-octet Ed25519 signature</li> </ol> <p><code>ED25519VFY</code> returns as <strong>output 4 octets</strong>:</p> <ul> <li><code>0x00000000</code> if signature is valid</li> <li>any non-zero value indicates a signature verification failure</li> </ul> <h3 id="address">Address</h3> <p>The address of <code>ED25519VFY</code> is <strong><code>0x9</code>.</strong></p> <h3 id="gas-costs">Gas costs</h3> <p>Gas cost for <code>ED25519VFY</code> is <strong>2000</strong>.</p> <h2 id="rationale">Rationale</h2> <p>The proposed <code>ED25519VFY</code> function takes the signer public key as a call parameter, as with Ed25519, I don't believe it is possible to derive the signers public key from the signature and message alone.</p> <p>The proposed <code>ED25519VFY</code> function uses a zero return value to indicate success, since this allows for different errors to be distinguished by return value, as all non-zero return values signal a verification failure.</p> <p><code>ECRECOVER</code> has a gas cost of 3000. Since Ed25519 is computationally cheaper, the gas price should be less.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>As the proposed precompiled contract is deployed at a reserved (&lt;255) and previously unused address, an implementation of the proposal should not introduce any backward compatibility issues.</p> <h2 id="test-cases">Test Cases</h2> <p>Test vectors for Ed25519 can be found in this IETF ID https://tools.ietf.org/html/draft-josefsson-eddsa-ed25519-03#section-6.</p> <p>More test vectors can be found in the regression tests of NaCl (see references).</p> <h2 id="implementation">Implementation</h2> <h3 id="libsodium">libsodium</h3> <p>libsodium is a mature, high-quality C implementation of Ed25519, with bindings for many languages.</p> <p>Further, libsodium is (to my knowledge, and as of today 2018/04) the only Ed25519 implementation that has gone through a <a rel="external" href="https://www.privateinternetaccess.com/blog/2017/08/libsodium-v1-0-12-and-v1-0-13-security-assessment/">Security Assessment</a>.</p> <p>To minimize consensus failure risks, the proposal recommends to use libsodium for adding the precompile in all Ethereum client implementations.</p> <blockquote> <p>Note: as an alternative to libsodium, I looked into HACL, an implementation of Ed25519 in F* (a ML dialect) that can be transpiled to C, and that was formally verified for functional correctness and memory safety of the resulting C code. However, this is new and compared to libsodium which is a "know thing" seems risky nevertheless.</p> </blockquote> <h3 id="libsodium-bindings">libsodium bindings</h3> <p>Here is an overview of the language bindings to libsodium for four Ethereum clients this proposal recommends:</p> <table><thead><tr><th>Client</th><th>Language</th><th>libsodium binding</th></tr></thead><tbody> <tr><td>Geth</td><td>Go</td><td>use cgo with C <a rel="external" href="https://github.com/jedisct1/libsodium">libsodium</a></td></tr> <tr><td>Parity</td><td>Rust</td><td><a rel="external" href="https://github.com/dnaq/sodiumoxide">sodiumoxide</a></td></tr> <tr><td>PyEthereum</td><td>Python</td><td><a rel="external" href="https://github.com/pyca/pynacl">PyNaCl</a></td></tr> <tr><td>cpp-ethereum</td><td>C++</td><td><a rel="external" href="https://github.com/jedisct1/libsodium">libsodium</a></td></tr> </tbody></table> <hr /> <h3 id="prs">PRs</h3> <p>Implementations of this proposal are here:</p> <ol> <li><a rel="external" href="https://github.com/ethereum/go-ethereum/pull/16453">go-ethereum PR #16453</a></li> <li><a rel="external" href="https://github.com/ethereum/pyethereum/pull/862">pyethereum PR #862</a></li> <li><a rel="external" href="https://github.com/paritytech/parity/pull/8330">parity PR #8330</a></li> <li><a rel="external" href="https://github.com/ethereum/cpp-ethereum/pull/4945">cpp-ethereum PR #4945</a></li> </ol> <h2 id="references">References</h2> <ul> <li>RFC7748 - Elliptic Curves for Security https://tools.ietf.org/html/rfc7748</li> <li>Definition of Ed25519: https://ed25519.cr.yp.to/ed25519-20110926.pdf</li> <li>Ed25519 - high-speed high-security signatures: https://ed25519.cr.yp.to/</li> <li>NaCl - Networking and Cryptography library: https://nacl.cr.yp.to/sign.html</li> <li>NaCl Crypto Libraries (which contains Ed25519): https://ianix.com/pub/ed25519-deployment.html</li> <li>Test vectors for Ed25519: https://tools.ietf.org/html/draft-josefsson-eddsa-ed25519-03#section-6</li> <li>NaCl regression tests: https://ed25519.cr.yp.to/python/sign.py and https://ed25519.cr.yp.to/python/sign.input</li> <li>On the recoverability of public keys from signature+message (alone): https://crypto.stackexchange.com/questions/9936/what-signature-schemes-allow-recovering-the-public-key-from-a-signature</li> <li>Bernstein, D., "Curve25519: new Diffie-Hellman speed records", DOI 10.1007/11745853_14, February 2006, https://cr.yp.to/ecdh.html</li> <li>Hamburg, M., "Ed448-Goldilocks, a new elliptic curve", June 2015, https://eprint.iacr.org/2015/625&gt;</li> <li>RFC8080: Edwards-Curve Digital Security Algorithm (EdDSA) for DNSSEC (https://datatracker.ietf.org/doc/html/rfc8080)</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-03-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonnick@ethereum.org https://wg-eips.ritovision.com/926/ <h2 id="abstract">Abstract</h2> <p>This EIP specifies a registry for address metadata, permitting both contracts and external accounts to supply metadata about themselves to onchain and offchain callers. This permits use-cases such as generalised authorisations, providing token acceptance settings, and claims registries.</p> <h2 id="motivation">Motivation</h2> <p>An increasing set of use cases require storage of metadata associated with an address; see for instance EIP 777 and EIP 780, and the ENS reverse registry in EIP 181. Presently each use-case defines its own specialised registry. To prevent a proliferation of special-purpose registry contracts, we instead propose a single standardised registry using an extendable architecture that allows future standards to implement their own metadata standards.</p> <h2 id="specification">Specification</h2> <p>The metadata registry has the following interface:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> AddressMetadataRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> provider</span><span>(</span><span class="z-support">address</span><span class="z-variable"> target</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setProvider</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _provider</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p><code>setProvider</code> specifies the metadata registry to be associated with the caller's address, while <code>provider</code> returns the address of the metadata registry for the supplied address.</p> <p>The metadata registry will be compiled with an agreed-upon version of Solidity and deployed using the trustless deployment mechanism to a fixed address that can be replicated across all chains.</p> <h2 id="provider-specification">Provider specification</h2> <p>Providers may implement any subset of the metadata record types specified here. Where a record types specification requires a provider to provide multiple functions, the provider MUST implement either all or none of them. Providers MUST throw if called with an unsupported function ID.</p> <p>Providers have one mandatory function:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> supportsInterface</span><span>(</span><span class="z-support">bytes4</span><span class="z-variable"> interfaceID</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span></span></code></pre> <p>The <code>supportsInterface</code> function is documented in <a href="https://wg-eips.ritovision.com/165/">EIP-165</a>, and returns true if the provider implements the interface specified by the provided 4 byte identifier. An interface identifier consists of the XOR of the function signature hashes of the functions provided by that interface; in the degenerate case of single-function interfaces, it is simply equal to the signature hash of that function. If a provider returns <code>true</code> for <code>supportsInterface()</code>, it must implement the functions specified in that interface.</p> <p><code>supportsInterface</code> must always return true for <code>0x01ffc9a7</code>, which is the interface ID of <code>supportsInterface</code> itself.</p> <p>The first argument to all provider functions MUST be the address being queried; this facilitates the creation of multi-user provider contracts.</p> <p>Currently standardised provider interfaces are specified in the table below.</p> <table><thead><tr><th>Interface name</th><th>Interface hash</th><th>Specification</th></tr></thead><tbody> </tbody></table> <p>EIPs may define new interfaces to be added to this registry.</p> <h2 id="rationale">Rationale</h2> <p>There are two obvious approaches for a generic metadata registry: the indirection approach employed here, or a generalised key/value store. While indirection incurs the cost of an additional contract call, and requires providers to change over time, it also provides for significantly enhanced flexibility over a key/value store; for that reason we selected this approach.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backwards compatibility concerns.</p> <h2 id="implementation">Implementation</h2> <p>The canonical implementation of the metadata registry is as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> AddressMetadataRegistry</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> mapping</span><span>(</span><span class="z-support">address</span><span class="z-keyword">=&gt;</span><span class="z-support">address</span><span>)</span><span class="z-storage z-type"> public</span><span> provider</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> setProvider</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _provider</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> provider</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span class="z-keyword"> =</span><span> _provider</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-03-12T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonnick@ethereum.org https://wg-eips.ritovision.com/927/ <h2 id="abstract">Abstract</h2> <p>This EIP specifies a generic authorisation mechanism, which can be used to implement a variety of authorisation patterns, replacing approvals in ERC20, operators in ERC777, and bespoke authorisation patterns in a variety of other types of contract.</p> <h2 id="motivation">Motivation</h2> <p>Smart contracts commonly need to provide an interface that allows a third-party caller to perform actions on behalf of a user. The most common example of this is token authorisations/operators, but other similar situations exist throughout the ecosystem, including for instance authorising operations on ENS domains. Typically each standard reinvents this system for themselves, leading to a large number of incompatible implementations of the same basic pattern. Here, we propose a generic method usable by all such contracts.</p> <p>The pattern implemented here is inspired by <a rel="external" href="https://github.com/dapphub/ds-auth">ds-auth</a> and by OAuth.</p> <h2 id="specification">Specification</h2> <p>The generalised authorisation interface is implemented as a metadata provider, as specified in EIP 926. The following mandatory function is implemented:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> canCall</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> caller</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> callee</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> func</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span>)</span><span>;</span></span></code></pre> <p>Where:</p> <ul> <li><code>owner</code> is the owner of the resource. If approved the function call is treated as being made by this address.</li> <li><code>caller</code> is the address making the present call.</li> <li><code>callee</code> is the address of the contract being called.</li> <li><code>func</code> is the 4-byte signature of the function being called.</li> </ul> <p>For example, suppose Alice authorises Bob to transfer tokens on her behalf. When Bob does so, Alice is the <code>owner</code>, Bob is the <code>caller</code>, the token contract is the <code>callee</code>, and the function signature for the transfer function is <code>func</code>.</p> <p>As this standard uses EIP 926, the authorisation flow is as follows:</p> <ol> <li>The callee contract fetches the provider for the <code>owner</code> address from the metadata registry contract, which resides at a well-known address.</li> <li>The callee contract calls <code>canCall()</code> with the parameters described above. If the function returns false, the callee reverts execution.</li> </ol> <p>Commonly, providers will wish to supply a standardised interface for users to set and unset their own authorisations. They SHOULD implement the following interface:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> authoriseCaller</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> caller</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> callee</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> func</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> revokeCaller</span><span>(</span><span class="z-support">address</span><span class="z-variable"> owner</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> caller</span><span>,</span><span class="z-support"> address</span><span class="z-variable"> callee</span><span>,</span><span class="z-support"> bytes4</span><span class="z-variable"> func</span><span>)</span><span>;</span></span></code></pre> <p>Arguments have the same meaning as in <code>canCall</code>. Implementing contracts MUST ensure that <code>msg.sender</code> is authorised to call <code>authoriseCaller</code> or <code>revokeCaller</code> on behalf of <code>owner</code>; this MUST always be true if <code>owner == msg.sender</code>. Implementing contracts SHOULD use the standard specified here to determine if other callers may provide authorisations as well.</p> <p>Implementing contracts SHOULD treat a <code>func</code> of 0 as authorising calls to all functions on <code>callee</code>. If <code>authorised</code> is <code>false</code> and <code>func</code> is 0, contracts need only clear any blanket authorisation; individual authorisations may remain in effect.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>There are no backwards compatibility concerns.</p> <h2 id="implementation">Implementation</h2> <p>Example implementation TBD.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-03-07T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jay Logelinjlogelin@alumni.harvard.edu Infernal_toastadmin@0xbitcoin.org Michael Seilermgs33@cornell.edu Brandon Grillbg2655@columbia.edu https://wg-eips.ritovision.com/918/ <h3 id="simple-summary">Simple Summary</h3> <p>A specification for a standardized Mineable Token that uses a Proof of Work algorithm for distribution.</p> <h3 id="abstract">Abstract</h3> <p>This specification describes a method for initially locking tokens within a token contract and slowly dispensing them with a mint() function which acts like a faucet. This mint() function uses a Proof of Work algorithm in order to minimize gas fees and control the distribution rate. Additionally, standardization of mineable tokens will give rise to standardized CPU and GPU token mining software, token mining pools and other external tools in the token mining ecosystem.</p> <h3 id="motivation">Motivation</h3> <p>Token distribution via the ICO model and its derivatives is susceptible to illicit behavior by human actors. Furthermore, new token projects are centralized because a single entity must handle and control all of the initial coins and all of the raised ICO money. By distributing tokens via an 'Initial Mining Offering' (or IMO), the ownership of the token contract no longer belongs with the deployer at all and the deployer is 'just another user.' As a result, investor risk exposure utilizing a mined token distribution model is significantly diminished. This standard is intended to be standalone, allowing maximum interoperability with ERC20, ERC721, and others.</p> <h3 id="specification">Specification</h3> <h4 id="interface">Interface</h4> <p>The general behavioral specification includes a primary function that defines the token minting operation, an optional merged minting operation for issuing multiple tokens, getters for challenge number, mining difficulty, mining target and current reward, and finally a Mint event, to be emitted upon successful solution validation and token issuance. At a minimum, contracts must adhere to this interface (save the optional merge operation). It is recommended that contracts interface with the more behaviorally defined Abstract Contract described below, in order to leverage a more defined construct, allowing for easier external implementations via overridden phased functions. (see 'Abstract Contract' below)</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC918</span><span> {</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mint</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> nonce</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getAdjustmentInterval</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getChallengeNumber</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getMiningDifficulty</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getMiningTarget</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> getMiningReward</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> decimals</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint8</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Mint</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> rewardAmount</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> epochCount</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> newChallengeNumber</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h4 id="abstract-contract-optional">Abstract Contract (Optional)</h4> <p>The Abstract Contract adheres to the EIP918 Interface and extends behavioral definition through the introduction of 4 internal phases of token mining and minting: hash, reward, epoch and adjust difficulty, all called during the mint() operation. This construct provides a balance between being too general for use while providing ample room for multiple mined implementation types.</p> <h3 id="fields">Fields</h3> <h4 id="adjustmentinterval">adjustmentInterval</h4> <p>The amount of time between difficulty adjustments in seconds.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> public</span><span> adjustmentInterval</span><span>;</span></span></code></pre><h4 id="challengenumber">challengeNumber</h4> <p>The current challenge number. It is expected that a new challenge number is generated after a new reward is minted.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">bytes32</span><span class="z-storage z-type"> public</span><span> challengeNumber</span><span>;</span></span></code></pre><h4 id="difficulty">difficulty</h4> <p>The current mining difficulty which should be adjusted via the _adjustDifficulty minting phase</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint</span><span class="z-storage z-type"> public</span><span> difficulty</span><span>;</span></span></code></pre><h4 id="tokensminted">tokensMinted</h4> <p>Cumulative counter of the total minted tokens, usually modified during the _reward phase</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint</span><span class="z-storage z-type"> public</span><span> tokensMinted</span><span>;</span></span></code></pre><h4 id="epochcount">epochCount</h4> <p>Number of 'blocks' mined</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">uint</span><span class="z-storage z-type"> public</span><span> epochCount</span><span>;</span></span></code></pre><h3 id="mining-operations">Mining Operations</h3> <h4 id="mint">mint</h4> <p>Returns a flag indicating a successful hash digest verification, and reward allocation to msg.sender. In order to prevent MiTM attacks, it is recommended that the digest include a recent Ethereum block hash and msg.sender's address. Once verified, the mint function calculates and delivers a mining reward to the sender and performs internal accounting operations on the contract's supply.</p> <p>The mint operation exists as a public function that invokes 4 separate phases, represented as functions hash, _reward, _newEpoch, and _adjustDifficulty. In order to create the most flexible implementation while adhering to a necessary contract protocol, it is recommended that token implementors override the internal methods, allowing the base contract to handle their execution via mint.</p> <p>This externally facing function is called by miners to validate challenge digests, calculate reward, populate statistics, mutate epoch variables and adjust the solution difficulty as required. Once complete, a Mint event is emitted before returning a boolean success flag.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> AbstractERC918</span><span class="z-storage"> is</span><span class="z-entity z-name"> EIP918Interface</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> the amount of time between difficulty adjustments</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span> adjustmentInterval</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> generate a new challenge number after a new reward is minted</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span class="z-storage z-type"> public</span><span> challengeNumber</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> the current mining target</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span> miningTarget</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> cumulative counter of the total minted tokens</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span> tokensMinted</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> number of blocks per difficulty readjustment</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span> blocksPerReadjustment</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">number of &#39;blocks&#39; mined</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span class="z-storage z-type"> public</span><span> epochCount</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * Externally facing mint function that is called by miners to validate challenge digests, calculate reward,</span></span> <span class="giallo-l"><span class="z-comment"> * populate statistics, mutate epoch variables and adjust the solution difficulty as required. Once complete,</span></span> <span class="giallo-l"><span class="z-comment"> * a Mint event is emitted before returning a success indicator.</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mint</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> nonce</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span class="z-variable z-language">msg.sender</span><span class="z-keyword"> !=</span><span class="z-support"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> perform the hash function validation</span></span> <span class="giallo-l"><span class="z-entity z-name"> hash</span><span>(</span><span>nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> calculate the current reward</span></span> <span class="giallo-l"><span class="z-support"> uint</span><span> rewardAmount </span><span class="z-keyword">=</span><span class="z-entity z-name"> _reward</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> increment the minted tokens amount</span></span> <span class="giallo-l"><span> tokensMinted </span><span class="z-keyword">+</span><span class="z-keyword">=</span><span> rewardAmount</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span> epochCount </span><span class="z-keyword">=</span><span class="z-entity z-name"> _epoch</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">every so often, readjust difficulty. Don&#39;t readjust when deploying</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>epochCount % blocksPerReadjustment </span><span class="z-keyword">==</span><span class="z-constant"> 0</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> _adjustDifficulty</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> send Mint event indicating a successful implementation</span></span> <span class="giallo-l"><span class="z-keyword"> emit</span><span class="z-entity z-name"> Mint</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> rewardAmount</span><span>,</span><span> epochCount</span><span>,</span><span> challengeNumber</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h5 id="mint-event"><em>Mint Event</em></h5> <p>Upon successful verification and reward the mint method dispatches a Mint Event indicating the reward address, the reward amount, the epoch count and newest challenge number.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Mint</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> reward_amount</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> epochCount</span><span>, </span><span class="z-support">bytes32</span><span class="z-variable"> newChallengeNumber</span><span>)</span><span>;</span></span></code></pre><h4 id="hash">hash</h4> <p>Public interface function hash, meant to be overridden in implementation to define hashing algorithm and validation. Returns the validated digest</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> hash</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> nonce</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span class="z-variable"> digest</span><span>)</span><span>;</span></span></code></pre><h4 id="reward">_reward</h4> <p>Internal interface function _reward, meant to be overridden in implementation to calculate and allocate the reward amount. The reward amount must be returned by this method.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> _reward</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span></code></pre><h4 id="newepoch">_newEpoch</h4> <p>Internal interface function _newEpoch, meant to be overridden in implementation to define a cutpoint for mutating mining variables in preparation for the next phase of mine.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> _newEpoch</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> nonce</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span></code></pre><h4 id="adjustdifficulty">_adjustDifficulty</h4> <p>Internal interface function _adjustDifficulty, meant to be overridden in implementation to adjust the difficulty (via field difficulty) of the mining as required</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> _adjustDifficulty</span><span>(</span><span>)</span><span class="z-storage z-type"> internal</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span></code></pre><h4 id="getadjustmentinterval">getAdjustmentInterval</h4> <p>The amount of time, in seconds, between difficulty adjustment operations.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getAdjustmentInterval</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span><span>;</span></span></code></pre><h4 id="getchallengenumber">getChallengeNumber</h4> <p>Recent ethereum block hash, used to prevent pre-mining future blocks.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getChallengeNumber</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bytes32</span><span>)</span><span>;</span></span></code></pre><h4 id="getminingdifficulty">getMiningDifficulty</h4> <p>The number of digits that the digest of the PoW solution requires which typically auto adjusts during reward generation.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getMiningDifficulty</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span></span></code></pre><h4 id="getminingreward">getMiningReward</h4> <p>Return the current reward amount. Depending on the algorithm, typically rewards are divided every reward era as tokens are mined to provide scarcity.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getMiningReward</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint</span><span>)</span></span></code></pre><h3 id="example-mining-function">Example mining function</h3> <p>A general mining function written in python for finding a valid nonce for keccak256 mined token, is as follows:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> generate_nonce</span><span>(</span><span>)</span><span>:</span></span> <span class="giallo-l"><span> myhex</span><span class="z-keyword"> =</span><span class="z-storage z-type"> b</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-constant">%064x</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> %</span><span> getrandbits</span><span>(</span><span class="z-constant">32</span><span class="z-keyword">*</span><span class="z-constant">8</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> codecs</span><span>.</span><span>decode</span><span>(</span><span>myhex</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">hex_codec</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span></span> <span class="giallo-l"><span> </span></span> <span class="giallo-l"><span class="z-storage z-type">def</span><span class="z-entity z-name"> mine</span><span>(</span><span class="z-variable z-parameter z-function">challenge</span><span>,</span><span class="z-variable z-parameter z-function"> public_address</span><span>,</span><span class="z-variable z-parameter z-function"> difficulty</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span class="z-constant"> True</span><span>:</span></span> <span class="giallo-l"><span> nonce</span><span class="z-keyword"> =</span><span> generate_nonce</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> hash1</span><span class="z-keyword"> =</span><span class="z-support"> int</span><span>(</span><span>sha3</span><span>.</span><span>keccak_256</span><span>(</span><span>challenge</span><span class="z-keyword">+</span><span>public_address</span><span class="z-keyword">+</span><span>nonce</span><span>)</span><span>.</span><span>hexdigest</span><span>(</span><span>)</span><span>,</span><span class="z-constant"> 16</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> hash1</span><span class="z-keyword"> &lt;</span><span> difficulty</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span> nonce</span><span>,</span><span> hash1</span></span></code></pre> <p>Once the nonce and hash1 are found, these are used to call the mint() function of the smart contract to receive a reward of tokens.</p> <h3 id="merged-mining-extension-optional">Merged Mining Extension (Optional)</h3> <p>In order to provide support for merge mining multiple tokens, an optional merged mining extension can be implemented as part of the ERC918 standard. It is important to note that the following function will only properly work if the base contracts use tx.origin instead of msg.sender when applying rewards. If not the rewarded tokens will be sent to the calling contract and not the end user.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-918 Mineable Token Standard, optional merged mining functionality</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See https://github.com/ethereum/EIPs/blob/master/EIPS/./00918.md</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC918Merged</span><span class="z-storage"> is</span><span class="z-entity z-name"> AbstractERC918</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * @notice Externally facing merge function that is called by miners to validate challenge digests, calculate reward,</span></span> <span class="giallo-l"><span class="z-comment"> * populate statistics, mutate state variables and adjust the solution difficulty as required. Additionally, the</span></span> <span class="giallo-l"><span class="z-comment"> * merge function takes an array of target token addresses to be used in merged rewards. Once complete,</span></span> <span class="giallo-l"><span class="z-comment"> * a Mint event is emitted before returning a success indicator.</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * @param _nonce the solution nonce</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> merge</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _nonce</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable z-parameter z-function"> _mineTokens</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> for</span><span> (</span><span class="z-support">uint</span><span> i </span><span class="z-keyword">=</span><span class="z-constant"> 0</span><span>;</span><span> i </span><span class="z-keyword">&lt;</span><span> _mineTokens</span><span>.</span><span>length</span><span>;</span><span> i</span><span class="z-keyword">+</span><span class="z-keyword">+</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> address</span><span> tokenAddress </span><span class="z-keyword">=</span><span> _mineTokens</span><span>[</span><span>i</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> ERC918Interface</span><span>(</span><span>tokenAddress</span><span>)</span><span>.</span><span class="z-entity z-name">mint</span><span>(</span><span>_nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * @notice Externally facing merge function kept for backwards compatibility with previous definition</span></span> <span class="giallo-l"><span class="z-comment"> *</span></span> <span class="giallo-l"><span class="z-comment"> * @param _nonce the solution nonce</span></span> <span class="giallo-l"><span class="z-comment"> * @param _challenge_digest the keccak256 encoded challenge number + message sender + solution nonce</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> merge</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _nonce</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _challenge_digest</span><span>,</span><span class="z-support"> address</span><span>[</span><span>]</span><span class="z-variable z-parameter z-function"> _mineTokens</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">the challenge digest must match the expected</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> digest </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>challengeNumber</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> _nonce</span><span>)</span><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>digest </span><span class="z-keyword">==</span><span> _challenge_digest</span><span>,</span><span class="z-string"> &quot;Challenge digest does not match expected digest on token contract [ ERC918Merged.mint() ]&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> merge</span><span>(</span><span>_nonce</span><span>,</span><span> _mineTokens</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="delegated-minting-extension-optional">Delegated Minting Extension (Optional)</h3> <p>In order to facilitate a third party minting submission paradigm, such as the case of miners submitting solutions to a pool operator and/or system, a delegated minting extension can be used to allow pool accounts submit solutions on the behalf of a user, so the miner can avoid directly paying Ethereum transaction costs. This is performed by an off chain mining account packaging and signing a standardized mint solution packet and sending it to a pool or 3rd party to be submitted.</p> <p>The ERC918 Mineable Mint Packet Metadata should be prepared using following schema:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-string"> &quot;title&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Mineable Mint Packet Metadata&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;object&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;properties&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;nonce&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Identifies the target solution nonce&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;origin&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Identifies the original user that mined the solution nonce&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;signature&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;The signed hash of tightly packed variables sha3(&#39;delegatedMintHashing(uint256,address)&#39;)+nonce+origin_account&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The preparation of a mineable mint packet on a JavaScript client would appear as follows:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> prepareDelegatedMintTxn</span><span>(</span><span class="z-variable">nonce</span><span>,</span><span class="z-variable"> account</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> var functionSig </span><span class="z-keyword">=</span><span> web3</span><span>.</span><span>utils</span><span>.</span><span class="z-support">sha3</span><span>(</span><span class="z-string">&quot;delegatedMintHashing(uint256,address)&quot;</span><span>)</span><span>.</span><span class="z-entity z-name">substring</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant">10</span><span>)</span></span> <span class="giallo-l"><span> var data </span><span class="z-keyword">=</span><span> web3</span><span>.</span><span>utils</span><span>.</span><span class="z-entity z-name">soliditySha3</span><span>(</span><span> functionSig</span><span>,</span><span> nonce</span><span>,</span><span> account</span><span>.</span><span class="z-support">address</span><span> )</span></span> <span class="giallo-l"><span> var sig </span><span class="z-keyword">=</span><span> web3</span><span>.</span><span>eth</span><span>.</span><span>accounts</span><span>.</span><span class="z-entity z-name">sign</span><span>(</span><span>web3</span><span>.</span><span>utils</span><span>.</span><span class="z-entity z-name">toHex</span><span>(</span><span>data</span><span>)</span><span>,</span><span> account</span><span>.</span><span>privateKey </span><span>)</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> prepare the mint packet</span></span> <span class="giallo-l"><span> var packet </span><span class="z-keyword">=</span><span> {</span><span>}</span></span> <span class="giallo-l"><span> packet</span><span>.</span><span>nonce </span><span class="z-keyword">=</span><span> nonce</span></span> <span class="giallo-l"><span> packet</span><span>.</span><span>origin </span><span class="z-keyword">=</span><span> account</span><span>.</span><span class="z-support">address</span></span> <span class="giallo-l"><span> packet</span><span>.</span><span>signature </span><span class="z-keyword">=</span><span> sig</span><span>.</span><span>signature</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> deliver resulting JSON packet to pool or third party</span></span> <span class="giallo-l"><span> var mineableMintPacket </span><span class="z-keyword">=</span><span> JSON</span><span>.</span><span class="z-entity z-name">stringify</span><span>(</span><span>packet</span><span>,</span><span> null</span><span>,</span><span class="z-constant"> 4</span><span>)</span></span> <span class="giallo-l"><span class="z-comment"> /*</span><span class="z-keyword"> todo</span><span class="z-comment">: send mineableMintPacket to submitter </span><span class="z-comment">*/</span></span> <span class="giallo-l"><span> .</span><span>.</span><span>.</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Once the packet is prepared and formatted it can then be routed to a third party that will submit the transaction to the contract's delegatedMint() function, thereby paying for the transaction gas and receiving the resulting tokens. The pool/third party must then manually payback the minted tokens minus fees to the original minter.</p> <p>The following code sample exemplifies third party packet relaying:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">//</span><span class="z-comment">received by minter</span></span> <span class="giallo-l"><span>var mineableMintPacket </span><span class="z-keyword">=</span><span> .</span><span>.</span><span>.</span></span> <span class="giallo-l"><span>var packet </span><span class="z-keyword">=</span><span> JSON</span><span>.</span><span class="z-entity z-name">parse</span><span>(</span><span>mineableMintPacket</span><span>)</span></span> <span class="giallo-l"><span>erc918MineableToken</span><span>.</span><span class="z-entity z-name">delegatedMint</span><span>(</span><span>packet</span><span>.</span><span>nonce</span><span>,</span><span> packet</span><span>.</span><span>origin</span><span>,</span><span> packet</span><span>.</span><span>signature</span><span>)</span></span></code></pre> <p>The Delegated Mint Extension expands upon ERC918 realized as a sub-contract:</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-keyword">import</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">openzeppelin-solidity/contracts/contracts/cryptography/ECDSA.sol</span><span class="z-punctuation z-definition z-string">&#39;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other">contract</span><span class="z-variable z-other"> ERC918DelegatedMint</span><span class="z-variable z-other"> is</span><span class="z-variable z-other"> AbstractERC918</span><span>,</span><span class="z-variable z-other z-constant"> ECDSA</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">notice</span><span class="z-comment"> Hash (keccak256) of the payload used by delegatedMint</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">param</span><span class="z-variable z-other"> _nonce</span><span class="z-comment"> the golden nonce</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">param</span><span class="z-variable z-other"> _origin</span><span class="z-comment"> the original minter</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">param</span><span class="z-variable z-other"> _signature</span><span class="z-comment"> the original minter&#39;s elliptical curve signature</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegatedMint</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _nonce</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _origin</span><span>,</span><span class="z-variable"> bytes</span><span class="z-variable"> _signature</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> bytes32</span><span class="z-variable z-other"> hashedTx</span><span class="z-keyword"> =</span><span class="z-entity z-name"> delegatedMintHashing</span><span>(</span><span class="z-variable z-other">_nonce</span><span>,</span><span class="z-variable z-other"> _origin</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> address</span><span class="z-variable z-other"> minter</span><span class="z-keyword"> =</span><span class="z-entity z-name"> recover</span><span>(</span><span class="z-variable z-other">hashedTx</span><span>,</span><span class="z-variable z-other"> _signature</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">minter</span><span class="z-keyword"> ==</span><span class="z-variable z-other"> _origin</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Origin minter address does not match recovered signature address [ AbstractERC918.delegatedMint() ]</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> require</span><span>(</span><span class="z-variable z-other">minter</span><span class="z-keyword"> !=</span><span class="z-entity z-name"> address</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Invalid minter address recovered from signature [ ERC918DelegatedMint.delegatedMint() ]</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> success</span><span class="z-keyword"> =</span><span class="z-entity z-name"> mintInternal</span><span>(</span><span class="z-variable z-other">_nonce</span><span>,</span><span class="z-variable z-other"> minter</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">notice</span><span class="z-comment"> Hash (keccak256) of the payload used by delegatedMint</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">param</span><span class="z-variable z-other"> _nonce</span><span class="z-comment"> the golden nonce</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@</span><span class="z-storage z-type">param</span><span class="z-variable z-other"> _origin</span><span class="z-comment"> the original minter</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> delegatedMintHashing</span><span>(</span><span class="z-variable">uint256</span><span class="z-variable"> _nonce</span><span>,</span><span class="z-variable"> address</span><span class="z-variable"> _origin</span><span>)</span><span class="z-entity z-name"> public</span><span class="z-entity z-name"> pure</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bytes32</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /*</span><span class="z-comment"> &quot;0x7b36737a&quot;: delegatedMintHashing(uint256,address) </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-entity z-name"> toEthSignedMessageHash</span><span>(</span><span class="z-entity z-name">keccak256</span><span>(</span><span class="z-variable z-other">abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span class="z-entity z-name"> bytes4</span><span>(</span><span class="z-constant">0x7b36737a</span><span>)</span><span>,</span><span class="z-variable z-other"> _nonce</span><span>,</span><span class="z-variable z-other"> _origin</span><span>)</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="mineable-token-metadata-optional">Mineable Token Metadata (Optional)</h3> <p>In order to provide for richer and potentially mutable metadata for a particular Mineable Token, it is more viable to offer an off-chain reference to said data. This requires the implementation of a single interface method 'metadataURI()' that returns a JSON string encoded with the string fields symbol, name, description, website, image, and type.</p> <p>Solidity interface for Mineable Token Metadata:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-918 Mineable Token Standard, optional metadata extension</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See https://github.com/ethereum/EIPs/blob/master/EIPS/./00918.md</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERC918Metadata</span><span class="z-storage"> is</span><span class="z-entity z-name"> AbstractERC918</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> /**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@notice</span><span class="z-comment"> A distinct Uniform Resource Identifier (URI) for a mineable asset.</span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> metadataURI</span><span>(</span><span>)</span><span class="z-storage z-type"> external</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>Mineable Token Metadata JSON schema definition:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-string"> &quot;title&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Mineable Token Metadata&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;object&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;properties&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;symbol&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Identifies the Mineable Token&#39;s symbol&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;name&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Identifies the Mineable Token&#39;s name&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Identifies the Mineable Token&#39;s long description&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;website&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Identifies the Mineable Token&#39;s homepage URI&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;image&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Identifies the Mineable Token&#39;s image URI&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span> {</span></span> <span class="giallo-l"><span class="z-string"> &quot;type&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;string&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-string"> &quot;description&quot;</span><span class="z-keyword">:</span><span class="z-string"> &quot;Identifies the Mineable Token&#39;s hash algorithm ( ie.keccak256 ) used to encode the solution&quot;</span><span>,</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="rationale">Rationale</h3> <p>The solidity keccak256 algorithm does not have to be used, but it is recommended since it is a cost effective one-way algorithm to perform in the EVM and simple to perform in solidity. The nonce is the solution that miners try to find and so it is part of the hashing algorithm. A challengeNumber is also part of the hash so that future blocks cannot be mined since it acts like a random piece of data that is not revealed until a mining round starts. The msg.sender address is part of the hash so that a nonce solution is valid only for a particular Ethereum account and so the solution is not susceptible to man-in-the-middle attacks. This also allows pools to operate without being easily cheated by the miners since pools can force miners to mine using the pool's address in the hash algorithm.</p> <p>The economics of transferring electricity and hardware into mined token assets offers a flourishing community of decentralized miners the option to be involved in the Ethereum token economy directly. By voting with hash power, an economically pegged asset to real-world resources, miners are incentivized to participate in early token trade to revamp initial costs, providing a bootstrapped stimulus mechanism between miners and early investors.</p> <p>One community concern for mined tokens has been around energy use without a function for securing a network. Although token mining does not secure a network, it serves the function of securing a community from corruption as it offers an alternative to centralized ICOs. Furthermore, an initial mining offering may last as little as a week, a day, or an hour at which point all of the tokens would have been minted.</p> <h3 id="backwards-compatibility">Backwards Compatibility</h3> <p>Earlier versions of this standard incorporated a redundant 'challenge_digest' parameter on the mint() function that hash-encoded the packed variables challengeNumber, msg.sender and nonce. It was decided that this could be removed from the standard to help minimize processing and thereby gas usage during mint operations. However, in the name of interoperability with existing mining programs and pool software the following contract can be added to the inheritance tree:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-comment">/**</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@title</span><span class="z-comment"> ERC-918 Mineable Token Standard, optional backwards compatibility function</span></span> <span class="giallo-l"><span class="z-comment"> * </span><span class="z-storage z-type">@dev</span><span class="z-comment"> See https://github.com/ethereum/EIPs/blob/master/EIPS/./00918.md</span></span> <span class="giallo-l"><span class="z-comment"> * </span></span> <span class="giallo-l"><span class="z-comment"> */</span></span> <span class="giallo-l"><span class="z-storage z-type">contract</span><span class="z-entity z-name"> ERC918BackwardsCompatible</span><span class="z-storage"> is</span><span class="z-entity z-name"> AbstractERC918</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> /*</span></span> <span class="giallo-l"><span class="z-comment"> * @notice Externally facing mint function kept for backwards compatibility with previous mint() definition</span></span> <span class="giallo-l"><span class="z-comment"> * @param _nonce the solution nonce</span></span> <span class="giallo-l"><span class="z-comment"> * @param _challenge_digest the keccak256 encoded challenge number + message sender + solution nonce</span></span> <span class="giallo-l"><span class="z-comment"> *</span><span class="z-comment">*/</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> mint</span><span>(</span><span class="z-support">uint256</span><span class="z-variable z-parameter z-function"> _nonce</span><span>,</span><span class="z-support"> bytes32</span><span class="z-variable z-parameter z-function"> _challenge_digest</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment">the challenge digest must match the expected</span></span> <span class="giallo-l"><span class="z-support"> bytes32</span><span> digest </span><span class="z-keyword">=</span><span class="z-support"> keccak256</span><span>(</span><span class="z-variable z-language"> abi</span><span>.</span><span class="z-entity z-name">encodePacked</span><span>(</span><span>challengeNumber</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> _nonce</span><span>)</span><span> )</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> require</span><span>(</span><span>digest </span><span class="z-keyword">==</span><span> _challenge_digest</span><span>,</span><span class="z-string"> &quot;Challenge digest does not match expected digest on token contract [ AbstractERC918.mint() ]&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> success </span><span class="z-keyword">=</span><span class="z-entity z-name"> mint</span><span>(</span><span>_nonce</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="test-cases">Test Cases</h3> <p>(Test cases for an implementation are mandatory for EIPs that are affecting consensus changes. Other EIPs can choose to include links to test cases if applicable.)</p> <h3 id="implementation">Implementation</h3> <p>Simple Example: https://github.com/0xbitcoin/EIP918-Mineable-Token/blob/master/contracts/SimpleERC918.sol</p> <p>Complex Examples:</p> <p>https://github.com/0xbitcoin/EIP918-Mineable-Token/blob/master/contracts/0xdogeExample.sol https://github.com/0xbitcoin/EIP918-Mineable-Token/blob/master/contracts/0xdogeExample2.sol https://github.com/0xbitcoin/EIP918-Mineable-Token/blob/master/contracts/0xBitcoinBase.sol</p> <p>0xBitcoin Token Contract: https://etherscan.io/address/0xb6ed7644c69416d67b522e20bc294a9a9b405b31</p> <p>MVI OpenCL Token Miner https://github.com/mining-visualizer/MVis-tokenminer/releases</p> <p>PoWAdv Token Contract: https://etherscan.io/address/0x1a136ae98b49b92841562b6574d1f3f5b0044e4c</p> <h3 id="copyright">Copyright</h3> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-02-22T00:00:00+00:00 2026-02-11T14:48:25+00:00 Dean Eigenmanndean@tokenate.io Jorge Izquierdojorge@aragon.one https://wg-eips.ritovision.com/900/ <h2 id="abstract">Abstract</h2> <p>The following standard describes a common staking interface allowing for easy to use staking systems. The interface is kept simple allowing for various use cases to be implemented. This standard describes the common functionality for staking as well as providing information on stakes.</p> <h2 id="motivation">Motivation</h2> <p>As we move to more token models, having a common staking interface which is familiar to users can be useful. The common interface can be used by a variety of applications, this common interface could be beneficial especially to things like Token curated registries which have recently gained popularity.</p> <h2 id="specification">Specification</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> Staking</span><span> {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Staked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> total</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Unstaked</span><span>(</span><span class="z-support">address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> user</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>, </span><span class="z-support">uint256</span><span class="z-variable"> total</span><span>, </span><span class="z-support">bytes</span><span class="z-variable"> data</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> stake</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> stakeFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> user</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> unstake</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> amount</span><span>,</span><span class="z-support"> bytes</span><span class="z-variable"> data</span><span>)</span><span class="z-storage z-type"> public</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalStakedFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> addr</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalStaked</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> token</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> supportsHistory</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-comment"> //</span><span class="z-comment"> optional</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> lastStakedFor</span><span>(</span><span class="z-support">address</span><span class="z-variable"> addr</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalStakedForAt</span><span>(</span><span class="z-support">address</span><span class="z-variable"> addr</span><span>,</span><span class="z-support"> uint256</span><span class="z-variable"> blockNumber</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> totalStakedAt</span><span>(</span><span class="z-support">uint256</span><span class="z-variable"> blockNumber</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="stake">stake</h3> <p>Stakes a certain amount of tokens, this MUST transfer the given amount from the user.</p> <p><em>The data field can be used to add signalling information in more complex staking applications</em></p> <p>MUST trigger <code>Staked</code> event.</p> <h3 id="stakefor">stakeFor</h3> <p>Stakes a certain amount of tokens, this MUST transfer the given amount from the caller.</p> <p><em>The data field can be used to add signalling information in more complex staking applications</em></p> <p>MUST trigger <code>Staked</code> event.</p> <h3 id="unstake">unstake</h3> <p>Unstakes a certain amount of tokens, this SHOULD return the given amount of tokens to the user, if unstaking is currently not possible the function MUST revert.</p> <p><em>The data field can be used to remove signalling information in more complex staking applications</em></p> <p>MUST trigger <code>Unstaked</code> event.</p> <h3 id="totalstakedfor">totalStakedFor</h3> <p>Returns the current total of tokens staked for an address.</p> <h3 id="totalstaked">totalStaked</h3> <p>Returns the current total of tokens staked.</p> <h3 id="token">token</h3> <p>Address of the token being used by the staking interface.</p> <h3 id="supportshistory">supportsHistory</h3> <p>MUST return true if the optional history functions are implemented, otherwise false.</p> <h3 id="laststakedfor">lastStakedFor</h3> <p><em><strong>OPTIONAL:</strong> As not all staking systems require a complete history, this function is optional.</em></p> <p>Returns last block address staked at.</p> <h3 id="totalstakedforat">totalStakedForAt</h3> <p><em><strong>OPTIONAL:</strong> As not all staking systems require a complete history, this function is optional.</em></p> <p>Returns total amount of tokens staked at block for address.</p> <h3 id="totalstakedat">totalStakedAt</h3> <p><em><strong>OPTIONAL:</strong> As not all staking systems require a complete history, this function is optional.</em></p> <p>Returns the total tokens staked at block.</p> <h2 id="implementation">Implementation</h2> <ul> <li><a rel="external" href="https://github.com/HarbourProject/stakebank">Stakebank</a></li> <li><a rel="external" href="https://github.com/aragon/aragon-apps/pull/101">Aragon</a></li> <li><a rel="external" href="https://github.com/maticnetwork/contracts/blob/master/contracts/StakeManager.sol">PoS Staking</a></li> <li><a rel="external" href="https://github.com/codex-protocol/contract.erc-900">BasicStakeContract</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-02-21T00:00:00+00:00 2026-02-11T14:48:25+00:00 Jorge Izquierdojorge@aragon.one Manuel Araozmanuel@zeppelin.solutions https://wg-eips.ritovision.com/897/ <h2 id="simple-summary">Simple Summary</h2> <p>Proxy contracts are being increasingly used as both as an upgradeability mechanism and a way to save gas when deploying many instances of a particular contract. This standard proposes a set of interfaces for proxies to signal how they work and what their main implementation is.</p> <h2 id="abstract">Abstract</h2> <p>Using proxies that delegate their own logic to another contract is becoming an increasingly popular technique for both smart contract upgradeability and creating cheap clone contracts.</p> <p>We don't believe there is value in standardizing any particular implementation of a DelegateProxy, given its simplicity, but we believe there is a lot of value in agreeing on an interface all proxies use that allows for a standard way to operate with proxies.</p> <h2 id="implementations">Implementations</h2> <ul> <li> <p><strong>aragonOS</strong>: <a rel="external" href="https://github.com/aragon/aragonOS/blob/master/contracts/apps/AppProxyUpgradeable.sol">AppProxyUpgradeable</a>, <a rel="external" href="https://github.com/aragon/aragonOS/blob/master/contracts/apps/AppProxyPinned.sol">AppProxyPinned</a> and <a rel="external" href="https://github.com/aragon/aragonOS/blob/master/contracts/kernel/KernelProxy.sol">KernelProxy</a></p> </li> <li> <p><strong>zeppelinOS</strong>: <a rel="external" href="https://github.com/zeppelinos/labs/blob/2da9e859db81a61f2449d188e7193788ca721c65/upgradeability_ownership/contracts/Proxy.sol">Proxy</a></p> </li> </ul> <h2 id="standardized-interface">Standardized interface</h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ERCProxy</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> proxyType</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> pure</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">uint256</span><span class="z-variable"> proxyTypeId</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> implementation</span><span>(</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">address</span><span class="z-variable"> codeAddr</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="code-address-implementation">Code address (<code>implementation()</code>)</h3> <p>The returned code address is the address the proxy would delegate calls to at that moment in time, for that message.</p> <h3 id="proxy-type-proxytype">Proxy Type (<code>proxyType()</code>)</h3> <p>Checking the proxy type is the way to check whether a contract is a proxy at all. When a contract fails to return to this method or it returns 0, it can be assumed that the contract is not a proxy.</p> <p>It also allows for communicating a bit more of information about how the proxy operates. It is a pure function, therefore making it effectively constant as it cannot return a different value depending on state changes.</p> <ul> <li> <p><strong>Forwarding proxy</strong> (<code>id = 1</code>): The proxy will always forward to the same code address. The following invariant should always be true: once the proxy returns a non-zero code address, that code address should never change.</p> </li> <li> <p><strong>Upgradeable proxy</strong> (<code>id = 2</code>): The proxy code address can be changed depending on some arbitrary logic implemented either at the proxy level or in its forwarded logic.</p> </li> </ul> <h2 id="benefits">Benefits</h2> <ul> <li><strong>Source code verification</strong>: right now when checking the code of a proxy in explorers like Etherscan, it just shows the code in the proxy itself but not the actual code of the contract. By standardizing this construct, they will be able to show both the actual ABI and code for the contract.</li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-02-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Dave Sagdavesag@gmail.com https://wg-eips.ritovision.com/884/ <h1 id="delaware-general-corporations-law-dgcl-compatible-share-token">Delaware General Corporations Law (DGCL) compatible share token</h1> <p>Ref: <a rel="external" href="https://forum.ethereum.org/discussion/17200/proposing-an-eip-for-regulation-a-Tokens">proposing-an-eip-for-DGCL-tokens</a></p> <h2 id="simple-summary">Simple Summary</h2> <p>An <code>ERC-20</code> compatible token that conforms to <a rel="external" href="https://legis.delaware.gov/json/BillDetail/GenerateHtmlDocument?legislationId=25730&amp;legislationTypeId=1&amp;docTypeId=2&amp;legislationName=SB69">Delaware State Senate, 149th General Assembly, Senate Bill No. 69: An act to Amend Title 8 of the Delaware Code Relating to the General Corporation Law</a>, henceforth referred to as 'The Act'.</p> <h2 id="abstract">Abstract</h2> <p>The recently amended 'Title 8 of the Delaware Code Relating to the General Corporation Law' now explicitly allows for the use of blockchains to maintain corporate share registries. This means it is now possible to create a tradable <code>ERC-20</code> token where each token represents a share issued by a Delaware corporation. Such a token must conform to the following principles over and above the <code>ERC-20</code> standard.</p> <ol> <li> <p>Token owners must have their identity verified.</p> </li> <li> <p>The token contract must provide the following three functions of a <code>Corporations Stock ledger</code> (Ref: Section 224 of The Act):</p> <ol> <li> <p>Reporting:</p> <p>It must enable the corporation to prepare the list of shareholders specified in Sections 219 and 220 of The Act.</p> </li> <li> <p>It must record the information specified in Sections 156, 159, 217(a) and 218 of The Act:</p> <ul> <li>Partly paid shares</li> <li>Total amount paid</li> <li>Total amount to be paid</li> </ul> </li> <li> <p>Transfers of shares as per section 159 of The Act:</p> <p>It must record transfers of shares as governed by Article 8 of subtitle I of Title 6.</p> </li> </ol> </li> <li> <p>Each token MUST correspond to a single share, each of which would be paid for in full, so there is no need to record information concerning partly paid shares, and there are no partial tokens.</p> </li> <li> <p>There must be a mechanism to allow a shareholder who has lost their private key, or otherwise lost access to their tokens to have their address <code>cancelled</code> and the tokens re-issued to a new address.</p> </li> </ol> <h2 id="motivation">Motivation</h2> <ol> <li>Delaware General Corporation Law requires that shares issued by a Delaware corporation be recorded in a share registry.</li> <li>The share registry can be represented by an <code>ERC-20</code> token contract that is compliant with Delaware General Corporation Law.</li> <li>This standard can cover equity issued by any Delaware corporation, whether private or public.</li> </ol> <p>By using a <code>DGCL</code> compatible token, a firm may be able to raise funds via IPO, conforming to Delaware Corporations Law, but bypassing the need for involvement of a traditional Stock Exchange.</p> <p>There are currently no token standards that conform to the <code>DGCL</code> rules. <code>ERC-20</code> tokens do not support KYC/AML rules required by the General Corporation Law, and do not provide facilities for the exporting of lists of shareholders.</p> <h3 id="what-about-erc-721">What about ERC-721?</h3> <p>The proposed standard could easily be used to enhance <code>ERC-721</code>, adding features for associating tokens with assets such as share certificates.</p> <p>While the <code>ERC-721</code> token proposal allows for some association of metadata with an Ethereum address, its uses are <em>not completely aligned</em> with The Act, and it is not, in its current form, fully <code>ERC-20</code> compatible.</p> <h2 id="specification">Specification</h2> <p>The <code>ERC-20</code> token provides the following basic features:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>contract ERC20 {</span></span> <span class="giallo-l"><span> function totalSupply() public view returns (uint256);</span></span> <span class="giallo-l"><span> function balanceOf(address who) public view returns (uint256);</span></span> <span class="giallo-l"><span> function transfer(address to, uint256 value) public returns (bool);</span></span> <span class="giallo-l"><span> function allowance(address owner, address spender) public view returns (uint256);</span></span> <span class="giallo-l"><span> function transferFrom(address from, address to, uint256 value) public returns (bool);</span></span> <span class="giallo-l"><span> function approve(address spender, uint256 value) public returns (bool);</span></span> <span class="giallo-l"><span> event Approval(address indexed owner, address indexed spender, uint256 value);</span></span> <span class="giallo-l"><span> event Transfer(address indexed from, address indexed to, uint256 value);</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>This will be extended as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>/**</span></span> <span class="giallo-l"><span> * An `ERC20` compatible token that conforms to Delaware State Senate,</span></span> <span class="giallo-l"><span> * 149th General Assembly, Senate Bill No. 69: An act to Amend Title 8</span></span> <span class="giallo-l"><span> * of the Delaware Code Relating to the General Corporation Law.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * Implementation Details.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * An implementation of this token standard SHOULD provide the following:</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * `name` - for use by wallets and exchanges.</span></span> <span class="giallo-l"><span> * `symbol` - for use by wallets and exchanges.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * The implementation MUST take care not to allow unauthorised access to</span></span> <span class="giallo-l"><span> * share-transfer functions.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * In addition to the above the following optional `ERC20` function MUST be defined.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * `decimals` — MUST return `0` as each token represents a single share and shares are non-divisible.</span></span> <span class="giallo-l"><span> *</span></span> <span class="giallo-l"><span> * @dev Ref https://github.com/ethereum/EIPs/pull/884</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span>contract ERC884 is ERC20 {</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * This event is emitted when a verified address and associated identity hash are</span></span> <span class="giallo-l"><span> * added to the contract.</span></span> <span class="giallo-l"><span> * @param addr The address that was added.</span></span> <span class="giallo-l"><span> * @param hash The identity hash associated with the address.</span></span> <span class="giallo-l"><span> * @param sender The address that caused the address to be added.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event VerifiedAddressAdded(</span></span> <span class="giallo-l"><span> address indexed addr,</span></span> <span class="giallo-l"><span> bytes32 hash,</span></span> <span class="giallo-l"><span> address indexed sender</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * This event is emitted when a verified address and associated identity hash are</span></span> <span class="giallo-l"><span> * removed from the contract.</span></span> <span class="giallo-l"><span> * @param addr The address that was removed.</span></span> <span class="giallo-l"><span> * @param sender The address that caused the address to be removed.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event VerifiedAddressRemoved(address indexed addr, address indexed sender);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * This event is emitted when the identity hash associated with a verified address is updated.</span></span> <span class="giallo-l"><span> * @param addr The address whose hash was updated.</span></span> <span class="giallo-l"><span> * @param oldHash The identity hash that was associated with the address.</span></span> <span class="giallo-l"><span> * @param hash The hash now associated with the address.</span></span> <span class="giallo-l"><span> * @param sender The address that caused the hash to be updated.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event VerifiedAddressUpdated(</span></span> <span class="giallo-l"><span> address indexed addr,</span></span> <span class="giallo-l"><span> bytes32 oldHash,</span></span> <span class="giallo-l"><span> bytes32 hash,</span></span> <span class="giallo-l"><span> address indexed sender</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * This event is emitted when an address is cancelled and replaced with</span></span> <span class="giallo-l"><span> * a new address. This happens in the case where a shareholder has</span></span> <span class="giallo-l"><span> * lost access to their original address and needs to have their share</span></span> <span class="giallo-l"><span> * reissued to a new address. This is the equivalent of issuing replacement</span></span> <span class="giallo-l"><span> * share certificates.</span></span> <span class="giallo-l"><span> * @param original The address being superseded.</span></span> <span class="giallo-l"><span> * @param replacement The new address.</span></span> <span class="giallo-l"><span> * @param sender The address that caused the address to be superseded.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> event VerifiedAddressSuperseded(</span></span> <span class="giallo-l"><span> address indexed original,</span></span> <span class="giallo-l"><span> address indexed replacement,</span></span> <span class="giallo-l"><span> address indexed sender</span></span> <span class="giallo-l"><span> );</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Add a verified address, along with an associated verification hash to the contract.</span></span> <span class="giallo-l"><span> * Upon successful addition of a verified address, the contract must emit</span></span> <span class="giallo-l"><span> * `VerifiedAddressAdded(addr, hash, msg.sender)`.</span></span> <span class="giallo-l"><span> * It MUST throw if the supplied address or hash are zero, or if the address has already been supplied.</span></span> <span class="giallo-l"><span> * @param addr The address of the person represented by the supplied hash.</span></span> <span class="giallo-l"><span> * @param hash A cryptographic hash of the address holder&#39;s verified information.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function addVerified(address addr, bytes32 hash) public;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Remove a verified address, and the associated verification hash. If the address is</span></span> <span class="giallo-l"><span> * unknown to the contract then this does nothing. If the address is successfully removed, this</span></span> <span class="giallo-l"><span> * function must emit `VerifiedAddressRemoved(addr, msg.sender)`.</span></span> <span class="giallo-l"><span> * It MUST throw if an attempt is made to remove a verifiedAddress that owns tokens.</span></span> <span class="giallo-l"><span> * @param addr The verified address to be removed.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function removeVerified(address addr) public;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Update the hash for a verified address known to the contract.</span></span> <span class="giallo-l"><span> * Upon successful update of a verified address the contract must emit</span></span> <span class="giallo-l"><span> * `VerifiedAddressUpdated(addr, oldHash, hash, msg.sender)`.</span></span> <span class="giallo-l"><span> * If the hash is the same as the value already stored then</span></span> <span class="giallo-l"><span> * no `VerifiedAddressUpdated` event is to be emitted.</span></span> <span class="giallo-l"><span> * It MUST throw if the hash is zero, or if the address is unverified.</span></span> <span class="giallo-l"><span> * @param addr The verified address of the person represented by the supplied hash.</span></span> <span class="giallo-l"><span> * @param hash A new cryptographic hash of the address holder&#39;s updated verified information.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function updateVerified(address addr, bytes32 hash) public;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Cancel the original address and reissue the tokens to the replacement address.</span></span> <span class="giallo-l"><span> * Access to this function MUST be strictly controlled.</span></span> <span class="giallo-l"><span> * The `original` address MUST be removed from the set of verified addresses.</span></span> <span class="giallo-l"><span> * Throw if the `original` address supplied is not a shareholder.</span></span> <span class="giallo-l"><span> * Throw if the `replacement` address is not a verified address.</span></span> <span class="giallo-l"><span> * Throw if the `replacement` address already holds tokens.</span></span> <span class="giallo-l"><span> * This function MUST emit the `VerifiedAddressSuperseded` event.</span></span> <span class="giallo-l"><span> * @param original The address to be superseded. This address MUST NOT be reused.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function cancelAndReissue(address original, address replacement) public;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * The `transfer` function MUST NOT allow transfers to addresses that</span></span> <span class="giallo-l"><span> * have not been verified and added to the contract.</span></span> <span class="giallo-l"><span> * If the `to` address is not currently a shareholder then it MUST become one.</span></span> <span class="giallo-l"><span> * If the transfer will reduce `msg.sender`&#39;s balance to 0 then that address</span></span> <span class="giallo-l"><span> * MUST be removed from the list of shareholders.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function transfer(address to, uint256 value) public returns (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * The `transferFrom` function MUST NOT allow transfers to addresses that</span></span> <span class="giallo-l"><span> * have not been verified and added to the contract.</span></span> <span class="giallo-l"><span> * If the `to` address is not currently a shareholder then it MUST become one.</span></span> <span class="giallo-l"><span> * If the transfer will reduce `from`&#39;s balance to 0 then that address</span></span> <span class="giallo-l"><span> * MUST be removed from the list of shareholders.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function transferFrom(address from, address to, uint256 value) public returns (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Tests that the supplied address is known to the contract.</span></span> <span class="giallo-l"><span> * @param addr The address to test.</span></span> <span class="giallo-l"><span> * @return true if the address is known to the contract.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function isVerified(address addr) public view returns (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Checks to see if the supplied address is a shareholder.</span></span> <span class="giallo-l"><span> * @param addr The address to check.</span></span> <span class="giallo-l"><span> * @return true if the supplied address owns a token.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function isHolder(address addr) public view returns (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Checks that the supplied hash is associated with the given address.</span></span> <span class="giallo-l"><span> * @param addr The address to test.</span></span> <span class="giallo-l"><span> * @param hash The hash to test.</span></span> <span class="giallo-l"><span> * @return true if the hash matches the one supplied with the address in `addVerified`, or `updateVerified`.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function hasHash(address addr, bytes32 hash) public view returns (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * The number of addresses that hold tokens.</span></span> <span class="giallo-l"><span> * @return the number of unique addresses that hold tokens.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function holderCount() public view returns (uint);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * By counting the number of token holders using `holderCount`</span></span> <span class="giallo-l"><span> * you can retrieve the complete list of token holders, one at a time.</span></span> <span class="giallo-l"><span> * It MUST throw if `index &gt;= holderCount()`.</span></span> <span class="giallo-l"><span> * @param index The zero-based index of the holder.</span></span> <span class="giallo-l"><span> * @return the address of the token holder with the given index.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function holderAt(uint256 index) public view returns (address);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Checks to see if the supplied address was superseded.</span></span> <span class="giallo-l"><span> * @param addr The address to check.</span></span> <span class="giallo-l"><span> * @return true if the supplied address was superseded by another address.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function isSuperseded(address addr) public view returns (bool);</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> /**</span></span> <span class="giallo-l"><span> * Gets the most recent address, given a superseded one.</span></span> <span class="giallo-l"><span> * Addresses may be superseded multiple times, so this function needs to</span></span> <span class="giallo-l"><span> * follow the chain of addresses until it reaches the final, verified address.</span></span> <span class="giallo-l"><span> * @param addr The superseded address.</span></span> <span class="giallo-l"><span> * @return the verified address that ultimately holds the share.</span></span> <span class="giallo-l"><span> */</span></span> <span class="giallo-l"><span> function getCurrentFor(address addr) public view returns (address);</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="securities-exchange-commission-requirements">Securities Exchange Commission Requirements</h3> <p>The Securities Exchange Commission (SEC) has additional requirements as to how a crowdsale ought to be run and what information must be made available to the general public. This information is however out of scope from this standard, though the standard does support the requirements.</p> <p>For example: The SEC requires a crowdsale's website display the amount of money raised in US Dollars. To support this a crowdsale contract minting these tokens must maintain a USD to ETH conversion rate (via Oracle or some other mechanism) and must record the conversion rate used at time of minting.</p> <p>Also, depending on the type of raise, the SEC (or other statutory body) can apply limits to the number of shareholders allowed. To support this the standard provides the <code>holderCount</code> and <code>isHolder</code> functions which a crowdsale can invoke to check that limits have not been exceeded.</p> <h3 id="use-of-the-identity-hash-value">Use of the Identity <code>hash</code> value</h3> <p>Implementers of a crowdsale, in order to comply with The Act, must be able to produce an up-to-date list of the names and addresses of all shareholders. It is not desirable to include those details in a public blockchain, both for reasons of privacy, and also for reasons of economy. Storing arbitrary string data on the blockchain is strongly discouraged.</p> <p>Implementers should maintain an off-chain private database that records the owner's name, residential address, and Ethereum address. The implementer must then be able to extract the name and address for any address, and hash the name + address data and compare that hash to the hash recorded in the contract using the <code>hasHash</code> function. The specific details of this system are left to the implementer.</p> <p>It is also desirable that the implementers offer a REST API endpoint along the lines of</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>GET https://&lt;host&gt;/&lt;pathPrefix&gt;/:ethereumAddress -&gt; [true|false]</span></span></code></pre> <p>to enable third party auditors to verify that a given Ethereum address is known to the implementers as a verified address.</p> <p>How the implementers verify a person's identity is up to them and beyond the scope of this standard.</p> <h3 id="handling-users-who-have-lost-access-to-their-addresses">Handling users who have lost access to their addresses</h3> <p>A traditional share register is typically managed by a Transfer Agent who is authorised to maintain the register accurately, and to handle shareholder enquiries. A common request is for share certificates to be reissued in the case where the shareholder has lost or destroyed their original.</p> <p>Token implementers can handle that via the <code>cancelAndReissue</code> function, which must perform the various changes to ensure that the old address now points to the new one, and that cancelled addresses are not then reused.</p> <h3 id="permissions-management">Permissions management</h3> <p>It is not desirable that anyone can add, remove, update, or supersede verified addresses. How access to these functions is controlled is outside of the scope of this standard.</p> <h2 id="rationale">Rationale</h2> <p>The proposed standard offers as minimal an extension as possible over the existing <code>ERC-20</code> standard in order to conform to the requirements of The Act. Rather than return a <code>bool</code> for successful or unsuccessful completion of state-changing functions such as <code>addVerified</code>, <code>removeVerified</code>, and <code>updateVerified</code>, we have opted to require that implementations <code>throw</code> (preferably by using the <a rel="external" href="https://github.com/ethereum/solidity/issues/1686#issuecomment-328181514">forthcoming <code>require(condition, 'fail message')</code> syntax</a>).</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>The proposed standard is designed to maintain compatibility with <code>ERC-20</code> tokens with the following provisos:</p> <ol> <li>The <code>decimals</code> function MUST return <code>0</code> as the tokens MUST NOT be divisible,</li> <li>The <code>transfer</code> and <code>transferFrom</code> functions MUST NOT allow transfers to non-verified addresses, and MUST maintain a list of shareholders.</li> <li>Shareholders who transfer away their remaining tokens must be pruned from the list of shareholders.</li> </ol> <p>Proviso 1 will not break compatibility with modern wallets or exchanges as they all appear to use that information if available.</p> <p>Proviso 2 will cause transfers to fail if an attempt is made to transfer tokens to a non-verified address. This is implicit in the design and implementers are encouraged to make this abundantly clear to market participants. We appreciate that this will make the standard unpalatable to some exchanges, but it is an SEC requirement that shareholders of a corporation provide verified names and addresses.</p> <p>Proviso 3 is an implementation detail.</p> <h2 id="test-cases-and-reference-implementation">Test Cases and Reference Implementation</h2> <p>Test cases and a reference implementation are available at <a rel="external" href="https://github.com/davesag/ERC884-reference-implementation">github.com/davesag/ERC884-reference-implementation</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-02-14T00:00:00+00:00 2026-02-11T14:48:25+00:00 Brooklyn Zelenkahttps://github.com/expede Tom Carchraehttps://github.com/carchrae Gleb Naumenkohttps://github.com/naumenkogs https://wg-eips.ritovision.com/902/ <h1 id="simple-summary">Simple Summary</h1> <p>A protocol for services providing token ownership and transfer validation.</p> <h1 id="abstract">Abstract</h1> <p>This standard provides a registry contract method for authorizing token transfers. By nature, this covers both initially issuing tokens to users (ie: transfer from contract to owner), transferring tokens between users, and token spends.</p> <h1 id="motivation">Motivation</h1> <p>The tokenization of assets has wide application, not least of which is financial instruments such as securities and security tokens. Most jurisdictions have placed legal constraints on what may be traded, and who can hold such tokens which are regarded as securities. Broadly this includes KYC and AML validation, but may also include time-based spend limits, total volume of transactions, and so on.</p> <p>Regulators and sanctioned third-party compliance agencies need some way to link off-chain compliance information such as identity and residency to an on-chain service. The application of this design is broader than legal regulation, encompassing all manner of business logic permissions for the creation, management, and trading of tokens.</p> <p>Rather than each token maintaining its own whitelist (or other mechanism), it is preferable to share on-chain resources, rules, lists, and so on. There is also a desire to aggregate data and rules spread across multiple validators, or to apply complex behaviours (ex. switching logic, gates, state machines) to apply distributed data to an application.</p> <h1 id="specification">Specification</h1> <h2 id="tokenvalidator"><code>TokenValidator</code></h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> TokenValidator</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> check</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _token</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _subject</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-variable">byte</span><span class="z-variable"> statusCode</span><span>)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> function</span><span class="z-entity z-name"> check</span><span>(</span></span> <span class="giallo-l"><span class="z-entity z-name"> address</span><span class="z-entity z-name"> _token</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> address</span><span class="z-entity z-name"> _from</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> address</span><span class="z-entity z-name"> _to</span><span>,</span></span> <span class="giallo-l"><span class="z-entity z-name"> uint256</span><span class="z-entity z-name"> _amount</span></span> <span class="giallo-l"><span> )</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-variable">byte</span><span class="z-variable"> statusCode</span><span>)</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="methods">Methods</h3> <h4 id="check-2"><code>check</code>/2</h4> <p><code>function check(address _token, address _subject) public returns (byte _resultCode)</code></p> <blockquote> <p>parameters</p> <ul> <li><code>_token</code>: the token under review</li> <li><code>_subject</code>: the user or contract to check</li> </ul> <p><em>returns</em> an ERC1066 status code</p> </blockquote> <h4 id="check-4"><code>check</code>/4</h4> <p><code>function check(address token, address from, address to, uint256 amount) public returns (byte resultCode)</code></p> <blockquote> <p>parameters</p> <ul> <li><code>_token</code>: the token under review</li> <li><code>_from</code>: in the case of a transfer, who is relinquishing token ownership</li> <li><code>_to</code>: in the case of a transfer, who is accepting token ownership</li> <li><code>_amount</code>: The number of tokens being transferred</li> </ul> <p><em>returns</em> an ERC1066 status code</p> </blockquote> <h2 id="validatedtoken"><code>ValidatedToken</code></h2> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> ValidatedToken</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Validation</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> subject</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> byte</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> result</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> event</span><span class="z-entity z-name"> Validation</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> value</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> byte</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> statusCode</span></span> <span class="giallo-l"><span> )</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h3 id="events">Events</h3> <h4 id="validation-2"><code>Validation</code>/2</h4> <p><code>event Validation(address indexed subject, byte indexed resultCode)</code></p> <p>This event MUST be fired on return from a call to a <code>TokenValidator.check/2</code>.</p> <blockquote> <p>parameters</p> <ul> <li><code>subject</code>: the user or contract that was checked</li> <li><code>statusCode</code>: an ERC1066 status code</li> </ul> </blockquote> <h4 id="validation-4"><code>Validation</code>/4</h4> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Validation</span><span>(</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> from</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> address</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> to</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> uint256</span><span class="z-variable"> amount</span><span>,</span></span> <span class="giallo-l"><span class="z-variable"> byte</span><span class="z-storage z-type"> indexed</span><span class="z-variable"> statusCode</span></span> <span class="giallo-l"><span>)</span></span></code></pre> <p>This event MUST be fired on return from a call to a <code>TokenValidator.check/4</code>.</p> <blockquote> <p>parameters</p> <ul> <li><code>from</code>: in the case of a transfer, who is relinquishing token ownership</li> <li><code>to</code>: in the case of a transfer, who is accepting token ownership</li> <li><code>amount</code>: The number of tokens being transferred</li> <li><code>statusCode</code>: an ERC1066 status code</li> </ul> </blockquote> <h1 id="rationale">Rationale</h1> <p>This proposal includes a financial permissions system on top of any financial token. This design is not a general roles/permission system. In any system, the more you know about the context where a function will be called, the more powerful your function can be. By restricting ourselves to token transfers (ex. ERC20 or EIP-777), we can make assumptions about the use cases our validators will need to handle, and can make the API both small, useful, and extensible.</p> <p>The events are fired by the calling token. Since <code>Validator</code>s may aggregate or delegate to other <code>Validator</code>s, it would generate a lot of useless events were it the <code>Validator</code>'s responsibility. This is also the reason why we include the <code>token</code> in the <code>call/4</code> arguments: a <code>Validator</code> cannot rely on <code>msg.sender</code> to determine the token that the call is concerning.</p> <p>We have also seen a similar design from <a rel="external" href="https://github.com/harborhq/r-token">R-Token</a> that uses an additional field: <code>spender</code>. While there are potential use cases for this, it's not widely used enough to justify passing a dummy value along with every call. Instead, such a call would look more like this:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> approve</span><span>(</span><span class="z-support">address</span><span class="z-variable"> spender</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span>validator</span><span>.</span><span class="z-entity z-name">check</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-language"> msg.sender</span><span>,</span><span> spender</span><span>,</span><span> amount</span><span>)</span><span class="z-keyword"> ==</span><span> okStatusCode</span><span>)</span><span> {</span></span> <span class="giallo-l"><span> allowed</span><span>[</span><span class="z-variable z-language">msg.sender</span><span>]</span><span>[</span><span>spender</span><span>]</span><span class="z-keyword"> =</span><span> amount</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> Approval</span><span>(</span><span class="z-variable z-language">msg.sender</span><span>,</span><span> spender</span><span>,</span><span> amount</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> else</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>A second <code>check/2</code> function is also required, that is more general-purpose, and does not specify a transfer amount or recipient. This is intended for general checks, such as checking roles (admin, owner, &amp;c), or if a user is on a simple whitelist.</p> <p>We have left the decision to make associated <code>Validator</code> addresses public, private, or hardcoded up to the implementer. The proposed design does not include a centralized registry. It also does not include an interface for a <code>Validated</code> contract. A token may require one or many <code>Validator</code>s for different purposes, requiring different validations for different, or just a single <code>Validator</code>. The potential use cases are too varied to provide a single unified set of methods. We have provided a set of example contracts <a rel="external" href="https://github.com/Finhaven/ValidatedToken/">here</a> that may be inherited from for common use cases.</p> <p>The status codes in the <code>byte</code> returns are unspecified. Any status code scheme may be used, though a general status code proposal is fortcoming.</p> <p>By only defining the validation check, this standard is widely compatible with ERC-20, EIP-721, EIP-777, future token standards, centralized and decentralized exchanges, and so on.</p> <h1 id="implementation">Implementation</h1> <p><a rel="external" href="https://github.com/expede/validated-token/">Reference implementation</a></p> <h1 id="copyright">Copyright</h1> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-02-02T00:00:00+00:00 2026-02-11T14:49:27+00:00 Dan Phiferdp@musiconomi.com James Levyjames@taptrust.com Reuben Youngblomreuben@taptrust.com https://wg-eips.ritovision.com/867/ <h2 id="simple-summary">Simple Summary</h2> <p>Provide a standardized format for Ethereum Recovery Proposals (ERPs), which relate to recovery of certain classes of lost funds. Individual ERPs will follow the same process as any EIP, but will be formatted and evaluated in a standard way to ensure consistency and transparency.</p> <p><strong>This EIP does not advocate for or against the acceptance of any particular recovery proposals, nor would its acceptance alone result in any state changes to the blockchain.</strong></p> <h2 id="abstract">Abstract</h2> <p>This proposal identifies a common solution method that can be used to address certain classes of lost funds on the Ethereum blockchain. In particular, it is intended to address cases where there is no disagreement about the right outcome between directly affected parties, enabling timely and low-risk solutions to many issues that have already occurred or are likely to occur again as Ethereum grows.</p> <p>The solution method is divided into three parts:</p> <ol> <li>Standards that will need to be met by any follow-on ERP in order to be considered for approval.</li> <li>Recommendations for a common format for ERPs to use to specify a set of corrective actions that can be interpreted by clients.</li> <li>Guidelines for client teams to implement code that can read, interpret, and apply the corrective actions at a specific block. The set of possible corrective actions is intentionally limited to minimize risk associated with any ERP.</li> </ol> <h2 id="motivation">Motivation</h2> <p>The issue of fund recovery on the Ethereum blockchain is often controversial. Frozen fund recovery proposals are almost never successful due to the relatively ad-hoc nature of such requests and the subjectivity that is often required to evaluate the merits. This EIP attempts to remove these barriers by providing both a standardized format for fund recovery EIPs and an objective standard by which to measure future proposals.</p> <h2 id="specification">Specification</h2> <p>This EIP describes a common format to be used for a subclass of EIPs, referred to as ethereum recovery proposals (ERPs), that propose an irregular state change required to address a fund recovery scenario that cannot be addressed using the standard protocol. Each ERP will reference this EIP will follow the guidelines set out here.</p> <p>The purpose of each ERP is (a) to clearly describe the issue to be corrected, (b) to describe why an irregular state change is both necessary and justified, and (c) to demonstrate that the proposed actions will achieve the ERP's objectives.</p> <p>Each ERP will be required to use a standard format to represent the set of proposed state changes and must include a verification script that can reliably generate those changes. ERPs that do not meet (at least) these requirements will not be considered for approval.</p> <p>Each ERP should contain the following items:</p> <ul> <li><strong>Preamble</strong>: EIP (RFC 822) header containing metadata about the ERP, including the EIP number, a short title (44 character maximum), and the real names (and optional contact information) for each author.</li> <li><strong>Simple Summary</strong>: A simplified and layman-accessible explanation of the ERP.</li> <li><strong>Detailed description</strong>: A human-readable description of the proposed corrective actions and the criteria used to determine the proposed actions.</li> <li><strong>Justification</strong>: A concise description of why the corrective actions are both reasonable and unlikely to be challenged by any directly affected party.</li> <li><strong>Verification script</strong>: A machine-readable script that outputs one State Change Object. The script should clearly implement the selection and action generating logic outlined in the description such that reviewers can independently re-generate an identical State Change Object.</li> <li><strong>State Change Object</strong>: The output of the verification script and the input to the ethereum clients. Primarily, it specifies the complete set of proposed state change actions.</li> <li><strong>Appendix (optional)</strong>: with supporting evidence. Attachments in the appendix may include documents verifying details specified as part of the recovery proposal description.</li> </ul> <p>The following sections give more detailed descriptions of the expectations for the Justification, Verification Script, and the format of the State Change Object.</p> <h3 id="justification">Justification</h3> <p>A concise description of why this action is both reasonable (cannot be accomplished without an irregular state change) and unlikely to be challenged by a <em>directly</em> affected party.</p> <p><strong>Considerable example</strong> (concise, includes supporting evidence, no negative impact): <em>A crowdsale run by XYZ incorrectly published the testnet address of their crowdsale contract to their public website at the start of their crowdsale on Jan 19, 2018. 501 ETH was sent by 328 users on the mainnet to the incorrect address between block 4,235,987 and 4,236,050. See here for the testnet contract, and see here for the transactions to the same address on the mainnet. See here for a statement made by XYZ on their website. Because there is a contract at this address on the testnet and the corresponding nonce for the creator address has already been used on the mainnet, it is considered effectively impossible that anyone coincidentally holds the private key. We have verified that all transactions came from addresses with no associated code, so there should be no issue returning eth to the senders.</em></p> <p><strong>Insufficient example</strong> (not enough detail, no supporting evidence): <em>We accidentally put the wrong contract address up on our website. Can you please refund any eth sent to 0x1234 back to the senders. Thanks.</em></p> <p><strong>Unacceptable example</strong> (not objective, one person’s word against another): <em>I sent tokens to X for services and he did a lousy job. I want my money back, but he won’t refund me. Please help!!</em></p> <h3 id="verification-script">Verification Script</h3> <p>A machine-readable script that outputs a single State Change Object. This script should be implemented so that it is easily audited by a reviewer. Verification scripts should be javascript files that may use the <a rel="external" href="https://github.com/ethereum/web3.js/">web3.js</a> library.</p> <p>There are a few guidelines for verification scripts:</p> <ul> <li>Scripts should always be written to be as concise as reasonably possible, and anyone executing the verification script should review it first to verify that it does not contain any unsafe operations.</li> <li>No verification script should ever require an unlocked ethereum wallet</li> <li>The script should hardcode the highest block included during execution (otherwise the results may differ between runs).</li> </ul> <p>The purpose of the ERP Verification script is to unambiguously specify (through code) the criteria used to compute the set of State Change Actions. The script’s output, as described above, will be the input used by all Ethereum clients. Client teams should avoid manually pre-processing the artifact or using the artifact to simply guide changes in the code. Instead, the artifact should be bundled with the client and processed directly by the client at the specified block. This will minimize the amount of client effort required for each ERP and help to ensure compatibility between clients. We anticipate that some ERP Verification scripts may be trivial, but we recommend their inclusion for consistency.</p> <h3 id="state-change-object">State Change Object</h3> <p>The State Change Object is a standard format that will be interpretable by all Ethereum clients.</p> <p>It is a single JSON object containing the following fields:</p> <ul> <li><strong>erpId</strong>: A string identifier for this ERP (likely the associated EIP number, e.g. “EIP-1234”). This will be converted from ascii to a hex string, then added as extra data on the target block.</li> <li><strong>targetBlock</strong>: The block at which the stateChange should be applied. Clients would use this to determine when a set of state changes should occur</li> <li><strong>actions</strong>: An array of State Change Actions.</li> <li><strong>metadata</strong> <ul> <li><strong>sourceBlock</strong>: The highest block considered by the script when it was run.</li> <li><strong>version</strong>: The version of the verification script when it was run.</li> </ul> </li> </ul> <h3 id="state-change-actions">State Change Actions</h3> <p>A State Change action is a JSON object that includes a “type” field and a set of “data” fields, where the contents of the data fields are dependent on the type and must follow the schema defined for that type. This allows clients to support a limited set of operations initially and add more based on a subsequent EIP if needed. Support for the following action types should be implemented by clients upon adoption of this EIP:</p> <h4 id="weitransfer">weiTransfer</h4> <p>The <code>weiTransfer</code> action transfers ETH from one address to another.</p> <p><em>Data fields</em></p> <ul> <li><strong>type</strong> (<em>string</em>): <code>weiTransfer</code></li> <li><strong>fromAddress</strong> (<em>hex string</em>): The address from which ETH should be transferred</li> <li><strong>toAddress</strong> (<em>hex string</em>): The address to which ETH should be sent</li> <li><strong>value</strong> (<em>decimal string</em>): The amount of ETH to be transferred, in units of wei. The value must be a whole number greater than zero.</li> </ul> <h4 id="storecode">storeCode</h4> <p>The <code>storeCode</code> action stores the given code at the given address.</p> <p><em>Data fields</em></p> <ul> <li><strong>type</strong> (<em>string</em>): <code>storeCode</code></li> <li><strong>toAddress</strong> (<em>hex string</em>): The address to which the contract should be restored.</li> <li><strong>expectedCodeHash</strong> (<em>hex string</em>): the expected hash of the code already at the toAddress.The empty string should be used if no code is expected at the toAddress. In all other cases, the “0x” prefix is optional.</li> <li><strong>code</strong> (<em>hex string</em>): the new bytecode associated with the contract</li> </ul> <h3 id="appendix-optional">Appendix (Optional)</h3> <p>The appendix can include additional supporting evidence or attachments that will help reviewers understand or verify the claims made in the ERP.</p> <p>For the storeCode operation, it should include the proposed contract source (e.g. Solidity) as well as the other details required such that a reviewer can compile the source and generate the same bytecode. It should also include the source that was originally stored at that address, if possible/applicable. If the two contracts are not identical, changes should be noted. If they are identical, the author should indicate why no changes are necessary (this is unlikely). Additionally, any relevant reviews, audits, and test cases should be included to the extent that they address the issues encountered with the original contract.</p> <p>If accepted, an ERP could easily compile the block at while the changes are to take place, and the source of the actions (which would be the output of the script, in a standardized object output). These can be bundled with the client for seamless execution.</p> <h2 id="erp-approval-process">ERP Approval Process</h2> <p>ERPs are a subclass of EIPs and will, therefore, follow the same approval process.</p> <h3 id="testing">Testing</h3> <p><em>The ERP authors are currently seeking feedback from client teams about the proper testing procedures</em></p> <h2 id="ethereum-client-implementation">Ethereum Client Implementation</h2> <p>Clients that choose to adopt the proposal outlined in this EIP will implement a module that scans a designated directory for SCO files (each time the client process launches) to construct a mapping between target blocks and SCO file names. When starting work on a new block, clients should first consult the set of SCO target blocks discovered and determine if there are any recovery actions required for the current block.</p> <p>E.g. in this example, <code>erpsByTargetBlock</code> is the mapping between the target block number associated with each ERP's State Change Object and a reference (i.e. file name) to the resource with the actual data.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>if (erpsByTargetBlock.get(currentBlock) != null) {</span></span> <span class="giallo-l"><span> try {</span></span> <span class="giallo-l"><span> applyRecoveryActions(erpsByTargetBlock.get(currentBlock));</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> catch (e) {</span></span> <span class="giallo-l"><span> // recovery actions should be treated as a batch. </span></span> <span class="giallo-l"><span> // If one fails, they all fail.</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span>// continue with normal block processing...</span></span></code></pre> <p>The <code>applyRecoveryActions</code> method must apply the recovery actions in the same order as they are stored in the SCO file. Clients are responsible for ensuring that no State Change Action will result in an account transferring an amount that is greater than its current balance. The <code>toAddress</code> for both <code>weiTransfer</code> and <code>storeCode</code> should always be a valid address (i.e. never <code>0x0</code>).</p> <p>Additionally, each block affected by an ERP should include extra data to indicate that the state change occurred. The extra data included in the block should be the erpId found in the SCO file, converted to hex (i.e. <code>hexStringToBytes(asciiToHex(erpId))</code>). Clients should also validate that the expected header appears in the target block if the block is received from a peer.</p> <p>The ERP should link to pull requests for each client repository, and these pull requests should link back to the ERP and also contain its EIP preamble and summary.</p> <p>Each PR associated with an ERP should consist of a single file (the SCO file) added to the client’s designated SCO directory. No additional client code should be required.</p> <h3 id="limitations-of-this-eip">Limitations of this EIP</h3> <p>This EIP is focused on standardizing how recovery proposals can be formatted, to optimize readability and eliminate or minimize as much as possible the potential for mistakes or intentional abuses.</p> <p>The following are considered out of scope from this EIP:</p> <ul> <li>Which fund recovery proposals, if any, should be accepted for implementation.</li> <li>How common classes of recovery proposal plaintiff may organize ERPs representing a collective group of individual parties</li> </ul> <h2 id="rationale">Rationale</h2> <p>The primary consideration for the approach described above was to minimize the amount of risk associated with recovery actions that would otherwise not have a viable solution. A secondary consideration was to standardize the format used in the proposals for recovery actions.</p> <p>First, including a verification script guarantees that the way in which the recovery actions were determined is unambiguous. This does not mean that the recovery actions are necessarily correct, only that the logic used to determine them is fully specified and auditable.</p> <p>Second, requiring that the output of the verification script is directly interpretable by client programs minimizes the work necessary for each client to adopt a particular ERP. It also reduces the risk that two clients will make different decisions about the implementation of a particular ERP.</p> <p>Third, action types are intentionally limited and inflexible, which reduces the likelihood of unintended consequences or maliciously constructed files affecting the blockchain state. The format is easily extensible with new actions types if needed but that would require a separate EIP.</p> <h2 id="implementation">Implementation</h2> <p>A reference implementation has been written for the EthereumJ platform. See the pull request <a rel="external" href="https://github.com/ethereum/ethereumj/pull/1004#commits-pushed-1105610">here</a>.</p> <h2 id="erp-examples">ERP Examples</h2> <p>This section will include examples and SCO resource files, as well as a brief tutorial on how to test using a private testnet.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-01-29T00:00:00+00:00 2026-02-11T14:49:27+00:00 Carl Larsoncslarson@gmail.com https://wg-eips.ritovision.com/858/ <h2 id="simple-summary">Simple Summary</h2> <p>Reduce the block reward to 1 ETH and delay the difficulty bomb.</p> <h2 id="abstract">Abstract</h2> <p>The current public Ethereum network has a hashrate that corresponds to a tremendous level of energy consumption. As this energy consumption has a correlated environmental cost the network participants have an ethical obligation to ensure this cost is not higher than necessary. At this time, the most direct way to reduce this cost is to lower the block reward in order to limit the appeal of ETH mining. Unchecked growth in hashrate is also counterproductive from a security standpoint. Recent research developments also now time the switch to POS as sometime in 2019 and as a result there is need to further delay the difficulty bomb so the network doesn't grind to a halt.</p> <h2 id="motivation">Motivation</h2> <p>The current public Ethereum network has a hashrate of 296 TH/s. This hashrate corresponds to a power usage of roughly <a href="https://wg-eips.ritovision.com/858/assets/calculations/">1 TW</a> and yearly energy consumption of 8.8 TWh (roughly 0.04% of <a rel="external" href="https://en.wikipedia.org/wiki/List_of_countries_by_electricity_consumption">total</a> global electricity consumption). A future switch to full Proof of Stake will solve this issue entirely. Yet that switch remains enough in the future that action should be taken in the interim to limit excess harmful side affects of the present network.</p> <h2 id="specification">Specification</h2> <p>Delay difficulty bomb by 2,000,000 blocks Adjust block, uncle, and nephew rewards to reflect a new block reward of 1 ETH.</p> <h2 id="rationale">Rationale</h2> <p>This will delay the difficulty bomb by roughly a year. The difficulty bomb remains a community supported mechanism to aid a future transition to POS.</p> <p>The network hashrate provides security by reducing the likelihood that an adversary could mount a 51% attack. A static block reward means that factors (price) may be such that participation in mining grows unchecked. This growth may be counterproductive and work to also grow and potential pool of adversaries. The means we have to arrest this growth is to reduce the appeal of mining and the most direct way to do that is to reduce the block reward.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is consensus incompatible with the current public Ethereum chain and would cause a hard fork when enacted. The resulting fork would allow users to chose between two chains: a chain with a block reward of 1 ETH/block and another with a block reward of 3 ETH/block. This is a good choice to allow users to make. In addition, the difficulty bomb would be delayed - ensuring the network would not grind to a halt.</p> <h2 id="test-cases">Test Cases</h2> <p>Tests have, as yet, not been completed.</p> <h2 id="implementation">Implementation</h2> <p>No implementation including both block reward and difficulty adjustment is currently available.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-01-15T00:00:00+00:00 2026-02-11T14:48:26+00:00 ligihttps://github.com/ligi https://wg-eips.ritovision.com/831/

A way of creating Ethereum URIs for various use-cases.

<h2 id="abstract">Abstract</h2> <p>URIs embedded in QR-codes, hyperlinks in web-pages, emails or chat messages provide for robust cross-application signaling between very loosely coupled applications. A standardized URI format allows for instant invocation of the user's preferred wallet application.</p> <h2 id="specification">Specification</h2> <h3 id="syntax">Syntax</h3> <p>Ethereum URIs contain "ethereum" or "eth" in their schema (protocol) part and are constructed as follows:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>request = &quot;eth&quot; [ &quot;ereum&quot; ] &quot;:&quot; [ prefix &quot;-&quot; ] payload</span></span> <span class="giallo-l"><span>prefix = STRING</span></span> <span class="giallo-l"><span>payload = STRING</span></span></code></pre><h3 id="semantics">Semantics</h3> <p><code>prefix</code> is optional and defines the use-case for this URI. If no prefix is given: "pay-" is assumed to be concise and ensure backward compatibility to <a href="https://wg-eips.ritovision.com/67/">EIP-67</a>. When the prefix is omitted, the payload must start with <code>0x</code>. Also prefixes must not start with <code>0x</code>. So starting with <code>0x</code> can be used as a clear signal that there is no prefix.</p> <p><code>payload</code> is mandatory and the content depends on the prefix. Structuring of the content is defined in the ERC for the specific use-case and not in the scope of this document. One example is <a href="https://wg-eips.ritovision.com/681/">EIP-681</a> for the pay- prefix.</p> <h2 id="rationale">Rationale</h2> <p>The need for this ERC emerged when refining EIP-681. We need a container that does not carry the weight of the use-cases. EIP-67 was the first attempt on defining Ethereum-URIs. This ERC tries to keep backward compatibility and not break existing things. This means EIP-67 URIs should still be valid and readable. Only if the prefix feature is used, EIP-67 parsers might break. No way was seen to avoid this and innovate on the same time. This is also the reason this open prefix approach was chosen to being able to adopt to future use-cases and not block the whole "ethereum:" scheme for a limited set of use-cases that existed at the time of writing this.</p> <h2 id="security-considerations">Security Considerations</h2> <p>There are no known security considerations at this time.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2018-01-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Kashish Khullarkkhullar7@gmail.com https://wg-eips.ritovision.com/823/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard for token contracts, providing token exchange services thereby facilitating cross token payments.</p> <h2 id="abstract">Abstract</h2> <p>The following standard provides functionally to make payments in the form of any other registered tokens, as well as allow token contracts to store any other tokens in an existing token contract. This standard allows ERC20 token holders to exchange their token with another ERC20 token and use the exchanged tokens to make payments. After a successful payment, the former specified ERC20 tokens, will be stored within the ERC20 token contract they are exchanged with. This proposal uses the term target contract which is used to denote the contract to the token with whom we want to exchange our tokens.</p> <h2 id="motivation">Motivation</h2> <p>Existing token standards do not provide functionality to exchange tokens. Existing token converters reduce the total supply of an existing token, which in the sense destroys the currency. Token converters do not solve this problem and hence discourages creation of new tokens. This solution does not destroy the existing token but in essence preserve them in the token contract that they are exchanged with, which in turn increases the market value of the latter.</p> <h2 id="specification">Specification</h2> <h3 id="sender-interface">Sender Interface</h3> <p>This interface must be inherited by a ERC20 token contract that wants to exchange its tokens with another token.</p> <h4 id="storage-variables">Storage Variables</h4> <h5 id="exchnagedwith">exchnagedWith</h5> <p>This mapping stores the number of tokens exchanged with another token, along with the latter’s address. Every time more tokens are exchanged the integer value is incremented consequently. This mapping acts as a record to denote which target contract holds our tokens.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">mapping</span><span> (</span><span class="z-support"> address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint</span><span> )</span><span class="z-storage z-type"> private</span><span> exchangedWith</span><span>;</span></span></code></pre><h5 id="exchangedby">exchangedBy</h5> <p>This mapping stores the address of the person who initiated the exchange and the amount of tokens exchanged.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">mapping</span><span> (</span><span class="z-support"> address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint</span><span> )</span><span class="z-storage z-type"> private</span><span> exhangedBy</span><span>;</span></span></code></pre><h4 id="methods">Methods</h4> <p>NOTE: Callers MUST handle false from returns (bool success). Callers MUST NOT assume that false is never returned!</p> <h5 id="exchangetoken">exchangeToken</h5> <p>This function calls the intermediate exchange service contract that handles the exchanges. This function takes the address of the target contract and the amount we want to exchange as parameters and returns boolean <code>success</code> and <code>creditedAmount</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> exchangeToken</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _targetContract</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> creditedAmount</span><span>)</span></span></code></pre><h5 id="exchangeandspend">exchangeAndSpend</h5> <p>This function calls an intermediate exchange service contract that handles exchange and expenditure. This function takes the address of the target contract, the amount we want to spend in terms of target contract tokens and address of the receiver as parameters and returns boolean <code>success</code>.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> exchangeAndSpend</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _targetContract</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _amount</span><span>,</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _to</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h5 id="exchangercallback">__exchangerCallback</h5> <p>This function is called by the exchange service contract to our token contract to deduct calculated amount from our balance. It takes the address of the targert contract , the address of the person who exchanged the tokens and amount to be deducted from exchangers account as parameters and returns boolean <code>success</code>.</p> <p>NOTE: It is required that only the exchange service contract has the authority to call this function.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> __exchangerCallback</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _targetContract</span><span>,</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _exchanger</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="events">Events</h4> <h5 id="exchange">Exchange</h5> <p>This event logs any new exchanges that have taken place.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Exchange</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _</span><span class="z-variable"> targetContract</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> _amount</span><span>)</span></span></code></pre><h5 id="exchangespent">ExchangeSpent</h5> <p>This event logs any new exchange that have taken place and have been spent immediately.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ExchangeSpent</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _targetContract</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> _amount</span><span>)</span></span></code></pre><h3 id="receiver-interface">Receiver Interface</h3> <p>This interface must be inherited by a ERC20 token contract that wants to receive exchanged tokens.</p> <h4 id="storage-variables-1">Storage Variables</h4> <h5 id="exchangesrecieved">exchangesRecieved</h5> <p>This mapping stores the number of tokens received in terms of another token, along with its address. Every time more tokens are exchanged the integer value is incremented consequently. This mapping acts as a record to denote which tokens do this contract holds apart from its own.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">mapping</span><span> (</span><span class="z-support"> address</span><span class="z-keyword"> =&gt;</span><span class="z-support"> uint</span><span> )</span><span class="z-storage z-type"> private</span><span> exchnagesReceived</span><span>;</span></span></code></pre><h4 id="methods-1">Methods</h4> <p>NOTE: Callers MUST handle false from returns (bool success). Callers MUST NOT assume that false is never returned!</p> <h5 id="targetexchangecallback">__targetExchangeCallback</h5> <p>This function is called by the intermediate exchange service contract. This function should add <code>_amount</code> tokens of the target contract to the exchangers address for exchange to be completed successfully.</p> <p>NOTE: It is required that only the exchange service contract has the authority to call this function.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> __targetExchangeCallback</span><span> (</span><span class="z-support">uint</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h5 id="targetexchangeandspendcallback">__targetExchangeAndSpendCallback</h5> <p>This function is called by the intermediate exchange service contract. This function should add <code>_amount</code> tokens of the target contract to the exchangers address and transfer it to the <code>_to</code> address for the exchange and expenditure to be completed successfully.</p> <p>NOTE: It is required that only the exchange service contract has the authority to call this function.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> __targetExchangeAndSpendCallback</span><span> (</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _amount</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="events-1">Events</h4> <h5 id="exchange-1">Exchange</h5> <p>This event logs any new exchanges that have taken place.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Exchange</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _with</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> _amount</span><span>)</span></span></code></pre><h5 id="exchangespent-1">ExchangeSpent</h5> <p>This event logs any new exchange that have taken place and have been spent immediately.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ExchangeSpent</span><span>(</span><span class="z-support">address</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _</span><span class="z-variable"> targetContract</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _to</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> _amount</span><span>)</span></span></code></pre><h3 id="exchange-service-contract">Exchange Service Contract</h3> <p>This is an intermediate contract that provides a gateway for exchanges and expenditure. This contract uses oracles to get the authenticated exchange rates.</p> <h4 id="storage-variables-2">Storage Variables</h4> <h5 id="registeredtokens">registeredTokens</h5> <p>This array stores all the tokens that are registered for exchange. Only register tokens can participate in exchanges.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-support">address</span><span>[</span><span>]</span><span class="z-storage z-type"> private</span><span> registeredTokens</span><span>;</span></span></code></pre><h4 id="methods-2">Methods</h4> <h5 id="registertoken">registerToken</h5> <p>This function is called by the owner of the token contract to get it’s tokens registered. It takes the address of the token as the parameter and return boolean <code>success</code>.</p> <p>NOTE: Before any exchange it must be ensured that the token is registered.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> registerToken</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _token</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h5 id="exchangetoken-1">exchangeToken</h5> <p>This function is called by the token holder who wants to exchange his token with the <code>_targetContract</code> tokens. This function queries the exchange rate, calculates the converted amount, calls <code>__exchangerCallback</code> and calls the <code>__targetExchangeCallback</code>. It takes address of the target contract and amount to exchange as parameter and returns boolean <code>success</code> and amount credited.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> exchangeToken</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _targetContract</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _from</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>,</span><span class="z-support"> uint</span><span class="z-variable"> creditedAmount</span><span>)</span></span></code></pre><h5 id="exchangeandspend-1">exchangeAndSpend</h5> <p>This function is called by the token holder who wants to exchange his token with the <code>_targetContract</code> tokens. This function queries the exchange rate, calculates the converted amount, calls <code>__exchangerCallback</code> and calls the <code>__targetExchangeAndSpendCallback</code>. It takes address of the target contract and amount to exchange as parameter and returns boolean <code>success</code> and amount credited.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> exchangeAndSpend</span><span>(</span><span class="z-support">address</span><span class="z-variable z-parameter z-function"> _targetContract</span><span>,</span><span class="z-support"> uint</span><span class="z-variable z-parameter z-function"> _amount</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _from</span><span>,</span><span class="z-support"> address</span><span class="z-variable z-parameter z-function"> _to</span><span>)</span><span class="z-storage z-type"> public</span><span class="z-keyword"> returns</span><span>(</span><span class="z-support">bool</span><span class="z-variable"> success</span><span>)</span></span></code></pre><h4 id="events-2">Events</h4> <h5 id="exchanges">Exchanges</h5> <p>This event logs any new exchanges that have taken place.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> Exchange</span><span>(</span><span class="z-support"> address</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _by</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> _value</span><span> ,</span><span class="z-support">address</span><span class="z-variable"> _target</span><span> )</span></span></code></pre><h5 id="exchangeandspent">ExchangeAndSpent</h5> <p>This event logs any new exchange that have taken place and have been spent immediately.</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">event</span><span class="z-entity z-name"> ExchangeAndSpent</span><span> (</span><span class="z-support"> address</span><span class="z-variable"> _from</span><span>, </span><span class="z-support">address</span><span class="z-variable"> _by</span><span>, </span><span class="z-support">uint</span><span class="z-variable"> _value</span><span> ,</span><span class="z-support">address</span><span class="z-variable"> _target</span><span> ,</span><span class="z-support">address</span><span class="z-variable"> _to</span><span>)</span></span></code></pre><h3 id="diagramatic-explanation">Diagramatic Explanation</h3> <h4 id="exchanging-tokens">Exchanging Tokens</h4> <p><img src="https://wg-eips.ritovision.com/823/./assets/eip-823-token-exchange-standard-visual-representation-1.png" alt="token-exchange-standard-visual-representation-1" /></p> <p>NOTE: After the successful exchange the contract on right owns some tokens of the contract on the left.</p> <h4 id="exchanging-and-spending-tokens">Exchanging And Spending Tokens</h4> <p><img src="https://wg-eips.ritovision.com/823/./assets/eip-823-token-exchange-standard-visual-representation-2.png" alt="token-exchange-standard-visual-representation-2" /></p> <p>NOTE: After the successful exchange the contract on right owns some tokens of the contract on the left.</p> <h2 id="rationale">Rationale</h2> <p>Such a design provides a consistent exchange standard applicable to all ERC20 tokens that follow it. The primary advantage for of this strategy is that the exchanged tokens will not be lost. They can either be spent or preserved. Token convert face a major drawback of destroying tokens after conversion. This mechanism treats tokens like conventional currency where tokens are not destroyed but are stored.</p> <h2 id="backward-compatibility">Backward Compatibility</h2> <p>This proposal is fully backward compatible. Tokens extended by this proposal should also be following ERC20 standard. The functionality of ERC20 standard should not be affected by this proposal but will provide additional functionality to it.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-12-30T00:00:00+00:00 2026-02-11T14:49:27+00:00 Wei Tanghttps://github.com/sorpaas https://wg-eips.ritovision.com/1702/ <h2 id="simple-summary">Simple Summary</h2> <p>Introduce account versioning for smart contracts so upgrading the VM or introducing new VMs can be easier.</p> <h2 id="abstract">Abstract</h2> <p>This defines a method of hard forking while maintaining the exact functionality of existing account by allowing multiple versions of the virtual machines to execute in the same block. This is also useful to define future account state structures when we introduce the on-chain WebAssembly virtual machine.</p> <h2 id="motivation">Motivation</h2> <p>By allowing account versioning, we can execute different virtual machine for contracts created at different times. This allows breaking features to be implemented while making sure existing contracts work as expected.</p> <p>Note that this specification might not apply to all hard forks. We have emergency hard forks in the past due to network attacks. Whether they should maintain existing account compatibility should be evaluated in individual basis. If the attack can only be executed once against some particular contracts, then the scheme defined here might still be applicable. Otherwise, having a plain emergency hard fork might still be a good idea.</p> <h2 id="specification">Specification</h2> <h3 id="account-state">Account State</h3> <p>Re-define account state stored in the world state trie to have 5 items: <code>nonce</code>, <code>balance</code>, <code>storageRoot</code>, <code>codeHash</code>, and <code>version</code>. The newly added field <code>version</code> is a 256-bit <strong>scalar</strong>. We use the definition of "scalar" from Yellow Paper. Note that this is the same type as <code>nonce</code> and <code>balance</code>, and it is equivalent to a RLP variable-sized byte array with no leading zero, of maximum length 32.</p> <p>When <code>version</code> is zero, the account is RLP-encoded with the first 4 items. When <code>version</code> is not zero, the account is RLP-encoded with 5 items.</p> <p>Account versions can also optionally define additional account state RLP fields, whose meaning are specified through its <code>version</code> field. In those cases, the parsing strategy is defined in "Additional Fields in Account State RLP" section.</p> <h3 id="contract-execution">Contract Execution</h3> <p>When fetching an account code from state, we always fetch the associated version field together. We refer to this as the <em>code's version</em> below. The code of the account is always executed in the <em>code's version</em>.</p> <p>In particular, this means that for <code>DELEGATECALL</code> and <code>CALLCODE</code>, the version of the execution call frame is the same as delegating/receiving contract's version.</p> <h3 id="contract-deployment">Contract Deployment</h3> <p>In Ethereum, a contract has a deployment method, either by a contract creation transaction, or by another contract. If we regard this deployment method a contract's <em>parent</em>, then we find them forming a family of contracts, with the <em>root</em> being a contract creation transaction.</p> <p>We let a family of contracts to always have the same <code>version</code>. That is, <code>CREATE</code> and <code>CREATE2</code> will always deploy contract that has the same <code>version</code> as the <em>code's version</em>.</p> <p>In other words, <code>CREATE</code> and <code>CREATE2</code> will execute the init code using the current <em>code's version</em>, and deploy the contract of the current <em>code's version</em>. This holds even if the to-be-deployed code is empty.</p> <h3 id="validation">Validation</h3> <p>A new phrase, <em>validation</em> is added to contract deployment (by <code>CREATE</code> / <code>CREATE2</code> opcodes, or by contract creation transaction). When <code>version</code> is <code>0</code>, the phrase does nothing and always succeeds. Future VM versions can define additional validation that has to be passed.</p> <p>If the validation phrase fails, deployment does not proceed and return out-of-gas.</p> <h3 id="contract-creation-transaction">Contract Creation Transaction</h3> <p>Define <code>LATEST_VERSION</code> in a hard fork to be the latest supported VM version. A contract creation transaction is always executed in <code>LATEST_VERSION</code> (which means the <em>code's version</em> is <code>LATEST_VERSION</code>), and deploys contracts of <code>LATEST_VERSION</code>. Before a contract creation transaction is executed, run <em>validation</em> on the contract creation code. If it does not pass, return out-of-gas.</p> <h3 id="precompiled-contract-and-externally-owned-address">Precompiled Contract and Externally-owned Address</h3> <p>Precompiled contracts and externally-owned addresses do not have <code>version</code>. If a message-call transaction or <code>CALL</code> / <code>CALLCODE</code> / <code>STATICCALL</code> / <code>DELEGATECALL</code> touches a new externally-owned address or a non-existing precompiled contract address, it is always created with <code>version</code> field being <code>0</code>.</p> <h3 id="additional-fields-in-account-state-rlp">Additional Fields in Account State RLP</h3> <p>In the future we may need to associate more information into an account, and we already have some EIPs that define new additional fields in the account state RLP. In this section, we define the parsing strategy when additional fields are added.</p> <ul> <li>Check the RLP list length, if it is 4, then set account version to <code>0</code>, and do not parse any additional fields.</li> <li>If the RLP list length more than 4, set the account version to the scalar at position <code>4</code> (counting from <code>0</code>). <ul> <li>Check version specification for the number of additional fields defined <code>N</code>, if the RLP list length is not equal to <code>5 + N</code>, return parse error.</li> <li>Parse RLP position <code>5</code> to <code>4 + N</code> as the meaning specified in additional fields.</li> </ul> </li> </ul> <h2 id="extensions">Extensions</h2> <p>In relation to the above "Specification" section, we have defined the base account versioning layer. The base account versioning layer is already useful by itself and can handle most EVM improvements. Below we define two specifications that can be deployed separately, which improves functionality of base layer account versioning.</p> <p>Note that this section is provided only for documentation purpose. When "enabling EIP-1702", those extensions should not be enabled unless the extension specification is also included.</p> <ul> <li><a rel="external" href="https://corepaper.org/ethereum/compatibility/versioning/#extensions-for-state-based-account-versioning">44-VERTXN: Account Versioning Extension for Contract Creation Transaction</a></li> <li><a rel="external" href="https://corepaper.org/ethereum/compatibility/versioning/#create-and-create2-extension">45-VEROP: Account Versioning Extension for CREATE and CREATE2</a></li> </ul> <h2 id="usage-template">Usage Template</h2> <p>This section defines how other EIPs might use this account versioning specification. Note that currently we only define the usage template for base layer.</p> <p>Account versioning is usually applied directly to a hard fork meta. EIPs in the hard fork are grouped by the virtual machine type, for example, EVM and eWASM. For each of them, we define:</p> <ul> <li><strong>Version</strong>: a non-zero scalar less than <code>2^256</code> that uniquely identifies this version. Note that it does not need to be sequential.</li> <li><strong>Parent version</strong>: the base that all new features derived from. With parent version of <code>0</code> we define the base to be legacy VM. Note that once a version other than <code>0</code> is defined, the legacy VM's feature set must be frozen. When defining an entirely new VM (such as eWASM), parent version does not apply.</li> <li><strong>Features</strong>: all additional features that are enabled upon this version.</li> </ul> <p>If a meta EIP includes EIPs that provide additional account state RLP fields, we also define:</p> <ul> <li><strong>Account fields</strong>: all account fields up to the end of this meta EIP, excluding the basic 5 fields (<code>nonce</code>, <code>balance</code>, <code>storageRoot</code>, <code>codeHash</code> and <code>version</code>). If EIPs included that are specific to modifying account fields do not modify VM execution logic, it is recommended that we specify an additional version whose execution logic is the same as previous version, but only the account fields are changed.</li> </ul> <h2 id="rationale">Rationale</h2> <p>This introduces account versioning via a new RLP item in account state. The design above gets account versioning by making the contract <em>family</em> always have the same version. In this way, versions are only needed to be provided by contract creation transaction, and there is no restrictions on formats of code for any version. If we want to support multiple newest VMs (for example, EVM and WebAssembly running together), then this will requires extensions such as 44-VERTXN and 45-VEROP.</p> <p>Alternatively, account versioning can also be done through:</p> <ul> <li><strong><a rel="external" href="https://corepaper.org/ethereum/compatibility/versioning/#prefix-based-account-versioning">26-VER</a></strong> and <strong><a rel="external" href="https://corepaper.org/ethereum/compatibility/forward/">40-UNUSED</a></strong>: This makes an account's versioning solely dependent on its code header prefix. If with only 26-VER, it is not possible to certify any code is valid, because current VM allows treating code as data. This can be fixed by 40-UNUSED, but the drawback is that it's potentially backward incompatible.</li> <li><strong>EIP-1891</strong>: Instead of writing version field into account RLP state, we write it in a separate contract. This can accomplish the same thing as this EIP and potentially reduces code complexity, but the drawback is that every code execution will require an additional trie traversal, which impacts performance.</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Account versioning is fully backwards compatible, and it does not change how current contracts are executed.</p> <h2 id="discussions">Discussions</h2> <h3 id="performance">Performance</h3> <p>Currently nearly all full node implementations uses config parameters to decide which virtual machine version to use. Switching virtual machine version is simply an operation that changes a pointer using a different set of config parameters. As a result, this scheme has nearly zero impact to performance.</p> <h3 id="webassembly">WebAssembly</h3> <p>This scheme can also be helpful when we deploy on-chain WebAssembly virtual machine. In that case, WASM contracts and EVM contracts can co-exist and the execution boundary and interaction model are clearly defined as above.</p> <h2 id="test-cases-and-implementations">Test Cases and Implementations</h2> <p>To be added.</p> <h2 id="references">References</h2> <p>The source of this specification can be found at <a rel="external" href="https://corepaper.org/ethereum/compatibility/versioning/#state-based-account-versioning">43-VER</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-12-16T00:00:00+00:00 2026-02-11T14:48:25+00:00 ligiligi@ligi.de https://wg-eips.ritovision.com/801/ <h2 id="simple-summary">Simple Summary</h2> <p>A standard interface for canary contracts.</p> <h2 id="abstract">Abstract</h2> <p>The following standard allows the implementation of canaries within contracts. This standard provides basic functionality to check if a canary is alive, keeping the canary alive and optionally manage feeders.</p> <h2 id="motivation">Motivation</h2> <p>The canary can e.g. be used as a <a rel="external" href="https://en.wikipedia.org/wiki/Warrant_canary">warrant canary</a>. A standard interface allows other applications to easily interface with canaries on Ethereum - e.g. for visualizing the state, automated alarms, applications to feed the canary or contracts (e.g. insurance) that use the state.</p> <h2 id="specification">Specification</h2> <h3 id="methods">Methods</h3> <h4 id="isalive">isAlive()</h4> <p>Returns if the canary was fed properly to signal e.g. that no warrant was received.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> isAlive</span><span>(</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">bool</span><span class="z-variable"> alive</span><span>)</span></span></code></pre><h4 id="getblockofdeath">getBlockOfDeath()</h4> <p>Returns the block the canary died. Throws if the canary is alive.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getBlockOfDeath</span><span>(</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint256</span><span class="z-variable"> block</span><span>)</span></span></code></pre><h4 id="gettype">getType()</h4> <p>Returns the type of the canary:</p> <ul> <li><code>1</code> = Simple (just the pure interface as defined in this ERC)</li> <li><code>2</code> = Single feeder (as defined in ERC-TBD)</li> <li><code>3</code> = Single feeder with bad food (as defined in ERC-TBD)</li> <li><code>4</code> = Multiple feeders (as defined in ERC-TBD)</li> <li><code>5</code> = Multiple mandatory feeders (as defined in ERC-TBD)</li> <li><code>6</code> = IOT (as defined in ERC-TBD)</li> </ul> <p><code>1</code> might also be used for a special purpose contract that does not need a special type but still wants to expose the functions and provide events as defined in this ERC.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-storage z-type">function</span><span class="z-entity z-name"> getType</span><span>(</span><span>)</span><span class="z-entity z-name"> constant</span><span class="z-entity z-name"> returns</span><span> (</span><span class="z-variable">uint8</span><span class="z-variable"> type</span><span>)</span></span></code></pre><h3 id="events">Events</h3> <h4 id="rip">RIP</h4> <p>MUST trigger when the contract is called the first time after the canary died.</p> <pre class="giallo z-code"><code data-lang="javascript"><span class="giallo-l"><span class="z-variable z-other">event</span><span class="z-entity z-name"> RIP</span><span>(</span><span>)</span></span></code></pre><h2 id="implementation">Implementation</h2> <p>TODO</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-11-09T00:00:00+00:00 2026-02-11T14:49:27+00:00 Jack Petersonjack@tinybike.net https://wg-eips.ritovision.com/758/ <h2 id="simple-summary">Simple Summary</h2> <p>Provide a way for external callers to be notified of completed transactions, and access the return data of functions executed when a transaction is mined.</p> <h2 id="abstract">Abstract</h2> <p>When a new transaction is submitted successfully to an Ethereum node, the node responds with the transaction's hash. If the transaction involved the execution of a contract function that returns data, the data is discarded. If the return data is state-dependent, which is common, there is no straightforward way for the caller to access or compute the return data. This EIP proposes that callers should be able to subscribe to (or poll for) completed transactions. The Ethereum node sends the return data to the caller when the transactions are sealed.</p> <h2 id="motivation">Motivation</h2> <p>External callers presently have no way of accessing return data from Ethereum, if the function was executed via <code>eth_sendTransaction</code> or <code>eth_sendRawTransaction</code> RPC request. Access to function return data is in many cases a desirable feature. Making return data available to external callers also addresses the inconsistency between internal callers, which have access to return data within the context of the transaction, and external callers, which do not. Presently, a common workaround is to log the return data, which is bad for several reasons: it contributes to chain bloat, imposes additional gas costs on the caller, and can result in unused logs being written if the externally called function involves other (internal) function calls that log their return data. While implementing the original version of this EIP, it was decided to expand this functionality slightly to allow for external callers to be notified of their completed transactions even in the case where there is <em>no</em> return data. This could be either because the method called doesn't return a value, or because the transaction is a simple transfer of value.</p> <h2 id="specification">Specification</h2> <h3 id="subscription">Subscription</h3> <p>A caller who wants to be notified when transactions of theirs complete sends an <code>eth_subscribe</code> RPC request with the first parameter <code>"completedTransaction"</code>:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eth_subscribe</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">completedTransaction</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-invalid z-illegal"> f</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">r</span><span>]</span><span>}</span></span></code></pre> <p>The <code>filter</code> parameter is a dictionary containing 3 optional named arguments: <code>from</code>, <code>to</code>, and <code>hasReturnData</code>. <code>from</code> and <code>to</code> can each either be single addresses, or a list of addresses. They are used to filter out any transactions not sent from an address in the <code>from</code> list and sent to an address in the to list. <code>hasReturnData</code> is a boolean--if it is specified and <code>true</code>, then notifications will be received only for completed transactions containing returnData.</p> <p>For example, to restrict results to contract creations originating from either of two addresses (0x3f7d39bDBf1f5cE649c194571aEd3D2BbB2F85ce or 0x7097f41F1C1847D52407C629d0E0ae0fDD24fd58):</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>filter = </span><span>{</span><span class="z-support"> &quot;</span><span class="z-support">from</span><span class="z-support">&quot;</span><span> :</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x3f7d39bDBf1f5cE649c194571aEd3D2BbB2F85ce</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x7097f41F1C1847D52407C629d0E0ae0fDD24fd58</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">to</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x0</span><span class="z-punctuation z-definition z-string">&quot;</span><span> </span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>To restrict results to method calls on contract address 0xD9Cb531aB97A652c8fC60dcF6D263fcA2F5764e9:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>filter = </span><span>{</span><span class="z-support"> &quot;</span><span class="z-support">to</span><span class="z-support">&quot;</span><span> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0xD9Cb531aB97A652c8fC60dcF6D263fcA2F5764e9</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">hasReturnData</span><span class="z-support">&quot;</span><span> :</span><span class="z-constant"> true</span><span> }</span></span></code></pre> <p>Or to be notified of any transactions submitted by this rpc client when they complete, with no further restrictions:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>filter = </span><span>{</span><span>}</span></span></code></pre> <p>After the request is received, the Ethereum node responds with a subscription ID:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000b0b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span></code></pre> <p>Suppose the caller then submits a transaction via <code>eth_sendTransaction</code> or <code>eth_sendRawTransaction</code> RPC request which has the transaction hash <code>"0x00000000000000000000000000000000000000000000000000000000deadbeef"</code>. When the transaction is sealed (mined), the Ethereum node pushes a notification to the caller. If the transaction is a method call on a contract, this will include the return value (eg. <code>"0x000000000000000000000000000000000000000000000000000000000000002a"</code>) of the called function:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eth_subscription</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">transactionHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000deadbeef</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">returnData</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000000000000000000000000002a</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">subscription</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000b0b</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The caller receives notifications about their transactions in two cases: first when a transaction is sealed, and again (with an extra <code>"removed": true</code> field) if a transaction is affected by a chain reorganization. Notifications are sent to the client for all transactions submitted from the client that are sealed <em>after</em> subscribing. If <code>from</code>, <code>to</code>, or <code>hasReturnData</code> is specified, then only those matching the filter criteria will generate notifications. As with other subscriptions, the caller can send an <code>eth_unsubscribe</code> RPC request to stop receiving push notifications:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 2</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eth_unsubscribe</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x00000000000000000000000000000b0b</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>}</span></span></code></pre><h3 id="polling">Polling</h3> <p>Push notifications require full duplex connections (i.e., websocket or IPC). Instead of subscribing, callers using HTTP send an <code>eth_newCompletedTransactionFilter</code> request:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eth_newCompletedTransactionFilter</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-invalid z-illegal">f</span><span class="z-invalid z-illegal">i</span><span class="z-invalid z-illegal">l</span><span class="z-invalid z-illegal">t</span><span class="z-invalid z-illegal">e</span><span class="z-invalid z-illegal">r</span><span>]</span><span> }</span></span></code></pre> <p>The Ethereum node responds with a filter ID:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 1</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span></span></code></pre> <p>When a transaction is submitted, the Ethereum node pushes the transaction notification, including return value, into a queue which is emptied when the caller polls using <code>eth_getFilterChanges</code>:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span><span class="z-support">&quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 2</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">method</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eth_getFilterChanges</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-support"> &quot;</span><span class="z-support">params</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0x1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>}</span></span></code></pre> <p>The node responds with an array of transaction hashes and their corresponding return data, in the order they were computed:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">jsonrpc</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2.0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">id</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> 2</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">result</span><span class="z-support">&quot;</span><span>:</span><span> [</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">transactionHash</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x00000000000000000000000000000000000000000000000000000000deadbeef</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">returnData</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0x000000000000000000000000000000000000000000000000000000000000002a</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>]</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>All transactions that were sealed <em>after</em> the initial <code>eth_newCompletedTransactionFilter</code> request are included in this array. Again, if the <code>filter</code> param is a non-empty dictionary (contains either <code>from</code>, <code>to</code>, or <code>hasReturnData</code>) then only transactions matching the filter criteria generate notifications. Note that in the polling case, there is no way for the Ethereum node to be sure that an RPC client which submits a transaction was the same as the one who created the filter, so there is no restriction based on where the transaction was submitted.</p> <h2 id="rationale">Rationale</h2> <p><a href="https://wg-eips.ritovision.com/658/">EIP-658</a> originally proposed adding return data to transaction receipts. However, return data is not charged for (as it is not stored on the blockchain), so adding it to transaction receipts could result in DoS and spam opportunities. Instead, a simple Boolean <code>status</code> field was added to transaction receipts. This modified version of EIP 658 was included in the Byzantium hard fork. While the <code>status</code> field is useful, applications often need the return data as well.</p> <p>The primary advantage of using the strategy outlined here is efficiency: no extra data needs to be stored on the blockchain, and minimal extra computational load is imposed on nodes. Although after-the-fact lookups of the return value would not be supported, this is consistent with the conventional use of return data, which are only accessible to the caller when the function returns, and are not stored for later use.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-08-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Cody BurnsdontPanic@codywburns.com https://wg-eips.ritovision.com/698/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP adds an additional opcode to the EVM which will return a finalized blocks reward value.</p> <h2 id="abstract">Abstract</h2> <p>In the EVM, the 0x40 opcodes are reserved for <code>Block Information</code>. Currently reserved opcodes are:</p> <ul> <li><code>0X40 BLOCKHASH</code></li> <li><code>0X41 COINBASE</code></li> <li><code>0X42 TIMESTAMP</code></li> <li><code>0X43 NUMBER</code></li> <li><code>0X44 DIFFICULTY</code></li> <li><code>0X45 GASLIMIT</code></li> </ul> <p>This EIP would add an additional opcode, <code>0x46 BLOCKREWARD</code>, which would return the block reward for any finalized block. The finalized block reward would include the base reward, uncle payments, and gas.</p> <h2 id="motivation">Motivation</h2> <p>Per EIP-649 ( #669 ) periodic block reward reductions/variance are now planned in the roadmap, however, this EIP is consensus system agnostic and is most useful in decentralized pool operations and for any contract that benefits from knowing a block reward payout(i.e. Merge mined tokens)</p> <h2 id="specification">Specification</h2> <p>After block <code>n</code> all clients should process opcode <code>0x46</code> as follows:</p> <ul> <li>Value: <code>0x46</code></li> <li>Mnemonic: <code>BLOCKREWARD</code></li> <li>δ:<code> 0</code> nothing removed from stack</li> <li>α:<code>1</code> block reward added to stack</li> <li>Description: <code>Get the block's reward emission</code></li> <li>GasCost: <code>G&lt;sub&gt;base&lt;/sub&gt;</code></li> </ul> <p>Where:<code>µ'&lt;sub&gt;s&lt;/sub&gt;[0] ≡ I&lt;sub&gt;HR&lt;/sub&gt;</code></p> <h2 id="rationale">Rationale</h2> <h3 id="contract-mining-pools">Contract Mining Pools</h3> <p>For distributed consensus systems(staking pools and mining pools) ad hoc groups combine resources in order to reduce variance in payouts. Broadly, pool operations function by allowing a collective of miners / stakers to verify their contribution to solving PoW or staking share by periodically submitting solutions which are representative of the miners probability of finding a true block.</p> <p>In all these schemes <code>B</code> stands for a block reward minus pool fee and <code>p</code> is a probability of finding a block in a share attempt ( <code>p=1/D</code>, where <code>D</code> is current block difficulty).</p> <p>Some common methods of mining pool payout are pay-per-share, <code>R = B * p</code>, proportional [<code>R = B * (n/N)</code> where <code>n</code> is amount of a miners shares, and <code>N</code> is amount of all shares in this round.], and pay-per-last-N-shares [<code>R = B * (n/N)</code> where miner's reward is calculated on a basis of <code>N</code> last shares, instead of all shares for the last round]. All of these methods are predicated on knowing the block reward paid for a given block. In order to provide a trust minimized solution, <code>0x46</code> can be used to call a blocks reward for computing payouts.</p> <h3 id="merge-mined-tokens">Merge mined tokens</h3> <p>Contracts could create tokens which could be variably ‘minted’ as a function of block reward by calling <code>0x46</code></p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <h3 id="currently-deployed-contracts">Currently deployed contracts</h3> <p>No impact</p> <h3 id="current-clients">Current clients</h3> <p>This EIP would be incompatible with currently deployed clients that are not able to handle <code>0x46</code> and would process all transactions and block containing the opcode as invalid.</p> <p>Implementation should occur as part of a coordinated hardfork.</p> <h2 id="implementation">Implementation</h2> <h2 id="further-reading">Further reading</h2> <p><a rel="external" href="https://en.wikipedia.org/wiki/Mining_pool">Mining Pools</a></p> <p>The Yellow Paper Appendix H. Virtual Machine Specification section H.2</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-08-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Yoichi Hiraii@yoichihirai.com https://wg-eips.ritovision.com/689/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP proposes to make contract creation fail on an account with nonempty code or non-zero nonce.</p> <h2 id="abstract">Abstract</h2> <p>Some test cases in the consensus test suite try to deploy a contract at an address already with nonempty code. Although such cases can virtually never happen on the main network before the Constantinople fork block, the test cases detected discrepancies in clients' behavior. Currently, the Yellow Paper says that the contract creation starts with the empty code and the initial nonce even in the case of address collisions. To simplify the semantics, this EIP proposes that address collisions cause failures of contract creation.</p> <h2 id="motivation">Motivation</h2> <p>This EIP has no practical relevance to the main net history, but simplifies testing and reasoning.</p> <p>This EIP has no effects after Constantinople fork because <a href="https://wg-eips.ritovision.com/86/">EIP-86</a> contains the changes proposed in this EIP. Even before the Constantinople fork, this EIP has no practical relevance because the change is visible only in case of a hash collision of keccak256.</p> <p>Regarding testing, this EIP relieves clients from supporting reversion of code overwriting.</p> <p>Regarding reasoning, this EIP establishes an invariant that non-empty code is never modified.</p> <h2 id="specification">Specification</h2> <p>If <code>block.number &gt;= 0</code>, when a contract creation is on an account with non-zero nonce or non-empty code, the creation fails as if init code execution resulted in an exceptional halt. This applies to contract creation triggered by a contract creation transaction and by CREATE instruction.</p> <h2 id="rationale">Rationale</h2> <p>It seems impractical to implement never-used features just for passing tests. Client implementations will be simpler with this EIP.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This EIP is backwards compatible on the main network.</p> <h2 id="test-cases">Test Cases</h2> <p>At least the BlockchainTest called <code>createJS\_ExampleContract\_d0g0v0\_EIP158</code> will distinguish clients that implement this EIP.</p> <h2 id="implementation">Implementation</h2> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-07-28T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/1803/ <h2 id="abstract">Abstract</h2> <p>Rename the <code>BALANCE</code>, <code>SHA3</code>, <code>NUMBER</code>, <code>GASLIMIT</code>, <code>GAS</code> and <code>INVALID</code> opcodes to reflect their true meaning.</p> <h2 id="specification">Specification</h2> <p>Rename the opcodes as follows:</p> <ul> <li><code>BALANCE</code> (<code>0x31</code>) to <code>EXTBALANCE</code> to be in line with <code>EXTCODESIZE</code>, <code>EXTCODECOPY</code> and <code>EXTCODEHASH</code></li> <li><code>SHA3</code> (<code>0x20</code>) to <code>KECCAK256</code></li> <li><code>NUMBER</code> (<code>0x43</code>) to <code>BLOCKNUMBER</code></li> <li><code>GASLIMIT</code> (<code>0x45</code>) to <code>BLOCKGASLIMIT</code> to avoid confusion with the gas limit of the transaction</li> <li><code>GAS</code> (<code>0x5a</code>) to <code>GASLEFT</code> to be clear what it refers to</li> <li><code>INVALID</code> (<code>0xfe</code>) to <code>ABORT</code> to clearly articulate when someone refers this opcode as opposed to "any invalid opcode"</li> </ul> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This has no effect on any code. It can influence what mnemonics assemblers will use.</p> <h2 id="implementation">Implementation</h2> <p>Not applicable.</p> <h2 id="references">References</h2> <p><a href="https://wg-eips.ritovision.com/6/">EIP-6</a> previously renamed <code>SUICIDE</code> (<code>0xff</code>) to <code>SELFDESTRUCT</code>. Renaming <code>SHA3</code> was previously proposed by <a rel="external" href="https://github.com/ethereum/EIPs/issues/59">EIP-59</a>.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-07-03T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic Charles Cooperhttps://github.com/charles-cooper Danno Ferrinhttps://github.com/shemnon https://wg-eips.ritovision.com/663/

Introduce additional instructions for manipulating the stack which allow accessing the stack at higher depths

<h2 id="abstract">Abstract</h2> <p>Currently, <code>SWAP*</code> and <code>DUP*</code> instructions are limited to a stack depth of 16. Introduce three new instructions, <code>SWAPN</code>, <code>DUPN</code> and <code>EXCHANGE</code> which lift this limitation and allow accessing the stack at higher depths.</p> <h2 id="motivation">Motivation</h2> <p>While the stack is 1024 items deep, easy access is only possible for the top 16 items. Supporting more local variables is possible via manually keeping them in memory or through a "stack to memory elevation" in a compiler. This can result in complex and inefficient code.</p> <p>Furthermore, implementing higher level constructs, such as functions, on top of EVM will result in a list of input and output parameters as well as an instruction offset to return to.</p> <p>The number of these arguments (or stack items) can easily exceed 16 and thus will require extra care from a compiler to lay them out in a way that all of them are still accessible.</p> <p>Lastly, swapping items besides the 1st and Nth items in the stack is very important for compilers implementing stack scheduling algorithms (the analog of register allocation for stack machines), which try to minimize stack traffic given a set of variables and usage analysis.</p> <p>Introducing <code>SWAPN</code>, <code>DUPN</code> and <code>EXCHANGE</code> will provide an option to compilers to simplify accessing deep stack items.</p> <h2 id="specification">Specification</h2> <p>We introduce three new instructions:</p> <ol> <li><code>DUPN</code> (<code>0xe6</code>)</li> <li><code>SWAPN</code> (<code>0xe7</code>)</li> <li><code>EXCHANGE</code> (<code>0xe8</code>)</li> </ol> <p>If the code is legacy bytecode, any of these instructions result in an <em>exceptional halt</em>. (<em>Note: This means no change to behaviour.</em>)</p> <p>If the code is valid EOF1, the following rules apply:</p> <ol> <li>The instructions are followed by an 8-bit immediate value, which we call <code>imm</code>, and can have a value of 0 to 255. <ol> <li>In the case of <code>DUPN</code> and <code>SWAPN</code>, we introduce the variable <code>n</code> which equals to <code>imm + 1</code>.</li> <li>In the case of <code>EXCHANGE</code>, we introduce the variable <code>n</code> which is equal to <code>(imm &gt;&gt; 4) + 1</code>, and the variable <code>m</code> which is equal to <code>(imm &amp; 0x0F) + 1</code> (i.e., the first and second nibbles of <code>imm</code>, converted to one-indexing).</li> </ol> </li> <li>Code validation is extended to check that no relative jump instruction (<code>RJUMP</code>/<code>RJUMPI</code>/<code>RJUMPV</code>) targets immediate values of <code>DUPN</code>, <code>SWAPN</code> or <code>EXCHANGE</code>.</li> <li>The stack validation algorithm of <a href="https://wg-eips.ritovision.com/5450/">EIP-5450</a> is extended: <ol> <li>Before <code>DUPN</code> if the current stack height is less than <code>n</code>, code is invalid. After <code>DUPN</code>, the stack height is incremented.</li> <li>Before <code>SWAPN</code> if the current stack height is less than <code>n + 1</code>, code is invalid. After <code>SWAPN</code>, the stack height is unchanged.</li> <li>Before <code>EXCHANGE</code> if the current stack height is less than <code>n + m + 1</code>, code is invalid. After <code>EXCHANGE</code>, the stack height is unchanged.</li> </ol> </li> <li>Execution rules: <ol> <li><code>DUPN</code>: the <code>n</code>'th stack item is duplicated at the top of the stack. (<em>Note: We use 1-based indexing here.</em>)</li> <li><code>SWAPN</code>: the <code>n + 1</code>'th stack item is swapped with the top of the stack.</li> <li><code>EXCHANGE</code>: the <code>n + 1</code>'th stack item is swapped with the <code>n + m + 1</code>'th stack item.</li> </ol> </li> </ol> <p>The gas cost for all three instructions is set at 3.</p> <h2 id="rationale">Rationale</h2> <h3 id="use-of-an-immediate-argument">Use of an immediate argument</h3> <p>Allowing dynamic selection of the arguments to swap, dup, or exchange could be used to prevent static analysis of the contents of the stack. Since static analysis is an important tool for security auditors we want to do what we can to make their jobs easier. Hence, the operands require an immediate argument that is not dynamic in nature.</p> <h3 id="eof-only">EOF-only</h3> <p>Since this instruction depends on an immediate argument encoding, it can only be enabled within EOF. In legacy bytecode that encoding could contradict jumpdest-analysis.</p> <h3 id="size-of-immediate-argument">Size of immediate argument</h3> <p>For <code>DUPN</code> and <code>SWAPN</code> a 16-bit size was considered to accommodate the full stack space of 1024 items, however:</p> <ol> <li>that would require an additional restriction/check (<code>n &lt; 1024</code>)</li> <li>the 256 depth is a large improvement over the current 16 and the overhead of an extra byte would make it less useful</li> </ol> <p>Similarly for <code>EXCHANGE</code>, the proposed scheme allows addressing of 32 items.</p> <h3 id="gas-cost">Gas cost</h3> <p>The gas cost for these operations is the same as for existing <code>DUP*</code> and <code>SWAP*</code> instructions, because they are just implemented as pointer swaps.</p> <h3 id="exchange-vs-swapn"><code>EXCHANGE</code> vs <code>SWAPN</code></h3> <p>As mentioned before, <code>EXCHANGE</code> is important to compilers implementing stack scheduling algorithms. Specifically, in the case that a stack item is scheduled to be consumed deeper in the stack (for instance, the 3rd item in the stack needs to be moved into 2nd position in order to be consumed by the next operation), that currently takes three instructions, <code>SWAP2 SWAP3 SWAP2</code>. However, in the EVM implementation, the implementation is just a pointer swap, so it could be implemented in a single instruction at no extra runtime cost to the client.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This has no effect on backwards compatibility because the opcodes were not previously allocated and the feature is only enabled in EOF.</p> <h2 id="test-cases">Test Cases</h2> <p>Given <code>stack[]</code> is a 0-based data structure, and <code>n</code>, <code>m</code> and <code>imm</code> are defined as according to the spec:</p> <ul> <li><code>DUPN imm</code> to fail validation if <code>stack_height &lt; n</code>.</li> <li><code>SWAPN imm</code> to fail validation if <code>stack_height &lt; n + 1</code>.</li> <li><code>EXCHANGE imm</code> to fail validation if <code>stack_height &lt; n + m + 1</code>.</li> <li><code>DUPN imm</code> to increment maximum stack height of a function. Validation fails if maximum stack height exceeds limit of 1023.</li> <li><code>DUPN imm</code>, <code>SWAPN imm</code>, and <code>EXCHANGE imm</code> to fail at run-time if gas available is less than 3.</li> <li><code>DUPN imm</code> should duplicate the <code>stack[n - 1]</code> item and push it to the stack</li> <li><code>SWAPN imm</code> should swap <code>stack[n]</code> with <code>stack[stack.top()]</code></li> <li><code>EXCHANGE imm</code> should swap <code>stack[n]</code> with <code>stack[n + m]</code>.</li> </ul> <h2 id="security-considerations">Security Considerations</h2> <p>The authors are not aware of any additional risks introduced here. The EVM stack is fixed at 1024 items and most implementations keep that in memory at all times. This change will increase the number of stack items accessible via single instruction.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-05-17T00:00:00+00:00 2026-02-11T14:48:25+00:00 Richard Moorehttps://github.com/ricmoo https://wg-eips.ritovision.com/634/

Profiles for ENS resolvers to store arbitrary text key/value pairs.

<h2 id="abstract">Abstract</h2> <p>This EIP defines a resolver profile for ENS that permits the lookup of arbitrary key-value text data. This allows ENS name holders to associate e-mail addresses, URLs and other informational data with a ENS name.</p> <h2 id="motivation">Motivation</h2> <p>There is often a desire for human-readable metadata to be associated with otherwise machine-driven data; used for debugging, maintenance, reporting and general information.</p> <p>In this EIP we define a simple resolver profile for ENS that permits ENS names to associate arbitrary key-value text.</p> <h2 id="specification">Specification</h2> <h3 id="resolver-profile">Resolver Profile</h3> <p>A new resolver interface is defined, consisting of the following method:</p> <pre class="giallo z-code"><code data-lang="solidity"><span class="giallo-l"><span class="z-storage z-type">interface</span><span class="z-entity z-name"> IERC634</span><span> {</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @notice</span><span class="z-comment"> Returns the text data associated with a key for an ENS name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> node</span><span class="z-comment"> A nodehash for an ENS name</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @param</span><span class="z-variable z-other"> key</span><span class="z-comment"> A key to lookup text data for</span></span> <span class="giallo-l"><span class="z-comment"> ///</span><span class="z-storage z-type"> @return</span><span class="z-variable z-other"> The</span><span class="z-comment"> text data</span></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> text</span><span>(</span><span class="z-support">bytes32</span><span class="z-variable"> node</span><span>,</span><span class="z-support"> string</span><span class="z-variable"> key</span><span>)</span><span class="z-storage z-type"> view</span><span class="z-keyword"> returns</span><span> (</span><span class="z-support">string</span><span class="z-variable"> text</span><span>)</span><span>;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>The <a href="https://wg-eips.ritovision.com/165/">EIP-165</a> interface ID of this interface is <code>0x59d1d43c</code>.</p> <p>The <code>text</code> data may be any arbitrary UTF-8 string. If the key is not present, the empty string must be returned.</p> <h3 id="global-keys">Global Keys</h3> <p>Global Keys must be made up of lowercase letters, numbers and the hyphen (-).</p> <ul> <li><strong>avatar</strong> - a URL to an image used as an avatar or logo</li> <li><strong>description</strong> - A description of the name</li> <li><strong>display</strong> - a canonical display name for the ENS name; this MUST match the ENS name when its case is folded, and clients should ignore this value if it does not (e.g. <code>"ricmoo.eth"</code> could set this to <code>"RicMoo.eth"</code>)</li> <li><strong>email</strong> - an e-mail address</li> <li><strong>keywords</strong> - A list of comma-separated keywords, ordered by most significant first; clients that interpresent this field may choose a threshold beyond which to ignore</li> <li><strong>mail</strong> - A physical mailing address</li> <li><strong>notice</strong> - A notice regarding this name</li> <li><strong>location</strong> - A generic location (e.g. <code>"Toronto, Canada"</code>)</li> <li><strong>phone</strong> - A phone number as an E.164 string</li> <li><strong>url</strong> - a website URL</li> </ul> <h3 id="service-keys">Service Keys</h3> <p>Service Keys must be made up of a <em>reverse dot notation</em> for a namespace which the service owns, for example, DNS names (e.g. <code>.com</code>, <code>.io</code>, etc) or ENS name (i.e. <code>.eth</code>). Service Keys must contain at least one dot.</p> <p>This allows new services to start using their own keys without worrying about colliding with existing services and also means new services do not need to update this document.</p> <p>The following services are common, which is why recommendations are provided here, but ideally a service would declare its own key.</p> <ul> <li><strong>com.github</strong> - a GitHub username</li> <li><strong>com.peepeth</strong> - a Peepeth username</li> <li><strong>com.linkedin</strong> - a LinkedIn username</li> <li><strong>com.twitter</strong> - a Twitter username</li> <li><strong>io.keybase</strong> - a Keybase username</li> <li><strong>org.telegram</strong> - a Telegram username</li> </ul> <p>This technique also allows for a service owner to specify a hierarchy for their keys, such as:</p> <ul> <li><strong>com.example.users</strong></li> <li><strong>com.example.groups</strong></li> <li><strong>com.example.groups.public</strong></li> <li><strong>com.example.groups.private</strong></li> </ul> <h3 id="legacy-keys">Legacy Keys</h3> <p>The following keys were specified in earlier versions of this EIP, which is still in draft.</p> <p>Their use is not likely very wide, but applications attempting maximal compatibility may wish to query these keys as a fallback if the above replacement keys fail.</p> <ul> <li><strong>vnd.github</strong> - a GitHub username (renamed to <code>com.github</code>)</li> <li><strong>vnd.peepeth</strong> - a peepeth username (renamced to <code>com.peepeth</code>)</li> <li><strong>vnd.twitter</strong> - a twitter username (renamed to <code>com.twitter</code>)</li> </ul> <h2 id="rationale">Rationale</h2> <h3 id="application-specific-vs-general-purpose-record-types">Application-specific vs general-purpose record types</h3> <p>Rather than define a large number of specific record types (each for generally human-readable data) such as <code>url</code> and <code>email</code>, we follow an adapted model of DNS's <code>TXT</code> records, which allow for a general keys and values, allowing future extension without adjusting the resolver, while allowing applications to use custom keys for their own purposes.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>Not applicable.</p> <h2 id="security-considerations">Security Considerations</h2> <p>None.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-04-25T00:00:00+00:00 2026-02-11T14:49:27+00:00 Greg Colvingreg@colvin.org https://wg-eips.ritovision.com/616/ <h2 id="abstract">ABSTRACT</h2> <p>A proposal to provide Single Instruction Multiple Data types and operations for the Ethereum Virtual Machine, making full use of the 256-bit wide EVM stack items, and offering substantial performance gains for both vector and scalar operations.</p> <h2 id="motivation">MOTIVATION</h2> <p>Most all modern CPUs include SIMD hardware that operates on wide registers of data, applying a Single Instruction to Multiple Data lanes in parallel, where lanes divide a register into a vector of scalar elements of equal size. This model is an excellent fit for the wide stack items of the EVM, offering substantial performance boosts for operations that can be expressed as parallel operations on vectors of scalars. For some examples, a brief literature search finds SIMD speedups of</p> <ul> <li>up to 7X for <a rel="external" href="http://keccak.noekeon.org/sw_performance.html">SHA-512</a></li> <li>4X for <a rel="external" href="https://link.springer.com/chapter/10.1007/3-540-45439-X_16">elliptic curve scalar multiplication</a></li> <li>3X to 4X for <a rel="external" href="https://github.com/minio/blake2b-simd">BLAKE2b</a></li> <li>up to 3X for <a rel="external" href="https://software.intel.com/en-us/articles/improving-openssl-performance">OpenSSL</a></li> <li>2X to 3X for <a rel="external" href="http://ieee-hpec.org/2013/index_htm_files/24-Simd-acceleration-Pabbuleti-2886999.pdf">elliptic curve modular multiplication</a></li> <li>1.7X to 1.9X for <a rel="external" href="https://github.com/minio/sha256-simd">SHA-256</a></li> <li>1.3X for <a rel="external" href="https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.738.1218&amp;rep=rep1&amp;type=pdf">RSA encryption</a></li> </ul> <h2 id="specification">SPECIFICATION</h2> <h3 id="encoding">Encoding</h3> <p>We propose a simple encoding of SIMD operations as extended two-byte codes. The first byte is the opcode, and the second byte is the SIMD type: scalar type, lane width, and number of elements.</p> <table><thead><tr><th>N bits</th><th>Field</th></tr></thead><tbody> <tr><td>8</td><td>opcode</td></tr> <tr><td>1</td><td>scalar type: 0 = unsigned integer, 1 = IEEE float</td></tr> <tr><td>1</td><td>reserved: 0</td></tr> <tr><td>2</td><td>lane width: log base 2 of the number of bytes, as an MSB first integer</td></tr> <tr><td>1</td><td>reserved: 0</td></tr> <tr><td>3</td><td>element count: log base 2 of the number of lanes, as an MSB first integer</td></tr> </tbody></table> <p>Thus we can specify SIMD types with unsigned integer lanes from 8 to 64 bits in vectors of 32 to 2 lanes, respectively. Floating point lanes however support only 32- and 64-bit IEEE floating point. And a type of <em>0x7F</em> represents a normal 256-bit EVM integer.</p> <p><em>Note that when the element count is one the operation is on one scalar, so this specification also provides for native operations on single scalars of native sizes.</em></p> <p><em>Note that floating point operations are <strong>not</strong> proposed for inclusion in the initial release, but we considered it important to reserve code space for possible future expansion.</em></p> <h3 id="semantics">Semantics</h3> <p>We define the following extended versions of the EVM's arithmetic, logic, and comparison operations. As with the normal versions, they consume their arguments from the stack and place their results on the stack, except that their arguments are vectors rather than scalars.</p> <table><thead><tr><th>lo\hi</th><th>B</th><th>C</th></tr></thead><tbody> <tr><td>0</td><td></td><td>XLT</td></tr> <tr><td>1</td><td>XADD</td><td>XGT</td></tr> <tr><td>2</td><td>XMUL</td><td>XSLT</td></tr> <tr><td>3</td><td>XSUB</td><td>XSGT</td></tr> <tr><td>4</td><td>XDIV</td><td>XEQ</td></tr> <tr><td>5</td><td>XSDIV</td><td>XISZERO</td></tr> <tr><td>6</td><td>XMOD</td><td>XAND</td></tr> <tr><td>7</td><td>XSMOD</td><td>XOR</td></tr> <tr><td>8</td><td></td><td>XXOR</td></tr> <tr><td>9</td><td></td><td>XNOT</td></tr> <tr><td>A</td><td></td><td>XINDEX</td></tr> <tr><td>B</td><td></td><td>XSHL</td></tr> <tr><td>C</td><td></td><td>XSHR</td></tr> <tr><td>D</td><td></td><td>XSAR</td></tr> <tr><td>E</td><td>XCAST</td><td>XROL</td></tr> <tr><td>F</td><td>XSHUFFLE</td><td>XROR</td></tr> </tbody></table> <p>Except for XSHUFFLE, XCAST, and XINDEX all the extended operations on unsigned integer values have the same semantics as the corresponding operations for codes 01 through 1F, except that the modulus varies by scalar type and the operations are applied pair-wise to the elements of the source operands to compute the destination elements. <em>The source operands must have the same element type and number of elements.</em> E.g.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH uint8[1, 2, 3]</span></span> <span class="giallo-l"><span>PUSH uint8[4, 5, 6]</span></span> <span class="giallo-l"><span>XADD</span></span></code></pre> <p>leaves</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>uint8[5, 7, 9]</span></span></code></pre> <p>on the stack.</p> <p>XSHUFFLE takes two vectors on the stack: a vector to permute and a permutation mask. E.g.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH uint64[4, 5, 6, 0]</span></span> <span class="giallo-l"><span>PUSH uint8[2, 0, 1, 3]</span></span> <span class="giallo-l"><span>SHUFFLE</span></span></code></pre> <p>leaves</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>uint64[6, 4, 5 , 0]</span></span></code></pre> <p>on the stack. The mask must have integral type, and the same number of elements as the source vector.</p> <p>The second byte of the XCAST opcode is applied to the item on the stack to create a new vector of the specified type. Elements are converted according to the usual C conventions, missing elements are set to zero, and extra elements are discarded. If the stack item is not a vector it is converted to a vector by taking its bits least-significant-bit first and copying them into the corresponding bits of each element, least-significant-element first. Again, excess data is truncated and missing data is 0-filled. Vectors are converted to 256-bit EVM integers via the reverse process., with elements that are floating point NANs normalized to all bits on.</p> <p><em>Note that MLOAD and MSTORE are valid only on 256-bit EVM integers. For SIMD vectors an XCAST is needed after a load and before a store to convert vectors to and from 256-bit integers.</em></p> <p>XINDEX has the same semantics as BYTE, except that individual elements of the vector are indexed.</p> <p>Floating point values follow IEEE 754 semantics. Since those are not defined for shifting and rotating those operations are defined here as having no effect.</p> <p>Extended operations other than XSHUFFLE and XCAST are only valid on vectors of the same SIMD type. This can be validated at contract creation time, or else checked at runtime.</p> <h3 id="subroutines">Subroutines</h3> <p>If <a rel="external" href="https://github.com/ethereum/EIPs/pull/187">EIP-187</a> is accepted a type-safe syntax for declaring subroutines taking vector arguments will be needed.</p> <ul> <li><code>BEGINSUBX n_args, arg_types... n_results, result_types...</code> marks the <strong>single</strong> entry to a subroutine. <code>n_args</code> items are taken off of the stack at entry to, and <code>n_results</code> items are placed on the stack at return from the subroutine. <code>n_args</code> and <code>n_results</code> are given as one immediate byte each. The <code>arg_types</code> and <code>result_types</code> are given in the same encoding as second byte of the SIMD opcodes, and must match the values on the stack. The bytecode for a subroutine ends at the next <code>BEGINSUB</code>, <code>BEGINSUBX</code> or <code>BEGINDATA</code> instruction or at the end of the bytecode.</li> </ul> <h2 id="rationale">RATIONALE</h2> <p>Currently, the lowest common denominator for SIMD hardware (e.g. Intel SSE2 and ARM Neon) is 16-byte registers supporting integer lanes of 1, 2, 4, and 8 bytes, and floating point lanes of 4 and 8 bytes. More recent SIMD hardware (e.g. Intel AVX) supports 32-byte registers, and EVM stack items are also 32 bytes wide. The limits above derive from these numbers, assuring that EVM code is within the bounds of available hardware - and the reserved bits provide room for growth.</p> <p>For most modern languages (including Rust, Python, Go, Java, and C++) compilers can do a good job of generating SIMD code for parallelizable loops, and/or there are intrinsics or libraries available for explicit access to SIMD hardware. So a portable software implementation will likely provide good use of the hardware on most platforms, and intrinsics or libraries can be used as available and needed. Thus we can expect these operations to take about the same (or for 256-bit vectors on 128-bit hardware up to twice) the time to execute regardless of element size or number of elements.</p> <h3 id="gas">Gas</h3> <p>One motivation for these operations, besides taking full advantage of the hardware, is assigning lower gas costs for operations on smaller scalars.</p> <p>On a machine with 64-bit registers the standard algorithms from Knuth's <a rel="external" href="https://library.aceondo.net/ebooks/Computer_Science/algorithm-the_art_of_computer_programming-knuth.pdf">Art of Computer Programming</a> require 32-bit digits, using the upper half of a register for overflows, so for 256-bit values N=8 digits are needed, and for 64-bit values N=2 digits are needed. The cycle counts for these algorithms are:</p> <table><thead><tr><th>operation</th><th>cycles</th><th>N = 2</th><th>N = 4</th><th>N = 8</th></tr></thead><tbody> <tr><td>add</td><td>10 <em>N</em> + 6</td><td>26</td><td>46</td><td>86</td></tr> <tr><td>subtract</td><td>12 <em>N</em> + 3</td><td>27</td><td>51</td><td>99</td></tr> <tr><td>multiply</td><td>28 <em>N</em>**2 + 11 <em>N</em> + 3</td><td>137</td><td>495</td><td>1883</td></tr> <tr><td>divide</td><td>15 <em>N</em>**2 + 119 <em>N</em> + 111</td><td>409</td><td>827</td><td>2023</td></tr> </tbody></table> <p>The remaining operations are of about the same complexity as addition and subtraction, or less. Given that JUMPDEST is a no-op, and is assigned a gas price of 1, this can be taken as the overhead of the interpreter. All of the arithmetic operations are assigned the same gas price of 5, for a remaining runtime of 4. The interpreter loop itself takes about 6 to 8 C instructions, so ADD and SUB are reasonably priced, but MUL is some 5 to 21 times slower than ADD or SUB, and DIV is some 15 to 23 times slower, so they are clearly mispriced.</p> <p>By comparison, on most <a rel="external" href="https://software.intel.com/sites/landingpage/IntrinsicsGuide">Intel</a> and <a rel="external" href="https://developer.arm.com/docs/100166/latest/programmers-model/instruction-set-summary/table-of-processor-instructions">ARM</a> SIMD units instructions take approximately the following cycle counts, independent of register width.</p> <table><thead><tr><th>operation</th><th>Intel cycles</th><th>ARM cycles</th><th>gas</th></tr></thead><tbody> <tr><td>add</td><td>.5</td><td>1</td><td>1</td></tr> <tr><td>subtract</td><td>.5</td><td>1</td><td>1</td></tr> <tr><td>multiply</td><td>2</td><td>1</td><td>1</td></tr> <tr><td>divide</td><td>10</td><td>12</td><td>2</td></tr> </tbody></table> <p>Since all but the divide operation take fewer cycles than the interpreter overhead they are assigned the minimal cost of 1. Division takes slightly more, and is assigned a cost of 2.</p> 2017-03-23T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/233/ <h2 id="abstract">Abstract</h2> <p>To describe the formal process of preparing and activating hard forks.</p> <h2 id="motivation">Motivation</h2> <p>Today discussions about hard forks happen at various forums and sometimes in ad-hoc ways.</p> <h2 id="specification">Specification</h2> <p>A Meta EIP should be created and merged as a <em>Draft</em> as soon as a new hard fork is planned.</p> <p>This EIP should contain:</p> <ul> <li>the desired codename of the hard fork,</li> <li>activation block number once decided</li> <li>a timeline section</li> <li>an EIPs to include section</li> <li>the <strong>Requires</strong> header should point to the previous hard fork meta EIP.</li> </ul> <p>The draft shall be updated with summaries of the decisions around the hard fork.</p> <h3 id="timeline">Timeline</h3> <p>Once a timeline with key dates is agreed upon for other crucial dates. The basic outline of a hardfork timeline should include:</p> <ul> <li>Hard deadline to accept proposals for this hard fork</li> <li>Soft deadline for major client implementations</li> <li>Projected date for testnet network upgrade</li> <li>Projected date for mainnet upgrade (the activation block number / projected date for this block)</li> </ul> <h3 id="eip-inclusion-process">EIP Inclusion Process</h3> <p>Anyone that wishes to propose a Core EIP for the hard fork should make a PR against the Meta EIP representing the hard fork. The EIP must be published as at least <code>Draft</code>. It enters the <em>Proposed EIPs</em> section, along with at least one person who is a point of contact for wanting to include the EIP.</p> <p>EIPs can move states by discussion done on the "<a rel="external" href="https://github.com/ethereum/pm/">All Core Devs Meetings</a>":</p> <ul> <li>If accepted for a hard fork, the EIP should be moved to the <em>Accepted EIPs</em> section. If the EIP has major client implementations and no security issues by the timeline date, it is scheduled for inclusion.</li> <li>If rejected from a hard fork, the EIP should be moved to the <em>Rejected EIPs</em> section.</li> <li>Once the EIPs in the <em>Accepted EIPs</em> section have successfully launched on a testnet roll out, they are moved to the <em>Included EIPs</em> section.</li> </ul> <hr /> <p>The Meta EIP representing the hard fork should move in to the <code>Accepted</code> state once the changes are frozen (i.e. all referenced EIPs are in the <code>Accepted</code> state) and in to the <code>Final</code> state once the hard fork has been activated.</p> <h2 id="template">Template</h2> <p>A template for the <a href="https://wg-eips.ritovision.com/1679/">Istanbul Hardfork Meta 1679</a> is included below (<a href="https://wg-eips.ritovision.com/1679/">source file on GitHub</a>):</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{% raw %}</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"><span>eip: 1679</span></span> <span class="giallo-l"><span>title: &quot;Hardfork Meta: Istanbul&quot;</span></span> <span class="giallo-l"><span>author: Alex Beregszaszi (@axic), Afri Schoedon (@5chdn)</span></span> <span class="giallo-l"><span>type: Meta</span></span> <span class="giallo-l"><span>status: Draft</span></span> <span class="giallo-l"><span>created: 2019-01-04</span></span> <span class="giallo-l"><span>requires: 1716</span></span> <span class="giallo-l"><span>---</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>## Abstract</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>This meta-EIP specifies the changes included in the Ethereum hardfork named Istanbul.</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>## Specification</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>- Codename: Istanbul</span></span> <span class="giallo-l"><span>- Activation: TBD</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>### Included EIPs</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>- TBD</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>### Accepted EIPs</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>- TBD</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>### Rejected EIPs</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>- TBD</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>### Proposed EIPs</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>- TBD</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>## Timeline</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>* 2019-05-17 (Fri) hard deadline to accept proposals for &quot;Istanbul&quot;</span></span> <span class="giallo-l"><span>* 2019-07-19 (Fri) soft deadline for major client implementations</span></span> <span class="giallo-l"><span>* 2019-08-14 (Wed) projected date for testnet network upgrade (Ropsten, Görli, or ad-hoc testnet)</span></span> <span class="giallo-l"><span>* 2019-10-16 (Wed) projected date for mainnet upgrade (&quot;Istanbul&quot;)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>## References</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>- TBD (e.g. link to Core Dev notes or other references)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>## Copyright</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>Copyright and related rights waived via [CC0](/LICENSE.md).</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span>{% endraw %}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>A meta EIP for coordinating the hard fork should help in visibility and traceability of the scope of changes as well as provide a simple name and/or number for referring to the proposed fork.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-02-11T00:00:00+00:00 2026-02-11T14:49:27+00:00 Alex Beregszaszihttps://github.com/axic https://wg-eips.ritovision.com/2069/ <h2 id="simple-summary">Simple Summary</h2> <p>Recommendation for including contract ABI descriptions in EIPs and ERCs as YAML.</p> <h2 id="motivation">Motivation</h2> <p>In the past, most ERCs/EIPs included an ABI description purely as a Solidity contract and/or interface. This has several drawbacks:</p> <ul> <li>Prefers a single language over others and could hinder the development of new languages.</li> <li>Locks the specification to a certain version of the Solidity language.</li> <li>Allows the use of syntactical elements and features of the Solidity language, which may not be well representable in the ABI. This puts other languages at even more disadvantage.</li> </ul> <p>This proposal aims to solve all these issues.</p> <h2 id="specification">Specification</h2> <p>The <a rel="external" href="https://solidity.readthedocs.io/en/latest/abi-spec.html">Standard Contract ABI</a> is usually represented as a JSON object. This works well and several tools – including compilers and clients – support it to handle data encoding.</p> <p>One shortcoming of the JSON description is its inability to contain comments. To counter this, we suggest the use of YAML for providing user readable specifications. Given YAML was designed to be compatible with JSON, several tools exist to convert between the two formats.</p> <p>The following example contains a single function, <code>transfer</code> with one input and one output in YAML:</p> <pre class="giallo z-code"><code data-lang="yaml"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> The transfer function. Takes the recipient address</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> as an input and returns a boolean signaling the result.</span></span> <span class="giallo-l"><span>-</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> t</span><span class="z-string">ransfer</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> f</span><span class="z-string">unction</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> p</span><span class="z-entity z-name z-tag">ayable</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> c</span><span class="z-entity z-name z-tag">onstant</span><span>:</span><span class="z-constant"> false</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> s</span><span class="z-entity z-name z-tag">tateMutability</span><span>:</span><span class="z-string"> n</span><span class="z-string">onpayable</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> i</span><span class="z-entity z-name z-tag">nputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> r</span><span class="z-string">ecipient</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> a</span><span class="z-string">ddress</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-string"> a</span><span class="z-string">mount</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> u</span><span class="z-string">int256</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> o</span><span class="z-entity z-name z-tag">utputs</span><span>:</span></span> <span class="giallo-l"><span> -</span><span class="z-entity z-name z-tag"> n</span><span class="z-entity z-name z-tag">ame</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-punctuation z-definition z-string">&#39;</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> t</span><span class="z-entity z-name z-tag">ype</span><span>:</span><span class="z-string"> b</span><span class="z-string">ool</span></span></code></pre> <p>Specifications are encouraged to include comments in the YAML ABI.</p> <p>For details on what fields and values are valid in the ABI, please consult the <a rel="external" href="https://solidity.readthedocs.io/en/latest/abi-spec.html">Standard Contract ABI</a> specification.</p> <p>The same in JSON:</p> <pre class="giallo z-code"><code data-lang="json"><span class="giallo-l"><span>[</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">transfer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">function</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">payable</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">constant</span><span class="z-support">&quot;</span><span>:</span><span class="z-constant"> false</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">stateMutability</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">nonpayable</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">inputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">recipient</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">address</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span><span>,</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">amount</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">uint256</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">outputs</span><span class="z-support">&quot;</span><span>:</span><span> [</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">name</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span></span> <span class="giallo-l"><span class="z-support"> &quot;</span><span class="z-support">type</span><span class="z-support">&quot;</span><span>:</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">bool</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> ]</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span>]</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The aim was to choose a representation which is well supported by tools and supports comments. While inventing a more concise description language seems like a good idea, it felt as an unnecessary layer of complexity.</p> <h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>This has no effect on backwards compatibility.</p> <h2 id="test-cases">Test Cases</h2> <p>TBA</p> <h2 id="implementation">Implementation</h2> <p><a rel="external" href="https://github.com/axic/yamabi/">yamabi</a> is a Javascript tool to convert between the above YAML and the more widely used JSON format.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2017-02-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/210/ <h3 id="summary">Summary</h3> <p>Stores blockhashes in the state, reducing the protocol complexity and the need for client implementation complexity in order to process the BLOCKHASH opcode. Also extends the range of how far back blockhash checking can go, with the side effect of creating direct links between blocks with very distant block numbers, facilitating much more efficient initial light client syncing.</p> <h3 id="parameters">Parameters</h3> <ul> <li><code>CONSTANTINOPLE_FORK_BLKNUM</code>: TBD</li> <li><code>SUPER_USER</code>: 2**160 - 2</li> <li><code>BLOCKHASH_CONTRACT_ADDR</code>: 0xf0 (ie. 240)</li> <li><code>BLOCKHASH_CONTRACT_CODE</code>: see below</li> </ul> <h3 id="specification">Specification</h3> <p>If <code>block.number == CONSTANTINOPLE_FORK_BLKNUM</code>, then when processing the block, before processing any transactions set the code of BLOCKHASH_CONTRACT_ADDR to BLOCKHASH_CONTRACT_CODE.</p> <p>If <code>block.number &gt;= CONSTANTINOPLE_FORK_BLKNUM</code>, then when processing a block, before processing any transactions execute a call with the parameters:</p> <ul> <li><code>SENDER</code>: SUPER_USER</li> <li><code>GAS</code>: 1000000</li> <li><code>TO</code>: BLOCKHASH_CONTRACT_ADDR</li> <li><code>VALUE</code>: 0</li> <li><code>DATA</code>: &lt;32 bytes corresponding to the block's prevhash&gt;</li> </ul> <p>If <code>block.number &gt;= CONSTANTINOPLE_FORK_BLKNUM + 256</code>, then the BLOCKHASH opcode instead returns the result of executing a call (NOT a transaction) with the parameters:</p> <ul> <li><code>SENDER</code>: &lt;account from which the opcode was called&gt;</li> <li><code>GAS</code>: 1000000</li> <li><code>TO</code>: BLOCKHASH_CONTRACT_ADDR</li> <li><code>VALUE</code>: 0</li> <li><code>DATA</code>: 32 byte zero-byte-leftpadded integer representing the stack argument with which the opcode was called</li> </ul> <p>Also, for blocks where <code>block.number &gt;= CONSTANTINOPLE_FORK_BLKNUM</code>, the gas cost is increased from 20 to 800 to reflect the higher costs of processing the algorithm in the contract code.</p> <h3 id="blockhash-contract-code">BLOCKHASH_CONTRACT_CODE</h3> <p>The Serpent source code is:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-keyword">with</span><span> offset</span><span class="z-keyword"> =</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> msg</span><span>.</span><span>sender</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0x</span><span class="z-constant">fffffffffffffffffffffffffffffffffffffffe</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> with</span><span> bn</span><span class="z-keyword"> =</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> bn</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> ~</span><span>sstore</span><span>(</span><span>offset</span><span class="z-keyword"> +</span><span class="z-keyword"> ~</span><span>mod</span><span>(</span><span>bn</span><span>,</span><span class="z-constant"> 256</span><span>)</span><span>,</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span class="z-keyword"> ~</span><span>mod</span><span>(</span><span>bn</span><span>,</span><span class="z-constant"> 256</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> ~</span><span>stop</span><span>(</span><span>)</span></span> <span class="giallo-l"><span> bn</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>div</span><span>(</span><span>bn</span><span>,</span><span class="z-constant"> 256</span><span>)</span></span> <span class="giallo-l"><span> offset</span><span class="z-keyword"> +=</span><span class="z-constant"> 256</span></span> <span class="giallo-l"><span class="z-keyword"> elif</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 0</span><span class="z-keyword"> and</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword"> &lt;</span><span> block</span><span>.</span><span>number</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> with</span><span> tbn</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">0</span><span>)</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> with</span><span> dist_minus_one</span><span class="z-keyword"> =</span><span> block</span><span>.</span><span>number</span><span class="z-keyword"> -</span><span> tbn</span><span class="z-keyword"> -</span><span class="z-constant"> 1</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> while</span><span> dist_minus_one</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 256</span><span class="z-invalid z-illegal"> &amp;&amp;</span><span class="z-keyword"> ~</span><span>mod</span><span>(</span><span>tbn</span><span>,</span><span class="z-constant"> 256</span><span>)</span><span class="z-keyword"> ==</span><span class="z-constant"> 0</span><span>:</span></span> <span class="giallo-l"><span> offset</span><span class="z-keyword"> +=</span><span class="z-constant"> 256</span></span> <span class="giallo-l"><span> tbn</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>div</span><span>(</span><span>tbn</span><span>,</span><span class="z-constant"> 256</span><span>)</span><span> </span></span> <span class="giallo-l"><span> dist_minus_one</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>div</span><span>(</span><span>dist_minus_one</span><span>,</span><span class="z-constant"> 256</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> dist_minus_one</span><span class="z-keyword"> &gt;=</span><span class="z-constant"> 256</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-keyword">~</span><span>sload</span><span>(</span><span>offset</span><span class="z-keyword"> +</span><span class="z-keyword"> ~</span><span>mod</span><span>(</span><span>tbn</span><span>,</span><span class="z-constant"> 256</span><span>)</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword"> else</span><span>:</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>(</span><span class="z-constant">0</span><span>)</span></span></code></pre> <p>The EVM init code is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x6100f58061000e60003961010356600073fffffffffffffffffffffffffffffffffffffffe33141561005857600143035b801561005257600035610100820683015561010081061561003f57005b6101008104905061010082019150610022565b506100f3565b600060003512151561006e574360003512610071565b60005b156100e7576000356001814303035b6101008112151561009857600061010083061461009b565b60005b156100ba57610100830192506101008204915061010081049050610080565b610100811215156100d057600060a052602060a0f35b610100820683015460c052602060c0f350506100f2565b600060e052602060e0f35b5b505b6000f3</span></span></code></pre> <p>The EVM bytecode that the contract code should be set to is:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0x600073fffffffffffffffffffffffffffffffffffffffe33141561005857600143035b801561005257600035610100820683015561010081061561003f57005b6101008104905061010082019150610022565b506100f3565b600060003512151561006e574360003512610071565b60005b156100e7576000356001814303035b6101008112151561009857600061010083061461009b565b60005b156100ba57610100830192506101008204915061010081049050610080565b610100811215156100d057600060a052602060a0f35b610100820683015460c052602060c0f350506100f2565b600060e052602060e0f35b5b50</span></span></code></pre><h3 id="rationale">Rationale</h3> <p>This removes the need for implementations to have an explicit way to look into historical block hashes, simplifying the protocol definition and removing a large component of the "implied state" (information that is technically state but is not part of the state tree) and thereby making the protocol more "pure". Additionally, it allows blocks to directly point to blocks far behind them, which enables extremely efficient and secure light client protocols.</p> 2017-02-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/86/ <h1 id="summary">Summary</h1> <p>Implements a set of changes that serve the combined purpose of "abstracting out" signature verification and nonce checking, allowing users to create "account contracts" that perform any desired signature/nonce checks instead of using the mechanism that is currently hard-coded into transaction processing.</p> <h1 id="parameters">Parameters</h1> <ul> <li>METROPOLIS_FORK_BLKNUM: TBD</li> <li>CHAIN_ID: same as used for EIP 155 (ie. 1 for mainnet, 3 for testnet)</li> <li>NULL_SENDER: 2**160 - 1</li> </ul> <h1 id="specification">Specification</h1> <p>If <code>block.number &gt;= METROPOLIS_FORK_BLKNUM</code>, then:</p> <ol> <li>If the signature of a transaction is <code>(CHAIN_ID, 0, 0)</code> (ie. <code>r = s = 0</code>, <code>v = CHAIN_ID</code>), then treat it as valid and set the sender address to <code>NULL_SENDER</code></li> <li>Transactions of this form MUST have gasprice = 0, nonce = 0, value = 0, and do NOT increment the nonce of account NULL_SENDER.</li> <li>Create a new opcode at <code>0xfb</code>, <code>CREATE2</code>, with 4 stack arguments (value, salt, mem_start, mem_size) which sets the creation address to <code>sha3(sender + salt + sha3(init code)) % 2**160</code>, where <code>salt</code> is always represented as a 32-byte value.</li> <li>Add to <em>all</em> contract creation operations, including transactions and opcodes, the rule that if a contract at that address already exists and has non-empty code OR non-empty nonce, the operation fails and returns 0 as if the init code had run out of gas. If an account has empty code and nonce but nonempty balance, the creation operation may still succeed.</li> </ol> <h1 id="rationale">Rationale</h1> <p>The goal of these changes is to set the stage for abstraction of account security. Instead of having an in-protocol mechanism where ECDSA and the default nonce scheme are enshrined as the only "standard" way to secure an account, we take initial steps toward a model where in the long term all accounts are contracts, contracts can pay for gas, and users are free to define their own security model.</p> <p>Under EIP 86, we can expect users to store their ether in contracts, whose code might look like the following (example in Serpent):</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Get signature from tx data</span></span> <span class="giallo-l"><span>sig_v</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">0</span><span>)</span></span> <span class="giallo-l"><span>sig_r</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">32</span><span>)</span></span> <span class="giallo-l"><span>sig_s</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">64</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Get tx arguments</span></span> <span class="giallo-l"><span>tx_nonce</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">96</span><span>)</span></span> <span class="giallo-l"><span>tx_to</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">128</span><span>)</span></span> <span class="giallo-l"><span>tx_value</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">160</span><span>)</span></span> <span class="giallo-l"><span>tx_gasprice</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">192</span><span>)</span></span> <span class="giallo-l"><span>tx_data</span><span class="z-keyword"> =</span><span> string</span><span>(</span><span class="z-keyword">~</span><span>calldatasize</span><span>(</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 224</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>calldataload</span><span>(</span><span>tx_data</span><span>,</span><span class="z-constant"> 224</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Get signing hash</span></span> <span class="giallo-l"><span>signing_data</span><span class="z-keyword"> =</span><span> string</span><span>(</span><span class="z-keyword">~</span><span>calldatasize</span><span>(</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 64</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>mstore</span><span>(</span><span>signing_data</span><span>,</span><span> tx</span><span>.</span><span>startgas</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>calldataload</span><span>(</span><span>signing_data</span><span class="z-keyword"> +</span><span class="z-constant"> 32</span><span>,</span><span class="z-constant"> 96</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 96</span><span>)</span></span> <span class="giallo-l"><span>signing_hash</span><span class="z-keyword"> =</span><span> sha3</span><span>(</span><span>signing_data</span><span>:</span><span class="z-support">str</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Perform usual checks</span></span> <span class="giallo-l"><span>prev_nonce</span><span class="z-keyword"> =</span><span class="z-keyword"> ~</span><span>sload</span><span>(</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> tx_nonce</span><span class="z-keyword"> ==</span><span> prev_nonce</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span class="z-variable z-language"> self</span><span>.</span><span>balance</span><span class="z-keyword"> &gt;=</span><span> tx_value</span><span class="z-keyword"> +</span><span> tx_gasprice</span><span class="z-keyword"> *</span><span> tx</span><span>.</span><span>startgas</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span class="z-keyword"> ~</span><span>ecrecover</span><span>(</span><span>signing_hash</span><span>,</span><span> sig_v</span><span>,</span><span> sig_r</span><span>,</span><span> sig_s</span><span>)</span><span class="z-keyword"> ==</span><span class="z-keyword"> &lt;</span><span>pubkey</span><span class="z-support"> hash</span><span> here</span><span class="z-keyword">&gt;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Update nonce</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>sstore</span><span>(</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>,</span><span> prev_nonce</span><span class="z-keyword"> +</span><span class="z-constant"> 1</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Pay for gas</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>send</span><span>(</span><span class="z-constant">MINER_CONTRACT</span><span>,</span><span> tx_gasprice</span><span class="z-keyword"> *</span><span> tx</span><span>.</span><span>startgas</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Make the main call</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>call</span><span>(</span><span>msg</span><span>.</span><span>gas</span><span class="z-keyword"> -</span><span class="z-constant"> 50000</span><span>,</span><span> tx_to</span><span>,</span><span> tx_value</span><span>,</span><span> tx_data</span><span>,</span><span class="z-support"> len</span><span>(</span><span>tx_data</span><span>)</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Get remaining gas payments back</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>call</span><span>(</span><span class="z-constant">20000</span><span>,</span><span class="z-constant"> MINER_CONTRACT</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span> [</span><span>msg</span><span>.</span><span>gas</span><span>]</span><span>,</span><span class="z-constant"> 32</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span></code></pre> <p>This can be thought of as a "forwarding contract". It accepts data from the "entry point" address 2**160 - 1 (an account that anyone can send transactions from), expecting that data to be in the format <code>[sig, nonce, to, value, gasprice, data]</code>. The forwarding contract verifies the signature, and if the signature is correct it sets up a payment to the miner and then sends a call to the desired address with the provided value and data.</p> <p>The benefits that this provides lie in the most interesting cases:</p> <ul> <li><strong>Multisig wallets</strong>: currently, sending from a multisig wallet requires each operation to be ratified by the participants, and each ratification is a transaction. This could be simplified by having one ratification transaction include signatures from the other participants, but even still it introduces complexity because the participants' accounts all need to be stocked up with ETH. With this EIP, it will be possible to just have the contract store the ETH, send a transaction containing all signatures to the contract directly, and the contract can pay the fees.</li> <li><strong>Ring signature mixers</strong>: the way that ring signature mixers work is that N individuals send 1 coin into a contract, and then use a linkable ring signature to withdraw 1 coin later on. The linkable ring signature ensures that the withdrawal transaction cannot be linked to the deposit, but if someone attempts to withdraw twice then those two signatures can be linked and the second one prevented. However, currently there is a privacy risk: to withdraw, you need to have coins to pay for gas, and if these coins are not properly mixed then you risk compromising your privacy. With this EIP, you can pay for gas straight our of your withdrawn coins.</li> <li><strong>Custom cryptography</strong>: users can upgrade to ed25519 signatures, Lamport hash ladder signatures or whatever other scheme they want on their own terms; they do not need to stick with ECDSA.</li> <li><strong>Non-cryptographic modifications</strong>: users can require transactions to have expiry times (this being standard would allow old empty/dust accounts to be flushed from the state securely), use k-parallelizable nonces (a scheme that allows transactions to be confirmed slightly out-of-order, reducing inter-transaction dependence), or make other modifications.</li> </ul> <p>(2) and (3) introduce a feature similar to bitcoin's P2SH, allowing users to send funds to addresses that provably map to only one particular piece of code. Something like this is crucial in the long term because, in a world where all accounts are contracts, we need to preserve the ability to send to an account before that account exists on-chain, as that's a basic functionality that exists in all blockchain protocols today.</p> <h1 id="miner-and-transaction-replaying-strategy">Miner and transaction replaying strategy</h1> <p>Note that miners would need to have a strategy for accepting these transactions. This strategy would need to be very discriminating, because otherwise they run the risk of accepting transactions that do not pay them any fees, and possibly even transactions that have no effect (eg. because the transaction was already included and so the nonce is no longer current).</p> <p>One simple strategy is to have a set of regexps that the to address of an account would be checked against, each regexp corresponding to a "standard account type" which is known to be "safe" (in the sense that if an account has that code, and a particular check involving the account balances, account storage and transaction data passes, then if the transaction is included in a block the miner will get paid), and mine and relay transactions that pass these checks.</p> <p>One example would be to check as follows:</p> <ol> <li>Check that the to address has code which is the compiled version of the Serpent code above, with <code>&lt;pubkey hash here&gt;</code> replaced with any public key hash.</li> <li>Check that the signature in the transaction data verifies with that key hash.</li> <li>Check that the gasprice in the transaction data is sufficiently high</li> <li>Check that the nonce in the state matches the nonce in the transaction data</li> <li>Check that there is enough ether in the account to pay for the fee</li> </ol> <p>If all five checks pass, relay and/or mine the transaction.</p> <p>A looser but still effective strategy would be to accept any code that fits the same general format as the above, consuming only a limited amount of gas to perform nonce and signature checks and having a guarantee that transaction fees will be paid to the miner. Another strategy is to, alongside other approaches, try to process any transaction that asks for less than 250,000 gas, and include it only if the miner's balance is appropriately higher after executing the transaction than before it.</p> <h1 id="copyright">Copyright</h1> <p>Copyright and related rights waived via CC0.</p> 2017-02-06T00:00:00+00:00 2026-02-11T14:48:25+00:00 Nick Johnsonnick@ethereum.org https://wg-eips.ritovision.com/205/ <h2 id="simple-summary">Simple Summary</h2> <p>This EIP proposes a mechanism for storing ABI definitions in ENS, for easy lookup of contract interfaces by callers.</p> <h2 id="abstract">Abstract</h2> <p>ABIs are important metadata required for interacting with most contracts. At present, they are typically supplied out-of-band, which adds an additional burden to interacting with contracts, particularly on a one-off basis or where the ABI may be updated over time. The small size of ABIs permits an alternative solution, storing them in ENS, permitting name lookup and ABI discovery via the same process.</p> <p>ABIs are typically quite compact; the largest in-use ABI we could find, that for the DAO, is 9450 bytes uncompressed JSON, 6920 bytes uncompressed CBOR, and 1128 bytes when the JSON form is compressed with zlib. Further gains on CBOR encoding are possible using a CBOR extension that permits eliminating repeated strings, which feature extensively in ABIs. Most ABIs, however, are far shorter than this, consisting of only a few hundred bytes of uncompressed JSON.</p> <p>This EIP defines a resolver profile for retrieving contract ABIs, as well as encoding standards for storing ABIs for different applications, allowing the user to select between different representations based on their need for compactness and other considerations such as onchain access.</p> <h2 id="specification">Specification</h2> <h3 id="abi-encodings">ABI encodings</h3> <p>In order to allow for different tradeoffs between onchain size and accessibility, several ABI encodings are defined. Each ABI encoding is defined by a unique constant with only a single bit set, allowing for the specification of 256 unique encodings in a single uint.</p> <p>The currently recognised encodings are:</p> <table><thead><tr><th>ID</th><th>Description</th></tr></thead><tbody> <tr><td>1</td><td>JSON</td></tr> <tr><td>2</td><td>zlib-compressed JSON</td></tr> <tr><td>4</td><td>CBOR</td></tr> <tr><td>8</td><td>URI</td></tr> </tbody></table> <p>This table may be extended in future through the EIP process.</p> <p>Encoding type 1 specifies plaintext JSON, uncompressed; this is the standard format in which ABIs are typically encoded, but also the bulkiest, and is not easily parseable onchain.</p> <p>Encoding type 2 specifies zlib-compressed JSON. This is significantly smaller than uncompressed JSON, and is straightforward to decode offchain. However, it is impracticalfor onchain consumers to use.</p> <p>Encoding type 4 is <a rel="external" href="https://cbor.io/">CBOR</a>. CBOR is a binary encoding format that is a superset of JSON, and is both more compact and easier to parse in limited environments such as the EVM. Consumers that support CBOR are strongly encouraged to also support the <a rel="external" href="http://cbor.schmorp.de/stringref">stringref extension</a> to CBOR, which provides significant additional reduction in encoded size.</p> <p>Encoding type 8 indicates that the ABI can be found elsewhere, at the specified URI. This is typically the most compact of the supported forms, but also adds external dependencies for implementers. The specified URI may use any schema, but HTTP, IPFS, and Swarm are expected to be the most common.</p> <h3 id="resolver-profile">Resolver profile</h3> <p>A new resolver interface is defined, consisting of the following method:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>function ABI(bytes32 node, uint256 contentType) constant returns (uint256, bytes);</span></span></code></pre> <p>The interface ID of this interface is 0x2203ab56.</p> <p>contentType is a bitfield, and is the bitwise OR of all the encoding types the caller will accept. Resolvers that implement this interface must return an ABI encoded using one of the requested formats, or <code>(0, "")</code> if they do not have an ABI for this function, or do not support any of the requested formats.</p> <p>The <code>abi</code> resolver profile is valid on both forward and reverse records.</p> <h3 id="abi-lookup-process">ABI lookup process</h3> <p>When attempting to fetch an ABI based on an ENS name, implementers should first attempt an ABI lookup on the name itself. If that lookup returns no results, they should attempt a reverse lookup on the Ethereum address the name resolves to.</p> <p>Implementers should support as many of the ABI encoding formats as practical.</p> <h2 id="rationale">Rationale</h2> <p>Storing ABIs onchain avoids the need to introduce additional dependencies for applications wishing to fetch them, such as swarm or HTTP access. Given the typical compactness of ABIs, we believe this is a worthwhile tradeoff in many cases.</p> <p>The two-step resolution process permits different names to provide different ABIs for the same contract, such as in the case where it's useful to provide a minimal ABI to some callers, as well as specifying ABIs for contracts that did not specify one of their own. The fallback to looking up an ABI on the reverse record permits contracts to specify their own canonical ABI, and prevents the need for duplication when multiple names reference the same contract without the need for different ABIs.</p> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2016-12-10T00:00:00+00:00 2026-02-11T14:49:27+00:00 Greg Colvingreg@colvin.org Brooklyn Zelenkahttps://github.com/expede Paweł Bylicahttps://github.com/chfast Christian Reitwiessnerhttps://github.com/chriseth https://wg-eips.ritovision.com/615/ <h2 id="simple-summary">Simple Summary</h2> <p>In the 21st century, on a blockchain circulating billions of ETH, formal specification and verification are an essential tool against loss. Yet the design of the EVM makes this unnecessarily difficult. Further, the design of the EVM makes near-linear-time compilation to machine code difficult. We propose to move forward with proposals to resolve these problems by tightening EVM security guarantees and reducing barriers to performance.</p> <h2 id="abstract">Abstract</h2> <p>EVM code is currently difficult to statically analyze, hobbling critical tools for preventing the many expensive bugs our blockchain has experienced. Further, none of the current implementations of the Ethereum Virtual Machine—including the compilers—are sufficiently performant to reduce the need for precompiles and otherwise meet the network's long-term demands. This proposal identifies dynamic jumps as a major reason for these issues, and proposes changes to the EVM specification to address the problem, making further efforts towards a safer and more performant the EVM possible.</p> <p>We also propose to validate—in near-linear time—that EVM contracts correctly use subroutines, avoid misuse of the stack, and meet other safety conditions <em>before</em> placing them on the blockchain. Validated code precludes most runtime exceptions and the need to test for them. And well-behaved control flow and use of the stack makes life easier for interpreters, compilers, formal analysis, and other tools.</p> <h2 id="motivation">Motivation</h2> <p>Currently the EVM supports only dynamic jumps, where the address to jump to is an argument on the stack. Worse, the EVM fails to provide ordinary, alternative control flow facilities like subroutines and switches provided by Wasm and most CPUs. So dynamic jumps cannot be avoided, yet they obscure the structure of the code and thus mostly inhibit control- and data-flow analysis. This puts the quality and speed of optimized compilation fundamentally at odds. Further, since many jumps can potentially be to any jump destination in the code, the number of possible paths through the code can go up as the product of the number of jumps by the number of destinations, as does the time complexity of static analysis. Many of these cases are undecidable at deployment time, further inhibiting static and formal analyses.</p> <p>However, given Ethereum's security requirements, <strong>near-linear</strong> <strong><code>n log n</code></strong> <strong>time complexity</strong> is essential. Otherwise, Contracts can be crafted or discovered with quadratic complexity to use as denial of service attack vectors against validations and optimizations.</p> <p>But absent dynamic jumps code can be statically analyzed in linear time. That allows for <em>linear time validation</em>. It also allows for code generation and such optimizations as can be done in <code>log n</code> time to comprise an <em><code>n log n</code></em> <em>time compiler</em>.</p> <p>And absent dynamic jumps, and with proper subroutines the EVM is a better target for code generation from other languages, including</p> <ul> <li>Solidity</li> <li>Vyper</li> <li>LLVM IR <ul> <li>front ends include C, C++, Common Lisp, D, Fortran, Haskell, Java, Javascript, Kotlin, Lua, Objective-C, Pony, Pure, Python, Ruby, Rust, Scala, Scheme, and Swift</li> </ul> </li> </ul> <p>The result is that all of the following validations and optimizations can be done at deployment time with near-linear <code>(n log n)</code> time complexity.</p> <ul> <li>The absence of most exceptional halting states can be validated.</li> <li>The maximum use of resources can be sometimes be calculated.</li> <li>Bytecode can be compiled to machine code in near-linear time.</li> <li>Compilation can more effectively optimize use of smaller registers.</li> <li>Compilation can more effectively optimize injection of gas metering.</li> </ul> <h2 id="specification">Specification</h2> <h3 id="dependencies">Dependencies</h3> <blockquote> <p><strong><a href="https://wg-eips.ritovision.com/1702/">EIP-1702</a>. Generalized Account Versioning Scheme.</strong> This proposal needs a versioning scheme to allow for its bytecode (and eventually eWasm bytecode) to be deployed with existing bytecode on the same blockchain.</p> </blockquote> <h3 id="proposal">Proposal</h3> <p>We propose to deprecate two existing instructions—<code>JUMP</code> and <code>JUMPI</code>—and propose new instructions to support their legitimate uses. In particular, it must remain possible to compile Solidity and Vyper code to EVM bytecode, with no significant loss of performance or increase in gas price.</p> <p>Especially important is efficient translation to and from <a rel="external" href="https://github.com/ewasm/design">eWasm</a> and to machine code. To that end we maintain a close correspondence between <a rel="external" href="https://webassembly.github.io/spec/core/_download/WebAssembly.pdf">Wasm</a>, <a rel="external" href="https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-instruction-set-reference-manual-325383.pdf">x86</a>, <a rel="external" href="https://static.docs.arm.com/100076/0100/arm_instruction_set_reference_guide_100076_0100_00_en.pdf">ARM</a> and proposed EVM instructions.</p> <table><thead><tr><th>EIP-615</th><th>Wasm</th><th>x86</th><th>ARM</th></tr></thead><tbody> <tr><td>JUMPTO</td><td>br</td><td>JMP</td><td>B</td></tr> <tr><td>JUMPIF</td><td>br_if</td><td>JE</td><td>BEQ</td></tr> <tr><td>JUMPV</td><td>br_table</td><td>JMP</td><td>TBH</td></tr> <tr><td>JUMPSUB</td><td>call</td><td>CALL</td><td>BL</td></tr> <tr><td>JUMPSUBV</td><td>call_indirect</td><td>CALL</td><td>BL</td></tr> <tr><td>RETURN</td><td>return</td><td>RET</td><td>RET</td></tr> <tr><td>GETLOCAL</td><td>local.get</td><td>POP</td><td>POP</td></tr> <tr><td>PUTLOCAL</td><td>local.put</td><td>PUSH</td><td>PUSH</td></tr> <tr><td>BEGINSUB</td><td>func</td><td></td><td></td></tr> <tr><td>BEGINDATA</td><td>tables</td><td></td><td></td></tr> </tbody></table> <h4 id="preliminaries">Preliminaries</h4> <p>These forms</p> <blockquote> <p><em><code>INSTRUCTION</code></em></p> <p><em><code>INSTRUCTION x</code></em></p> <p><em><code>INSTRUCTION x, y</code></em></p> </blockquote> <p>name an <em><code>INSTRUCTION</code></em> with no, one and two arguments, respectively. An instruction is represented in the bytecode as a single-byte opcode. Any arguments are laid out as immediate data bytes following the opcode inline, interpreted as fixed length, MSB-first, two's-complement, two-byte positive integers. (Negative values are reserved for extensions.)</p> <h4 id="branches-and-subroutines">Branches and Subroutines</h4> <p>The two most important uses of <code>JUMP</code> and <code>JUMPI</code> are static jumps and return jumps. Conditional and unconditional static jumps are the mainstay of control flow. Return jumps are implemented as a dynamic jump to a return address pushed on the stack. With the combination of a static jump and a dynamic return jump you can—and Solidity does—implement subroutines. The problem is that static analysis cannot tell the one place the return jump is going, so it must analyze every possibility (a heavy analysis).</p> <p>Static jumps are provided by</p> <blockquote> <p><code>JUMPTO jump_target</code></p> <p><code>JUMPIF jump_target</code></p> <p>which are the same as <code>JUMP</code> and <code>JUMPI</code> except that they jump to an immediate <code>jump_target</code> rather than an address on the stack.</p> </blockquote> <p>To support subroutines, <code>BEGINSUB</code>, <code>JUMPSUB</code>, and <code>RETURNSUB</code> are provided. Brief descriptions follow, and full semantics are given below.</p> <blockquote> <p><code>BEGINSUB n_args, n_results</code></p> <p>marks the <strong>single</strong> entry to a subroutine. <code>n_args</code> items are taken off of the stack at entry to, and <code>n_results</code> items are placed on the stack at return from the subroutine. The subroutine ends at the next <code>BEGINSUB</code> instruction (or <code>BEGINDATA</code>, below) or at the end of the bytecode.</p> </blockquote> <blockquote> <p><code>JUMPSUB jump_target</code></p> <p>jumps to an immediate subroutine address.</p> </blockquote> <blockquote> <p><code>RETURNSUB</code></p> <p>returns from the current subroutine to the instruction following the JUMPSUB that entered it.</p> </blockquote> <h4 id="switches-callbacks-and-virtual-functions">Switches, Callbacks, and Virtual Functions</h4> <p>Dynamic jumps are also used for <code>O(1)</code> indirection: an address to jump to is selected to push on the stack and be jumped to. So we also propose two more instructions to provide for constrained indirection. We support these with vectors of <code>JUMPDEST</code> or <code>BEGINSUB</code> offsets stored inline, which can be selected with an index on the stack. That constrains validation to a specified subset of all possible destinations. The danger of quadratic blow up is avoided because it takes as much space to store the jump vectors as it does to code the worst case exploit.</p> <p>Dynamic jumps to a <code>JUMPDEST</code> are used to implement <code>O(1)</code> jumptables, which are useful for dense switch statements. Wasm and most CPUs provide similar instructions.</p> <blockquote> <p><code>JUMPV n, jump_targets</code></p> <p>jumps to one of a vector of <code>n</code> <code>JUMPDEST</code> offsets via a zero-based index on the stack. The vector is stored inline at the <code>jump_targets</code> offset after the BEGINDATA bytecode as MSB-first, two's-complement, two-byte positive integers. If the index is greater than or equal to <code>n - 1</code> the last (default) offset is used.</p> </blockquote> <p>Dynamic jumps to a <code>BEGINSUB</code> are used to implement <code>O(1)</code> virtual functions and callbacks, which take at most two pointer dereferences on most CPUs. Wasm provides a similar instruction.</p> <blockquote> <p><code>JUMPSUBV n, jump_targets</code></p> <p>jumps to one of a vector of <code>n</code> <code>BEGINSUB</code> offsets via a zero-based index on the stack. The vector is stored inline at the <code>jump_targets</code> offset after the DATA bytecode, as MSB-first, two's-complement, two-byte positive integers. If the index is greater than or equal to <code>n - 1</code> the last (default) offset is used.</p> </blockquote> <h4 id="variable-access">Variable Access</h4> <p>These operations provide convenient access to subroutine parameters and local variables at fixed stack offsets within a subroutine. Otherwise only sixteen variables can be directly addressed.</p> <blockquote> <p><code>PUTLOCAL n</code></p> <p>Pops the stack to the local variable <code>n</code>.</p> </blockquote> <blockquote> <p><code>GETLOCAL n</code></p> <p>Pushes the local variable <code>n</code> onto the stack.</p> </blockquote> <p>Local variable <code>n</code> is the nth stack item below the frame pointer, <code>FP[-n]</code>, as defined below.</p> <h4 id="data">Data</h4> <p>There needs to be a way to place unreachable data into the bytecode that will be skipped over and not validated. Indirect jump vectors will not be valid code. Initialization code must create runtime code from data that might not be valid code. And unreachable data might prove useful to programs for other purposes.</p> <blockquote> <p><code>BEGINDATA</code></p> <p>specifies that all of the following bytes to the end of the bytecode are data, and not reachable code.</p> </blockquote> <h4 id="structure">Structure</h4> <p>Valid EIP-615 EVM bytecode begins with a valid header. This is the magic number ‘\0evm’ followed by the semantic versioning number '\1\5\0'. (For Wasm the header is '\0asm\1').</p> <p>Following the header is the BEGINSUB opcode for the <em>main</em> routine. It takes no arguments and returns no values. Other subroutines may follow the <em>main</em> routine, and an optional BEGINDATA opcode may mark the start of a data section.</p> <h3 id="semantics">Semantics</h3> <p>Jumps to and returns from subroutines are described here in terms of</p> <ul> <li>The EVM data stack, (as defined in the <a rel="external" href="https://ethereum.github.io/yellowpaper/paper.pdf">Yellow Paper</a>) usually just called “the stack.”</li> <li>A return stack of <code>JUMPSUB</code> and <code>JUMPSUBV</code> offsets.</li> <li>A frame stack of frame pointers.</li> </ul> <p>We will adopt the following conventions to describe the machine state:</p> <ul> <li>The <em>program counter</em> <code>PC</code> is (as usual) the byte offset of the currently executing instruction.</li> <li>The <em>stack pointer</em> <code>SP</code> corresponds to the <a rel="external" href="https://ethereum.github.io/yellowpaper/paper.pdf">Yellow Paper</a>'s substate <code>s</code> of the machine state. <ul> <li><code>SP[0]</code> is where a new item is can be pushed on the stack.</li> <li><code>SP[1]</code> is the first item on the stack, which can be popped off the stack.</li> <li>The stack grows towards lower addresses.</li> </ul> </li> <li>The <em>frame pointer</em> <code>FP</code> is set to <code>SP + n_args</code> at entry to the currently executing subroutine. <ul> <li>The <em>stack items</em> between the frame pointer and the current stack pointer are called the <em>frame</em>.</li> <li>The current number of items in the frame, <code>FP - SP</code>, is the <em>frame size</em>.</li> </ul> </li> </ul> <blockquote> <p><strong>Note</strong>: Defining the frame pointer so as to include the arguments is unconventional, but better fits our stack semantics and simplifies the remainder of the proposal.</p> </blockquote> <p>The frame pointer and return stacks are internal to the subroutine mechanism, and not directly accessible to the program. This is necessary to prevent the program from modifying its own state in ways that could be invalid.</p> <p>Execution of EVM bytecode begins with the <em>main</em> routine with no arguments, <code>SP</code> and <code>FP</code> set to 0, and with one value on the return stack—<code>code_size - 1</code>. (Executing the virtual byte of 0 after this offset causes an EVM to stop. Thus executing a <code>RETURNSUB</code> with no prior <code>JUMPSUB</code> or <code>JUMBSUBV</code>—that is, in the <em>main</em> routine—executes a <code>STOP</code>.)</p> <p>Execution of a subroutine begins with <code>JUMPSUB</code> or <code>JUMPSUBV</code>, which</p> <ul> <li>pushes <code>PC</code> on the return stack,</li> <li>pushes <code>FP</code> on the frame stack <ul> <li>thus suspending execution of the current subroutine,</li> </ul> </li> <li>sets <code>FP</code> to <code>SP + n_args</code>, and</li> <li>sets <code>PC</code> to the specified <code>BEGINSUB</code> address <ul> <li>thus beginning execution of the new subroutine.</li> </ul> </li> </ul> <p>Execution of a subroutine is suspended during and resumed after execution of nested subroutines, and ends upon encountering a <code>RETURNSUB</code>, which</p> <ul> <li>sets <code>FP</code> to the top of the virtual frame stack and pops the stack,</li> <li>sets <code>SP</code> to <code>FP + n_results</code>,</li> <li>sets <code>PC</code> to top of the return stack and pops the stack, and</li> <li>advances <code>PC</code> to the next instruction</li> </ul> <p>thus resuming execution of the enclosing subroutine or <em>main</em> routine. A <code>STOP</code> or <code>RETURN</code> also ends the execution of a subroutine.</p> <p>For example, starting from this stack,</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>_________________</span></span> <span class="giallo-l"><span> | locals 20 &lt;- FP</span></span> <span class="giallo-l"><span>frame | 21</span></span> <span class="giallo-l"><span>______|___________ 22</span></span> <span class="giallo-l"><span> &lt;- SP</span></span></code></pre> <p>and after pushing two arguments and branching with <code>JUMPSUB</code> to a <code>BEGINSUB 2, 3</code></p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 10</span></span> <span class="giallo-l"><span>PUSH 11</span></span> <span class="giallo-l"><span>JUMPSUB beginsub</span></span></code></pre> <p>and initializing three local variables</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>PUSH 99</span></span> <span class="giallo-l"><span>PUSH 98</span></span> <span class="giallo-l"><span>PUSH 97</span></span></code></pre> <p>the stack looks like this</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> 20</span></span> <span class="giallo-l"><span> 21</span></span> <span class="giallo-l"><span>__________________ 22</span></span> <span class="giallo-l"><span> | arguments 10 &lt;- FP</span></span> <span class="giallo-l"><span>frame |___________ 11</span></span> <span class="giallo-l"><span> | locals 99</span></span> <span class="giallo-l"><span> | 98</span></span> <span class="giallo-l"><span>______|___________ 97</span></span> <span class="giallo-l"><span> &lt;- SP</span></span></code></pre> <p>After some amount of computation the stack could look like this</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> 20</span></span> <span class="giallo-l"><span> 21</span></span> <span class="giallo-l"><span>__________________ 22</span></span> <span class="giallo-l"><span> | returns 44 &lt;- FP</span></span> <span class="giallo-l"><span> | 43</span></span> <span class="giallo-l"><span>frame |___________ 42</span></span> <span class="giallo-l"><span> | locals 13</span></span> <span class="giallo-l"><span>______|___________ 14</span></span> <span class="giallo-l"><span> &lt;- SP</span></span></code></pre> <p>and after <code>RETURNSUB</code> would look like this</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>_________________</span></span> <span class="giallo-l"><span> | locals 20 &lt;- FP</span></span> <span class="giallo-l"><span> | 21</span></span> <span class="giallo-l"><span>frame |___________ 22</span></span> <span class="giallo-l"><span> | returns 44</span></span> <span class="giallo-l"><span> | 43</span></span> <span class="giallo-l"><span>______|___________ 42</span></span> <span class="giallo-l"><span> &lt;- SP</span></span></code></pre><h3 id="validity">Validity</h3> <p>We would like to consider EVM code valid iff no execution of the program can lead to an exceptional halting state, but we must validate code in linear time. So our validation does not consider the code’s data and computations, only its control flow and stack use. This means we will reject programs with invalid code paths, even if those paths are not reachable. Most conditions can be validated, and will not need to be checked at runtime; the exceptions are sufficient gas and sufficient stack. As such, static analysis may yield false negatives belonging to well-understood classes of code requiring runtime checks. Aside from those cases, we can validate large classes at validation time and with linear complexity.</p> <p><em>Execution</em> is as defined in the <a rel="external" href="https://ethereum.github.io/yellowpaper/paper.pdf">Yellow Paper</a>—a sequence of changes in the EVM state. The conditions on valid code are preserved by state changes. At runtime, if execution of an instruction would violate a condition the execution is in an exceptional halting state. The Yellow Paper defines five such states.</p> <blockquote> <p><strong>1</strong> Insufficient gas</p> </blockquote> <blockquote> <p><strong>2</strong> More than 1024 stack items</p> </blockquote> <blockquote> <p><strong>3</strong> Insufficient stack items</p> </blockquote> <blockquote> <p><strong>4</strong> Invalid jump destination</p> </blockquote> <blockquote> <p><strong>5</strong> Invalid instruction</p> </blockquote> <p>We propose to expand and extend the Yellow Paper conditions to handle the new instructions we propose.</p> <p>To handle the return stack we expand the conditions on stack size:</p> <blockquote> <p><strong>2a</strong> The size of the data stack does not exceed 1024.</p> </blockquote> <blockquote> <p><strong>2b</strong> The size of the return stack does not exceed 1024.</p> </blockquote> <p>Given our more detailed description of the data stack we restate condition 3—stack underflow—as</p> <blockquote> <p><strong>3</strong> <code>SP</code> must be less than or equal to <code>FP</code></p> </blockquote> <p>Since the various <code>DUP</code> and <code>SWAP</code> operations—as well as <code>PUTLOCAL</code> and <code>GETLOCAL</code>—are defined as taking items off the stack and putting them back on, this prevents them from accessing data below the frame pointer, since taking too many items off of the stack would mean that <code>SP</code> is less than <code>FP</code>.</p> <p>To handle the new jump instructions and subroutine boundaries, we expand the conditions on jumps and jump destinations.</p> <blockquote> <p><strong>4a</strong> <code>JUMPTO</code>, <code>JUMPIF</code>, and <code>JUMPV</code> address only <code>JUMPDEST</code> instructions.</p> </blockquote> <blockquote> <p><strong>4b</strong> <code>JUMPSUB</code> and <code>JUMPSUBV</code> address only <code>BEGINSUB</code> instructions.</p> </blockquote> <blockquote> <p><strong>4c</strong> <code>JUMP</code> instructions do not address instructions outside of the subroutine they occur in.</p> </blockquote> <p>We have two new conditions on execution to ensure consistent use of the stack by subroutines:</p> <blockquote> <p><strong>6</strong> For <code>JUMPSUB</code> and <code>JUMPSUBV</code> the frame size is at least the <code>n_args</code> of the <code>BEGINSUB</code>(s) to jump to.</p> </blockquote> <blockquote> <p><strong>7</strong> For <code>RETURNSUB</code> the frame size is equal to the <code>n_results</code> of the enclosing <code>BEGINSUB</code>.</p> </blockquote> <p>Finally, we have one condition that prevents pathological uses of the stack:</p> <blockquote> <p><strong>8</strong> For every instruction in the code the frame size is constant.</p> </blockquote> <p>In practice, we must test at runtime for conditions 1 and 2—sufficient gas and sufficient stack. We don’t know how much gas there will be, we don’t know how deep a recursion may go, and analysis of stack depth even for non-recursive programs is nontrivial.</p> <p>All of the remaining conditions we validate statically.</p> <h4 id="costs-codes">Costs &amp; Codes</h4> <p>All of the instructions are <code>O(1)</code> with a small constant, requiring just a few machine operations each, whereas a <code>JUMP</code> or <code>JUMPI</code> typically does an <code>O(log n)</code> binary search of an array of <code>JUMPDEST</code> offsets before every jump. With the cost of <code>JUMPI</code> being <em>high</em> and the cost of <code>JUMP</code> being <em>mid</em>, we suggest the cost of <code>JUMPV</code> and <code>JUMPSUBV</code> should be <em>mid</em>, <code>JUMPSUB</code> and <code>JUMPIF</code> should be <em>low</em>, and<code>JUMPTO</code> and the rest should be <em>verylow</em>. Measurement will tell.</p> <p>We suggest the following opcodes:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>0xb0 JUMPTO</span></span> <span class="giallo-l"><span>0xb1 JUMPIF</span></span> <span class="giallo-l"><span>0xb2 JUMPV</span></span> <span class="giallo-l"><span>0xb3 JUMPSUB</span></span> <span class="giallo-l"><span>0xb4 JUMPSUBV</span></span> <span class="giallo-l"><span>0xb5 BEGINSUB</span></span> <span class="giallo-l"><span>0xb6 BEGINDATA</span></span> <span class="giallo-l"><span>0xb7 RETURNSUB</span></span> <span class="giallo-l"><span>0xb8 PUTLOCAL</span></span> <span class="giallo-l"><span>0xb9 GETLOCAL</span></span></code></pre><h2 id="backwards-compatibility">Backwards Compatibility</h2> <p>These changes would need to be implemented in phases at decent intervals:</p> <blockquote> <p><strong>1.</strong> If this EIP is accepted, invalid code should be deprecated. Tools should stop generating invalid code, users should stop writing it, and clients should warn about loading it.</p> </blockquote> <blockquote> <p><strong>2.</strong> A later hard fork would require clients to place only valid code on the block chain. Note that despite the fork old EVM code will still need to be supported indefinitely; older contracts will continue to run, and to create new contracts.</p> </blockquote> <p>If desired, the period of deprecation can be extended indefinitely by continuing to accept code not versioned as new—but without validation. That is, by delaying or canceling phase 2.</p> <p>Regardless, we will need a versioning scheme like <a href="https://wg-eips.ritovision.com/1702/">EIP-1702</a> to allow current code and EIP-615 code to coexist on the same blockchain.</p> <h2 id="rationale">Rationale</h2> <p>This design was highly constrained by the existing EVM semantics, the requirement for eWasm compatibility, and the security demands of the Ethereum environment. It was also informed by the lead author's previous work implementing Java and Scheme interpreters. As such there was very little room for alternative designs.</p> <p>As described above, the approach was simply to deprecate the problematic dynamic jumps, then ask what opcodes were necessary to provide for the features they supported. These needed to include those provided by eWasm, which themselves were modeled after typical hardware. The only real innovation was to move the frame pointer and the return pointer to their own stacks, so as to prevent any possibility of overwriting them. (Although Forth also uses a return stack.) This allowed for treating subroutine arguments as local variables, and facilitated the return of multiple values.</p> <h2 id="implementation">Implementation</h2> <p>Implementation of this proposal need not be difficult. At the least, interpreters can simply be extended with the new opcodes and run unchanged otherwise. The new opcodes require only stacks for the frame pointers and return offsets and the few pushes, pops, and assignments described above. The bulk of the effort is the validator, which in most languages can almost be transcribed from the pseudocode above.</p> <p>A lightly tested C++ reference implementation is available in <a rel="external" href="https://github.com/gcolvin/aleth/tree/master/libaleth-interpreter">Greg Colvin's Aleth fork.</a> This version required circa 110 lines of new interpreter code and a well-commented, 178-line validator.</p> <h2 id="appendix-a">Appendix A</h2> <h3 id="validation">Validation</h3> <p>Validation comprises two tasks:</p> <ul> <li>Check that jump destinations are correct and instructions valid.</li> <li>Check that subroutines satisfy the conditions on control flow and stack use.</li> </ul> <p>We sketch out these two validation functions in pseudo-C below. To simplify the presentation only the five primitives are handled (<code>JUMPV</code> and <code>JUMPSUBV</code> would just add more complexity to loop over their vectors), we assume helper functions for extracting instruction arguments from immediate data and managing the stack pointer and program counter, and some optimizations are forgone.</p> <h4 id="validating-jumps">Validating Jumps</h4> <p>Validating that jumps are to valid addresses takes two sequential passes over the bytecode—one to build sets of jump destinations and subroutine entry points, another to check that addresses jumped to are in the appropriate sets.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> bytecode[code_size] // contains EVM bytecode to validate</span></span> <span class="giallo-l"><span> is_sub[code_size] // is there a BEGINSUB at PC?</span></span> <span class="giallo-l"><span> is_dest[code_size] // is there a JUMPDEST at PC?</span></span> <span class="giallo-l"><span> sub_for_pc[code_size] // which BEGINSUB is PC in?</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> bool validate_jumps(PC)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> current_sub = PC</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // build sets of BEGINSUBs and JUMPDESTs</span></span> <span class="giallo-l"><span> for (PC = 0; instruction = bytecode[PC]; PC = advance_pc(PC))</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> if instruction is invalid</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> if instruction is BEGINDATA</span></span> <span class="giallo-l"><span> break;</span></span> <span class="giallo-l"><span> if instruction is BEGINSUB</span></span> <span class="giallo-l"><span> is_sub[PC] = true</span></span> <span class="giallo-l"><span> current_sub = PC</span></span> <span class="giallo-l"><span> sub_for_pc[PC] = current_sub</span></span> <span class="giallo-l"><span> if instruction is JUMPDEST</span></span> <span class="giallo-l"><span> is_dest[PC] = true</span></span> <span class="giallo-l"><span> sub_for_pc[PC] = current_sub</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // check that targets are in subroutine</span></span> <span class="giallo-l"><span> for (PC = 0; instruction = bytecode[PC]; PC = advance_pc(PC))</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> if instruction is BEGINDATA</span></span> <span class="giallo-l"><span> break;</span></span> <span class="giallo-l"><span> if instruction is BEGINSUB</span></span> <span class="giallo-l"><span> current_sub = PC</span></span> <span class="giallo-l"><span> if instruction is JUMPSUB</span></span> <span class="giallo-l"><span> if is_sub[jump_target(PC)] is false</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> if instruction is JUMPTO or JUMPIF</span></span> <span class="giallo-l"><span> if is_dest[jump_target(PC)] is false</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> if sub_for_pc[PC] is not current_sub</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> return true</span></span> <span class="giallo-l"><span> }</span></span></code></pre> <p>Note that code like this is already run by EVMs to check dynamic jumps, including building the jump destination set every time a contract is run, and doing a lookup in the jump destination set before every jump.</p> <h4 id="subroutine-validation">Subroutine Validation</h4> <p>This function can be seen as a symbolic execution of a subroutine in the EVM code, where only the effect of the instructions on the state being validated is computed. Thus the structure of this function is very similar to an EVM interpreter. This function can also be seen as an acyclic traversal of the directed graph formed by taking instructions as vertices and sequential and branching connections as edges, checking conditions along the way. The traversal is accomplished via recursion, and cycles are broken by returning when a vertex which has already been visited is reached. The time complexity of this traversal is <code>O(|E|+|V|)</code>: The sum of the number of edges and number of vertices in the graph.</p> <p>The basic approach is to call <code>validate_subroutine(i, 0, 0)</code>, for <code>i</code> equal to the first instruction in the EVM code through each <code>BEGINDATA</code> offset. <code>validate_subroutine()</code> traverses instructions sequentially, recursing when <code>JUMP</code> and <code>JUMPI</code> instructions are encountered. When a destination is reached that has been visited before it returns, thus breaking cycles. It returns true if the subroutine is valid, false otherwise.</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span> bytecode[code_size] // contains EVM bytecode to validate</span></span> <span class="giallo-l"><span> frame_size[code_size ] // is filled with -1</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // we validate each subroutine individually, as if at top level</span></span> <span class="giallo-l"><span> // * PC is the offset in the code to start validating at</span></span> <span class="giallo-l"><span> // * return_pc is the top PC on return stack that RETURNSUB returns to</span></span> <span class="giallo-l"><span> // * at top level FP = SP = 0 is both the frame size and the stack size</span></span> <span class="giallo-l"><span> // * as items are pushed SP get more negative, so the stack size is -SP</span></span> <span class="giallo-l"><span> validate_subroutine(PC, return_pc, SP)</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> // traverse code sequentially, recurse for jumps</span></span> <span class="giallo-l"><span> while true</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> instruction = bytecode[PC]</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // if frame size set we have been here before</span></span> <span class="giallo-l"><span> if frame_size[PC] &gt;= 0</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> // check for constant frame size</span></span> <span class="giallo-l"><span> if instruction is JUMPDEST</span></span> <span class="giallo-l"><span> if -SP != frame_size[PC]</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // return to break cycle</span></span> <span class="giallo-l"><span> return true</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> frame_size[PC] = -SP</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // effect of instruction on stack</span></span> <span class="giallo-l"><span> n_removed = removed_items(instructions)</span></span> <span class="giallo-l"><span> n_added = added_items(instruction)</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // check for stack underflow</span></span> <span class="giallo-l"><span> if -SP &lt; n_removed</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // net effect of removing and adding stack items</span></span> <span class="giallo-l"><span> SP += n_removed</span></span> <span class="giallo-l"><span> SP -= n_added</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // check for stack overflow</span></span> <span class="giallo-l"><span> if -SP &gt; 1024</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if instruction is STOP, RETURN, or SUICIDE</span></span> <span class="giallo-l"><span> return true</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // violates single entry</span></span> <span class="giallo-l"><span> if instruction is BEGINSUB</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // return to top or from recursion to JUMPSUB</span></span> <span class="giallo-l"><span> if instruction is RETURNSUB</span></span> <span class="giallo-l"><span> return true;;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> if instruction is JUMPSUB</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> // check for enough arguments</span></span> <span class="giallo-l"><span> sub_pc = jump_target(PC)</span></span> <span class="giallo-l"><span> if -SP &lt; n_args(sub_pc)</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> return true</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // reset PC to destination of jump</span></span> <span class="giallo-l"><span> if instruction is JUMPTO</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> PC = jump_target(PC)</span></span> <span class="giallo-l"><span> continue</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // recurse to jump to code to validate</span></span> <span class="giallo-l"><span> if instruction is JUMPIF</span></span> <span class="giallo-l"><span> {</span></span> <span class="giallo-l"><span> if not validate_subroutine(jump_target(PC), return_pc, SP)</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // advance PC according to instruction</span></span> <span class="giallo-l"><span> PC = advance_pc(PC)</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> // check for right number of results</span></span> <span class="giallo-l"><span> if (-SP != n_results(return_pc)</span></span> <span class="giallo-l"><span> return false</span></span> <span class="giallo-l"><span> return true</span></span> <span class="giallo-l"><span> }</span></span></code></pre><h2 id="appendix-b">Appendix B</h2> <h3 id="evm-analysis">EVM Analysis</h3> <p>There is a large and growing ecosystem of researchers, authors, teachers, auditors, and analytic tools--providing software and services focused on the correctness and security of EVM code. A small sample is given here.</p> <h4 id="some-tools">Some Tools</h4> <ul> <li><a rel="external" href="https://contract-library.com/">Contract Library</a></li> <li><a rel="external" href="https://github.com/ethereum/ethereumj">EthereumJ</a></li> <li><a rel="external" href="https://github.com/exthereum/blockchain">Exthereum</a></li> <li><a rel="external" href="https://github.com/ether-camp/ethereum-harmony">Harmony</a></li> <li><a rel="external" href="https://www.pnfsoftware.com/blog/ethereum-smart-contract-decompiler/">JEB</a></li> <li><a rel="external" href="https://github.com/ConsenSys/mythril">Mythril</a></li> <li><a rel="external" href="https://github.com/eth-sri/securify">Securify</a></li> <li><a rel="external" href="https://www.skalelabs.com/">Skale</a></li> <li><a rel="external" href="https://status.im/">Status</a></li> </ul> <h4 id="some-papers">Some Papers</h4> <ul> <li><a rel="external" href="https://www.google.com/url?q=http://fsl.cs.illinois.edu/FSL/papers/2018/park-zhang-saxena-daian-rosu-2018-fse/park-zhang-saxena-daian-rosu-2018-fse-public.pdf">A Formal Verification Tool for Ethereum VM Bytecode</a></li> <li><a rel="external" href="https://github.com/pirapira/eth-isabelle">A Lem formalization of EVM and some Isabelle/HOL proofs</a></li> <li><a rel="external" href="https://eprint.iacr.org/2016/1007.pdf">A survey of attacks on Ethereum smart contracts</a></li> <li><a rel="external" href="https://www.google.com/url?q=http://fc17.ifca.ai/wtsc/Defining%2520the%2520Ethereum%2520Virtual%2520Machine%2520for%2520Interactive%2520Theorem%2520Provers.pdf">Defining the Ethereum Virtual Machine for Interactive Theorem Provers</a></li> <li><a rel="external" href="https://github.com/ethereum/eth2.0-specs">Ethereum 2.0 Specifications</a></li> <li><a rel="external" href="https://www.cs.umd.edu/~aseem/solidetherplas.pdf">Formal Verification of Smart Contracts</a></li> <li><a rel="external" href="https://jellopaper.org/">JelloPaper: Human Readable Semantics of EVM in K</a></li> <li><a rel="external" href="https://www.ideals.illinois.edu/items/102260">KEVM: A Complete Semantics of the Ethereum Virtual Machine.</a></li> <li><a rel="external" href="https://eprint.iacr.org/2016/633.pdf">Making Smart Contracts Smarter</a></li> <li><a rel="external" href="https://arxiv.org/pdf/1806.01143.pdf">Securify: Practical Security Analysis of Smart Contracts</a></li> <li><a rel="external" href="https://docs.thundercore.com/thunder-whitepaper.pdf">The Thunder Protocol</a></li> <li><a rel="external" href="https://trustworthy.systems/publications/full_text/Amani_BBS_18.pdf">Towards Verifying Ethereum Smart Contract Bytecode in Isabelle/HOL</a> *<a rel="external" href="https://github.com/seed/eth-isabelle/tree/evm15">A Lem formalization of EVM 1.5</a></li> </ul> <h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2016-06-05T00:00:00+00:00 2026-02-11T14:49:27+00:00 Ronan Sandfordhttps://github.com/wighawag https://wg-eips.ritovision.com/107/ <h2 id="abstract">Abstract</h2> <p>This draft EIP describes the details of an authorization method that if provided by rpc enabled ethereum nodes would allow regular websites to send transactions (via <code>eth_sendTransaction</code>) without the need to enable CORS. Instead, user would be asked to confirm the transaction via an html popup.</p> <p>Every read only rpc call the dapp wants to perform is redirected to an invisible iframe from the node's domain and for every transaction that the dapp wish to execute, an html popup is presented to the user to allow him/her to cancel or confirm the transaction. This allows the dapp to connect to the node's rpc api without being granted any kind of privileges. This allows users to safely interact with dapps running in their everyday web browser while their accounts are unlocked. In case the account is not unlocked, and the node has allowed the "personal" api via rpc,the html page also allow the user to enter their password to unlock the account for the scope of the transaction.</p> <h2 id="motivation">Motivation</h2> <p>Currently, if a user navigates to a dapp running on a website using her/his everyday browser, the dapp will by default have no access to the rpc api for security reasons. The user will have to enable CORS for the website's domain in order for the dapp to work. Unfortunately if the user does so, the dapp will be able to send transactions from any unlocked account without the need for any user consent. In other words, not only does the user need to change the node's default setting, but the user is also forced to trust the dapp in order to use it. This is of course not acceptable and forces existing dapps to rely on the use of workarounds like:</p> <ul> <li>if the transaction is a plain ether transfer, the user is asked to enter it in a dedicated trusted wallet like "Mist"</li> <li>For more complex case, the user is asked to enter the transaction manually via the node command line interface.</li> </ul> <p>This proposal aims to provide a safe and user friendly alternative.</p> <p>Here are some screenshots of the provided implementation of that html popup:</p> <h3 id="account-unlocked">Account unlocked</h3> <p>When the account is already unlocked, the user is presented with the following popup for every transaction that the dapp attempts to make:</p> <p><img src="https://wg-eips.ritovision.com/107/./assets/authorization.png" alt="" /></p> <h3 id="account-locked-and-no-personal-api-exposed-via-rpc">Account locked and no "personal" api exposed via rpc:</h3> <p>When the account is locked, and the node does not provide access to account unlocking via its rpc interface, the following popup will be presented. This is not ideal since this requires the user to know how to unlock an account:</p> <p><img src="https://wg-eips.ritovision.com/107/./assets/authorization-locked.png" alt="" /></p> <h3 id="account-locked-but-node-exposing-the-personal-api-via-rpc">Account locked but node exposing the "personal" api via rpc :</h3> <p>A better option is to ask the user for their password, but this is only possible if the node allows access to the "personal" api via rpc. In such case, the following dialog will be presented to the user so he/she can accept the transaction by providing the password required to unlock the account:</p> <p><img src="https://wg-eips.ritovision.com/107/./assets/authorization-password.png" alt="" /></p> <h2 id="specification">Specification</h2> <p>In order for the mechanism to work, the node needs to serve an html file via http at the url &lt;node url&gt;/authorization.html</p> <p>This file will then be used by the dapp in 2 different modes (invisible iframe and popup window).</p> <p>The invisible iframe will be embedded in the dapp to allow the dapp to send its read-only rpc call without having to enable CORS for the dapp's website domain. This is done by sending message to the iframe (via javascript <code>window.postMessage</code>) which in turn execute the rpc call. This works since the iframe and the node share the same domain/port.</p> <p>In the iframe mode, the html file's javascript code will ensure that no call requiring an unlocked key can be made. This is to prevent dapps from embedding the invisible iframe and tricking the user into clicking the confirm button. If the dapp requires an <code>eth_sendTransaction</code> call, the dapp will instead open a new window using the same url.</p> <p>In this popup window mode, the html file's javascript code will allow <code>eth_sendTransaction</code> (but not <code>eth_sign</code>, as there is no way to display to the user the meaningful content of the transaction to sign in a safe way) to be called. But instead of sending the call to the node directly, a confirmation dialog will be presented showing the sender and recipient addresses, as well as the amount being transferred along with the potential gas cost. Upon the user approving, the request will be sent and the result returned to the dapp. An error will be returned in case the user cancel the request.</p> <p>The html page also checks for the availability of the "personal" api and if so, will ask the user to unlock the account if necessary. The unlocking is temporary (3s) so the password will be asked again if a transaction is attempted before the end of this short time.</p> <p>In both iframe mode and window mode, the communication with the dapp is achieved using <code>window.postMessage</code>. The first message the iframe/window sends is a message containing the string "ready" to let the dapp know that it now accepts messages. Then the dapp can start performing rpc call by sending message using the following object :</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> id:&lt;an id&gt;, //so responses can be match as there is no guarantee of the order of the response</span></span> <span class="giallo-l"><span> payload:&lt;json rpc object&gt; //this is the exact object that usually send to the node</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>For <code>eth_sendTransaction</code> the "gas", "gasPrice" and "from" field need to be set in the rpc parameter so that the window can display the correct value. If not all of these are passed in, the window will return an error.</p> <p>Upon receiving such message, the iframe will perform the actual rpc call to the node but only if such a call is a read only call (not requiring an unlocked key). If it is not it will return a error. The window on the other will only accept <code>eth_sendTransaction</code> calls but will display a dialog so the user can accept or cancel the request.</p> <p>In all the cases, the iframe/window will send a message back to the dapp using the following object:</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> id:&lt;id matching the request&gt;,</span></span> <span class="giallo-l"><span> result:&lt;rpc result as is&gt;,</span></span> <span class="giallo-l"><span> error:&lt;error object&gt;</span></span> <span class="giallo-l"><span>}</span></span></code></pre> <p>the error object cannot be a javascript Error object due to postMessage limitation. Instead it is</p> <pre class="giallo z-code"><code data-lang="plain"><span class="giallo-l"><span>{</span></span> <span class="giallo-l"><span> message:&lt;a string describing the error&gt;,</span></span> <span class="giallo-l"><span> type:&lt;a string defining the type of error&gt; //type=&quot;cancel&quot; means the user cancel the transaction</span></span> <span class="giallo-l"><span>}</span></span></code></pre><h2 id="rationale">Rationale</h2> <p>The design for that proposal was chosen for its simplicity and security. A previous idea was to use an oauth-like protocol in order for the user to accept or deny a transaction request. It would have required deeper code change in the node and some geth contributors argues that such change did not fit into geth code base as it would have required dapp aware code. The current design, instead has a very simple implementation (self contained html file that can be shared across node's implementation) and its safeness is guaranteed by browsers' cross domain policies.</p> <p>The use of iframe/ window was required to have both security and user friendliness. The invisible iframe allows the dapp to execute read only calls without the need for user input, and the window ensures user approval before making a call. While we could have made it without the window mode by making the iframe confirmation use the native browser <code>window.confirm</code> dialog, this would have prevented the use of a more elegant confirmation popup that the current design allows. It also happens to be that the <code>window.confirm</code> is not safe in some browsers, as it gives focus to the accept option and can be triggered automatically (https://bugs.chromium.org/p/chromium/issues/detail?id=260653).</p> <h2 id="implementations">Implementations</h2> <p>In order to implement this design, the following html file or an equivalent one needs to be served at the url &lt;node url&gt;/authorization.html</p> <p>That's it.</p> <pre class="giallo z-code"><code data-lang="html"><span class="giallo-l"><span>&lt;!</span><span class="z-entity z-name z-tag">DOCTYPE</span><span class="z-entity"> html</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;</span><span class="z-entity z-name z-tag">html</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">head</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">title</span><span>&gt;</span><span>Ethereum Authorization</span><span>&lt;/</span><span class="z-entity z-name z-tag">title</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">head</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">script</span><span>&gt;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment">https://github.com/alexvandesande/blockies</span></span> <span class="giallo-l"><span class="z-keyword"> !</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> r</span><span>(</span><span class="z-variable">r</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">l</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">++</span><span>)</span><span class="z-variable z-other">l</span><span>[</span><span class="z-variable z-other">t</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">r</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">++</span><span>)</span><span class="z-variable z-other">l</span><span>[</span><span class="z-variable z-other">t</span><span class="z-keyword">%</span><span class="z-constant">4</span><span>]</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">l</span><span>[</span><span class="z-variable z-other">t</span><span class="z-keyword">%</span><span class="z-constant">4</span><span>]</span><span class="z-keyword">&lt;&lt;</span><span class="z-constant">5</span><span>)</span><span class="z-keyword">-</span><span class="z-variable z-other">l</span><span>[</span><span class="z-variable z-other">t</span><span class="z-keyword">%</span><span class="z-constant">4</span><span>]</span><span class="z-keyword">+</span><span class="z-variable z-other">r</span><span>.</span><span class="z-entity z-name">charCodeAt</span><span>(</span><span class="z-variable z-other">t</span><span>)</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> t</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">^</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">&lt;&lt;</span><span class="z-constant">11</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> l</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">2</span><span>]</span><span>,</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">2</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">3</span><span>]</span><span>,</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">3</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">3</span><span>]</span><span class="z-keyword">^</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">3</span><span>]</span><span class="z-keyword">&gt;&gt;</span><span class="z-constant">19</span><span class="z-keyword">^</span><span class="z-variable z-other">r</span><span class="z-keyword">^</span><span class="z-variable z-other">r</span><span class="z-keyword">&gt;&gt;</span><span class="z-constant">8</span><span>,</span><span>(</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">3</span><span>]</span><span class="z-keyword">&gt;&gt;&gt;</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">/</span><span>(</span><span class="z-constant">1</span><span class="z-keyword">&lt;&lt;</span><span class="z-constant">31</span><span class="z-keyword">&gt;&gt;&gt;</span><span class="z-constant">0</span><span>)</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> e</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">floor</span><span>(</span><span class="z-constant">360</span><span class="z-keyword">*</span><span class="z-entity z-name">t</span><span>(</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">60</span><span class="z-keyword">*</span><span class="z-entity z-name">t</span><span>(</span><span>)</span><span class="z-keyword">+</span><span class="z-constant">40</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">%</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-constant">25</span><span class="z-keyword">*</span><span>(</span><span class="z-entity z-name">t</span><span>(</span><span>)</span><span class="z-keyword">+</span><span class="z-entity z-name">t</span><span>(</span><span>)</span><span class="z-keyword">+</span><span class="z-entity z-name">t</span><span>(</span><span>)</span><span class="z-keyword">+</span><span class="z-entity z-name">t</span><span>(</span><span>)</span><span>)</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">%</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">hsl(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">r</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">o</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">)</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> n</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> o</span><span>(</span><span class="z-variable">r</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> e</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">ceil</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-constant">2</span><span>)</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span>[</span><span>]</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">c</span><span>;</span><span class="z-variable z-other">c</span><span class="z-keyword">++</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> f</span><span class="z-keyword">=</span><span>[</span><span>]</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">h</span><span>;</span><span class="z-variable z-other">h</span><span class="z-keyword">++</span><span>)</span><span class="z-variable z-other">f</span><span>[</span><span class="z-variable z-other">h</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">floor</span><span>(</span><span class="z-constant">2</span><span class="z-constant">.</span><span class="z-constant">3</span><span class="z-keyword">*</span><span class="z-entity z-name">t</span><span>(</span><span>)</span><span>)</span><span>;</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> i</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">a</span><span>)</span><span>;</span><span class="z-variable z-other">i</span><span>.</span><span class="z-entity z-name">reverse</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">concat</span><span>(</span><span class="z-variable z-other">i</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> v</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">v</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">f</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other">v</span><span class="z-keyword">++</span><span>)</span><span class="z-variable z-other">l</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-variable z-other">f</span><span>[</span><span class="z-variable z-other">v</span><span>]</span><span>)</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> l</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> n</span><span>(</span><span class="z-variable">r</span><span>,</span><span class="z-variable">t</span><span>,</span><span class="z-variable">e</span><span>,</span><span class="z-variable">o</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> a</span><span class="z-keyword">=</span><span class="z-variable z-other">document</span><span>.</span><span class="z-entity z-name">createElement</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">canvas</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">sqrt</span><span>(</span><span class="z-variable z-other">r</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span>;</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">width</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">height</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span class="z-keyword">*</span><span class="z-variable z-other">e</span><span>;</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> c</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">getContext</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">2d</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span><span class="z-variable z-other">c</span><span>.</span><span class="z-variable z-other">fillStyle</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">c</span><span>.</span><span class="z-entity z-name">fillRect</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">width</span><span>,</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">height</span><span>)</span><span>,</span><span class="z-variable z-other">c</span><span>.</span><span class="z-variable z-other">fillStyle</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> f</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">f</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">r</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other">f</span><span class="z-keyword">++</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> h</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">floor</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">/</span><span class="z-variable z-other">l</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span class="z-keyword">%</span><span class="z-variable z-other">l</span><span>;</span><span class="z-variable z-other">c</span><span>.</span><span class="z-variable z-other">fillStyle</span><span class="z-keyword">=</span><span class="z-constant">1</span><span class="z-keyword">==</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">f</span><span>]</span><span class="z-keyword">?</span><span class="z-variable z-other">t</span><span class="z-keyword">:</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">f</span><span>]</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">c</span><span>.</span><span class="z-entity z-name">fillRect</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">*</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">*</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> a</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> a</span><span>(</span><span class="z-variable">t</span><span>)</span><span>{</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span class="z-keyword">||</span><span>{</span><span>}</span><span>;</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> a</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">size</span><span class="z-keyword">||</span><span class="z-constant">8</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">scale</span><span class="z-keyword">||</span><span class="z-constant">4</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">seed</span><span class="z-keyword">||</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">floor</span><span>(</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">random</span><span>(</span><span>)</span><span class="z-keyword">*</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">pow</span><span>(</span><span class="z-constant">10</span><span>,</span><span class="z-constant">16</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span class="z-constant">16</span><span>)</span><span>;</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">c</span><span>)</span><span>;</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> f</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">color</span><span class="z-keyword">||</span><span class="z-entity z-name">e</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">bgcolor</span><span class="z-keyword">||</span><span class="z-entity z-name">e</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">spotcolor</span><span class="z-keyword">||</span><span class="z-entity z-name">e</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">v</span><span class="z-keyword">=</span><span class="z-entity z-name">o</span><span>(</span><span class="z-variable z-other">a</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-entity z-name">n</span><span>(</span><span class="z-variable z-other">v</span><span>,</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">h</span><span>,</span><span class="z-variable z-other">i</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> u</span><span>}</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> l</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> Array</span><span>(</span><span class="z-constant">4</span><span>)</span><span>;</span><span class="z-variable z-other">window</span><span>.</span><span class="z-variable z-other">blockies</span><span class="z-keyword">=</span><span>{</span><span>create</span><span>:</span><span class="z-variable z-other">a</span><span>}</span><span>}</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /*</span><span class="z-comment"> bignumber.js v2.3.0 https://github.com/MikeMcl/bignumber.js/LICENCE </span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span class="z-keyword"> !</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">use strict</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> n</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span>,</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword"> instanceof</span><span class="z-entity z-name"> E</span><span>)</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-constant">26</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">constructor call without new</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">n</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-constant">64</span><span>,</span><span class="z-variable z-other z-constant">M</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">base</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-constant">10</span><span class="z-keyword">==</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> f</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword"> instanceof</span><span class="z-entity z-name"> E</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-variable z-other">s</span><span>)</span><span>,</span><span class="z-entity z-name">U</span><span>(</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other z-constant">P</span><span class="z-keyword">+</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">k</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">number</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">==</span><span class="z-keyword">typeof</span><span class="z-variable z-other"> e</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-constant">0</span><span class="z-keyword">*</span><span class="z-variable z-other">e</span><span class="z-keyword">!=</span><span class="z-constant">0</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-keyword">new</span><span class="z-entity z-name"> RegExp</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">^-?</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other z-constant">N</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">]+</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">(?:</span><span class="z-constant">\\</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">t</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">)?$</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-constant">37</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span class="z-keyword">?</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">i</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>.</span><span class="z-entity z-name">test</span><span>(</span><span class="z-variable z-other">s</span><span>)</span><span>)</span><span class="z-keyword">return</span><span class="z-entity z-name"> h</span><span>(</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-constant">1</span><span class="z-keyword">/</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">:</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">replace</span><span>(</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-string z-regexp">0</span><span class="z-constant z-character z-escape">\.</span><span class="z-string z-regexp">0</span><span class="z-keyword">*</span><span class="z-keyword">|</span><span class="z-constant z-character z-escape">\.</span><span class="z-punctuation z-definition z-string">/</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">&gt;</span><span class="z-constant">15</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-variable z-other z-constant">M</span><span>,</span><span class="z-variable z-other">v</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">45</span><span class="z-keyword">===</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">charCodeAt</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">:</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-entity z-name">D</span><span>(</span><span class="z-variable z-other">s</span><span>,</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">s</span><span>)</span><span>}</span><span class="z-keyword">else</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword"> instanceof</span><span class="z-entity z-name"> E</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> f</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">e</span><span>,</span><span class="z-keyword">void</span><span>(</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">number</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">==</span><span class="z-keyword">typeof</span><span class="z-variable z-other"> e</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-constant">0</span><span class="z-keyword">*</span><span class="z-variable z-other">e</span><span class="z-keyword">==</span><span class="z-constant">0</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-constant">1</span><span class="z-keyword">/</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">e</span><span>,</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">:</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">===</span><span class="z-keyword">~</span><span class="z-keyword">~</span><span class="z-variable z-other">e</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">&gt;=</span><span class="z-constant">10</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> f</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other">e</span><span>]</span><span>,</span><span class="z-keyword">void</span><span>(</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>)</span><span>}</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span class="z-keyword">else</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">g</span><span>.</span><span class="z-entity z-name">test</span><span>(</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span><span class="z-keyword">return</span><span class="z-entity z-name"> h</span><span>(</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">o</span><span>)</span><span>;</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">45</span><span class="z-keyword">===</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">charCodeAt</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">:</span><span class="z-constant">1</span><span>}</span><span>}</span><span class="z-keyword">for</span><span>(</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">indexOf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span><span class="z-keyword">&gt;</span><span class="z-keyword">-</span><span class="z-constant">1</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">replace</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span><span>,</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">search</span><span>(</span><span class="z-punctuation z-definition z-string">/</span><span class="z-string z-regexp">e</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">i</span><span>)</span><span>)</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">r</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">+=</span><span class="z-keyword">+</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">substring</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">i</span><span>)</span><span>)</span><span class="z-keyword">:</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">r</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-constant">48</span><span class="z-keyword">===</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">charCodeAt</span><span>(</span><span class="z-variable z-other">i</span><span>)</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-constant">48</span><span class="z-keyword">===</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">charCodeAt</span><span>(</span><span class="z-keyword">--</span><span class="z-variable z-other">u</span><span>)</span><span>;</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>)</span><span>)</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;</span><span class="z-constant">15</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">y</span><span class="z-keyword">||</span><span class="z-variable z-other">e</span><span class="z-keyword">!==</span><span class="z-entity z-name">d</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-variable z-other z-constant">M</span><span>,</span><span class="z-variable z-other">v</span><span>,</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">*</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span class="z-keyword">-</span><span class="z-variable z-other">i</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">z</span><span>)</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">null</span><span>;</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other z-constant">G</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">r</span><span>)</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-keyword">else</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>[</span><span>]</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">%</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">r</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">+=</span><span class="z-variable z-other z-constant">O</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">i</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">c</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-keyword">+</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">i</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">-=</span><span class="z-variable z-other z-constant">O</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">i</span><span>;</span><span>)</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">c</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-keyword">+</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">+=</span><span class="z-variable z-other z-constant">O</span><span>)</span><span>)</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-variable z-other">i</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">-</span><span class="z-variable z-other">s</span><span>.</span><span class="z-support z-variable">length</span><span>}</span><span class="z-keyword">else</span><span class="z-variable z-other"> i</span><span class="z-keyword">-=</span><span class="z-variable z-other">u</span><span>;</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">--</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">+=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">c</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-keyword">+</span><span class="z-variable z-other">s</span><span>)</span><span>}</span><span class="z-keyword">else</span><span class="z-variable z-other"> f</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> D</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>,</span><span class="z-variable">i</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">h</span><span>,</span><span class="z-variable z-other">g</span><span>,</span><span class="z-variable z-other">p</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">indexOf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span class="z-variable z-other">d</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">P</span><span>,</span><span class="z-variable z-other">m</span><span class="z-keyword">=</span><span class="z-variable z-other">k</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-constant">37</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">toLowerCase</span><span>(</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">p</span><span class="z-keyword">&gt;=</span><span class="z-constant">0</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">J</span><span>,</span><span class="z-variable z-other z-constant">J</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">replace</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span class="z-variable z-other">g</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">t</span><span>)</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">g</span><span>.</span><span class="z-entity z-name">pow</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">-</span><span class="z-variable z-other">p</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">J</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">g</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-entity z-name">s</span><span>(</span><span class="z-entity z-name">l</span><span>(</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span>,</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-variable z-other">g</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">g</span><span>.</span><span class="z-variable z-other">c</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-entity z-name">s</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">t</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-other">h</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">f</span><span>]</span><span>;</span><span class="z-variable z-other">h</span><span>.</span><span class="z-entity z-name">pop</span><span>(</span><span>)</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">h</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-keyword">return</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">p</span><span class="z-keyword">?</span><span class="z-keyword">--</span><span class="z-variable z-other">u</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>,</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">g</span><span>,</span><span class="z-variable z-other">d</span><span>,</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span class="z-keyword">+</span><span class="z-variable z-other">d</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">p</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">o</span><span>]</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span class="z-keyword">/</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span class="z-keyword">||</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">o</span><span class="z-keyword">||</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">o</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-constant">4</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">m</span><span class="z-keyword">?</span><span>(</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">p</span><span class="z-keyword">||</span><span class="z-variable z-other">c</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-other">m</span><span class="z-keyword">||</span><span class="z-variable z-other">m</span><span class="z-keyword">==</span><span>(</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-constant">3</span><span class="z-keyword">:</span><span class="z-constant">2</span><span>)</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">p</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">f</span><span class="z-keyword">||</span><span class="z-variable z-other">p</span><span class="z-keyword">==</span><span class="z-variable z-other">f</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-constant">4</span><span class="z-keyword">==</span><span class="z-variable z-other">m</span><span class="z-keyword">||</span><span class="z-variable z-other">c</span><span class="z-keyword">||</span><span class="z-constant">6</span><span class="z-keyword">==</span><span class="z-variable z-other">m</span><span class="z-keyword">&amp;&amp;</span><span class="z-constant">1</span><span class="z-keyword">&amp;</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">o</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">||</span><span class="z-variable z-other">m</span><span class="z-keyword">==</span><span>(</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-constant">8</span><span class="z-keyword">:</span><span class="z-constant">7</span><span>)</span><span>)</span><span>,</span><span class="z-constant">1</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">o</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">h</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span class="z-keyword">?</span><span class="z-entity z-name">l</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-keyword">-</span><span class="z-variable z-other">d</span><span>)</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span><span class="z-keyword">else</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">h</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">c</span><span>)</span><span class="z-keyword">for</span><span>(</span><span class="z-keyword">--</span><span class="z-variable z-other">n</span><span>;</span><span class="z-keyword">++</span><span class="z-variable z-other">h</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">o</span><span>]</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span>;</span><span>)</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">o</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">||</span><span>(</span><span class="z-keyword">++</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">h</span><span>.</span><span class="z-entity z-name">unshift</span><span>(</span><span class="z-constant">1</span><span>)</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-keyword">!</span><span class="z-variable z-other">h</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">f</span><span>]</span><span>;</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">p</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span><span class="z-variable z-other">f</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">p</span><span>;</span><span class="z-variable z-other">e</span><span class="z-keyword">+=</span><span class="z-variable z-other z-constant">N</span><span>.</span><span class="z-entity z-name">charAt</span><span>(</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">p</span><span class="z-keyword">++</span><span>]</span><span>)</span><span>)</span><span>;</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-entity z-name">l</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">u</span><span>)</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> F</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>,</span><span class="z-variable">i</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">a</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">t</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">t</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">8</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">w</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">t</span><span class="z-keyword">:</span><span class="z-variable z-other">k</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">null</span><span class="z-keyword">==</span><span class="z-variable z-other">n</span><span>)</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-constant">19</span><span class="z-keyword">==</span><span class="z-variable z-other">i</span><span class="z-keyword">||</span><span class="z-constant">24</span><span class="z-keyword">==</span><span class="z-variable z-other">i</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other z-constant">B</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">s</span><span class="z-keyword">?</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">s</span><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name">l</span><span>(</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">s</span><span>)</span><span>;</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-entity z-name">U</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">t</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-constant">19</span><span class="z-keyword">==</span><span class="z-variable z-other">i</span><span class="z-keyword">||</span><span class="z-constant">24</span><span class="z-keyword">==</span><span class="z-variable z-other">i</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">n</span><span class="z-keyword">||</span><span class="z-variable z-other z-constant">B</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">u</span><span>)</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">c</span><span>;</span><span class="z-variable z-other">a</span><span class="z-keyword">+=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">u</span><span>)</span><span>}</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">-=</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-entity z-name">l</span><span>(</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">u</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">+</span><span class="z-constant">1</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">c</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">--</span><span class="z-variable z-other">n</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">a</span><span class="z-keyword">+=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">--</span><span>;</span><span class="z-variable z-other">a</span><span class="z-keyword">+=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span><span>}</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">+=</span><span class="z-variable z-other">u</span><span class="z-keyword">-</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">+</span><span class="z-constant">1</span><span class="z-keyword">==</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">a</span><span class="z-keyword">+=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">--</span><span>;</span><span class="z-variable z-other">a</span><span class="z-keyword">+=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">o</span><span class="z-keyword">?</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">-</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">a</span><span class="z-keyword">:</span><span class="z-variable z-other">a</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> _</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span>,</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-entity z-name">u</span><span>(</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span>;</span><span class="z-keyword">++</span><span class="z-variable z-other">i</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">e</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>)</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">r</span><span>.</span><span class="z-variable z-other">s</span><span>)</span><span>{</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>;</span><span class="z-keyword">break</span><span>}</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span class="z-variable z-other">t</span><span>,</span><span class="z-variable z-other">r</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>)</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> t</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> x</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>,</span><span class="z-variable">r</span><span>,</span><span class="z-variable">i</span><span>)</span><span>{</span><span class="z-keyword">return</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-variable z-other">e</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span class="z-keyword">||</span><span class="z-variable z-other">e</span><span class="z-keyword">!=</span><span class="z-entity z-name">c</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-variable z-other">r</span><span>,</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">||</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">decimal places</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-variable z-other">e</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> out of range</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> not an integer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-keyword">!</span><span class="z-constant">0</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> I</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-keyword">!</span><span class="z-variable z-other">n</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">i</span><span>]</span><span>;</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">pop</span><span>(</span><span>)</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">&gt;=</span><span class="z-constant">10</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-keyword">return</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span class="z-keyword">+</span><span class="z-variable z-other">t</span><span class="z-keyword">*</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">z</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">null</span><span class="z-keyword">:</span><span class="z-variable z-other z-constant">G</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>,</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> L</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> Error</span><span>(</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">new BigNumber</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">cmp</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">config</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">div</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">divToInt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eq</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">gt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">gte</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">lt</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">lte</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">minus</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">mod</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">plus</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">precision</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">random</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">round</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">shift</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">times</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">toDigits</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">toExponential</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">toFixed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">toFormat</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">toFraction</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">pow</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">toPrecision</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">toString</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">BigNumber</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>[</span><span class="z-variable z-other">e</span><span>]</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">() </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">n</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">: </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">t</span><span>)</span><span>;</span><span class="z-keyword">throw</span><span class="z-variable z-other"> r</span><span>.</span><span class="z-variable z-other">name</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">BigNumber Error</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">r</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> U</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>,</span><span class="z-variable">r</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> i</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">S</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">a</span><span>)</span><span>{</span><span class="z-entity z-name">e</span><span>:</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">&gt;=</span><span class="z-constant">10</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span class="z-keyword">-</span><span class="z-variable z-other">i</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">o</span><span>)</span><span class="z-variable z-other">o</span><span class="z-keyword">+=</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span class="z-keyword">/</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">i</span><span class="z-keyword">-</span><span class="z-variable z-other">u</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">%</span><span class="z-constant">10</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>;</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-entity z-name">p</span><span>(</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>)</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">r</span><span>)</span><span class="z-keyword">break</span><span class="z-entity z-name"> e</span><span>;</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-variable z-other">a</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">&lt;=</span><span class="z-variable z-other">l</span><span>;</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span>;</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">%=</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span class="z-keyword">-</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>}</span><span class="z-keyword">else</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">l</span><span>]</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">&gt;=</span><span class="z-constant">10</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">%=</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span class="z-keyword">-</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">+</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">u</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-variable z-other">f</span><span class="z-keyword">/</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">i</span><span class="z-keyword">-</span><span class="z-variable z-other">u</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">%</span><span class="z-constant">10</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>}</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span class="z-keyword">||</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span class="z-keyword">||</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">l</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">||</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">u</span><span class="z-keyword">?</span><span class="z-variable z-other">f</span><span class="z-keyword">:</span><span class="z-variable z-other">f</span><span class="z-keyword">%</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">i</span><span class="z-keyword">-</span><span class="z-variable z-other">u</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-constant">4</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">c</span><span class="z-keyword">||</span><span class="z-variable z-other">r</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-other">t</span><span class="z-keyword">||</span><span class="z-variable z-other">t</span><span class="z-keyword">==</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-constant">3</span><span class="z-keyword">:</span><span class="z-constant">2</span><span>)</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">c</span><span class="z-keyword">&gt;</span><span class="z-constant">5</span><span class="z-keyword">||</span><span class="z-constant">5</span><span class="z-keyword">==</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-constant">4</span><span class="z-keyword">==</span><span class="z-variable z-other">t</span><span class="z-keyword">||</span><span class="z-variable z-other">r</span><span class="z-keyword">||</span><span class="z-constant">6</span><span class="z-keyword">==</span><span class="z-variable z-other">t</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-variable z-other">f</span><span class="z-keyword">/</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">i</span><span class="z-keyword">-</span><span class="z-variable z-other">u</span><span>]</span><span class="z-keyword">:</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">l</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span>)</span><span class="z-keyword">%</span><span class="z-constant">10</span><span class="z-keyword">&amp;</span><span class="z-constant">1</span><span class="z-keyword">||</span><span class="z-variable z-other">t</span><span class="z-keyword">==</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-constant">8</span><span class="z-keyword">:</span><span class="z-constant">7</span><span>)</span><span>)</span><span>,</span><span class="z-constant">1</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> a</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">-=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>[</span><span>(</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span class="z-keyword">%</span><span class="z-variable z-other z-constant">O</span><span>)</span><span class="z-keyword">%</span><span class="z-variable z-other z-constant">O</span><span>]</span><span>,</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span class="z-keyword">||</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">e</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-other">o</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">a</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">--</span><span>)</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">a</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">-</span><span class="z-variable z-other">o</span><span>]</span><span>,</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">l</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-entity z-name">d</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">/</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">i</span><span class="z-keyword">-</span><span class="z-variable z-other">u</span><span>]</span><span class="z-keyword">%</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">u</span><span>]</span><span>)</span><span class="z-keyword">*</span><span class="z-variable z-other">s</span><span class="z-keyword">:</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>)</span><span class="z-keyword">for</span><span>(</span><span>;</span><span>;</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-other">l</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;=</span><span class="z-constant">10</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">+=</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;=</span><span class="z-constant">10</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">!=</span><span class="z-variable z-other">s</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">++</span><span>,</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">==</span><span class="z-variable z-other">b</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>)</span><span>)</span><span>;</span><span class="z-keyword">break</span><span>}</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">l</span><span>]</span><span class="z-keyword">+=</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">l</span><span>]</span><span class="z-keyword">!=</span><span class="z-variable z-other">b</span><span>)</span><span class="z-keyword">break</span><span>;</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">l</span><span class="z-keyword">--</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>}</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-constant">0</span><span class="z-keyword">===</span><span class="z-variable z-other">a</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">o</span><span>]</span><span>;</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">pop</span><span>(</span><span>)</span><span>)</span><span>;</span><span>}</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">z</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">null</span><span class="z-keyword">:</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">&lt;</span><span class="z-variable z-other z-constant">G</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>]</span><span>)</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span>}</span><span class="z-storage z-type">var</span><span class="z-variable z-other z-constant"> C</span><span>,</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">T</span><span class="z-keyword">=</span><span class="z-support">E</span><span>.</span><span class="z-support z-variable">prototype</span><span>,</span><span class="z-variable z-other">q</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">P</span><span class="z-keyword">=</span><span class="z-constant">20</span><span>,</span><span class="z-variable z-other">k</span><span class="z-keyword">=</span><span class="z-constant">4</span><span>,</span><span class="z-variable z-other z-constant">B</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-constant">7</span><span>,</span><span class="z-variable z-other">$</span><span class="z-keyword">=</span><span class="z-constant">21</span><span>,</span><span class="z-variable z-other z-constant">G</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-constant">1e7</span><span>,</span><span class="z-variable z-other">z</span><span class="z-keyword">=</span><span class="z-constant">1e7</span><span>,</span><span class="z-variable z-other">j</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">H</span><span class="z-keyword">=</span><span class="z-variable z-other">x</span><span>,</span><span class="z-variable z-other z-constant">V</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other z-constant">W</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other z-constant">J</span><span class="z-keyword">=</span><span class="z-constant">100</span><span>,</span><span class="z-variable z-other z-constant">X</span><span class="z-keyword">=</span><span>{</span><span>decimalSeparator</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span>groupSeparator</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">,</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span>groupSize</span><span>:</span><span class="z-constant">3</span><span>,</span><span>secondaryGroupSize</span><span>:</span><span class="z-constant">0</span><span>,</span><span>fractionGroupSeparator</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string"> &quot;</span><span>,</span><span>fractionGroupSize</span><span>:</span><span class="z-constant">0</span><span>}</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> E</span><span>.</span><span class="z-variable z-other">another</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">ROUND_UP</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">ROUND_DOWN</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">ROUND_CEIL</span><span class="z-keyword">=</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">ROUND_FLOOR</span><span class="z-keyword">=</span><span class="z-constant">3</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">ROUND_HALF_UP</span><span class="z-keyword">=</span><span class="z-constant">4</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">ROUND_HALF_DOWN</span><span class="z-keyword">=</span><span class="z-constant">5</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">ROUND_HALF_EVEN</span><span class="z-keyword">=</span><span class="z-constant">6</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">ROUND_HALF_CEIL</span><span class="z-keyword">=</span><span class="z-constant">7</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">ROUND_HALF_FLOOR</span><span class="z-keyword">=</span><span class="z-constant">8</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-variable z-other z-constant">EUCLID</span><span class="z-keyword">=</span><span class="z-constant">9</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-entity z-name">config</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> e</span><span>,</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span>{</span><span>}</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-language">arguments</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span class="z-keyword">&amp;&amp;</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">==</span><span class="z-keyword">typeof</span><span class="z-variable z-other"> s</span><span class="z-keyword">?</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other"> s</span><span>.</span><span class="z-entity z-name">hasOwnProperty</span><span>(</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span>)</span><span class="z-keyword">:</span><span class="z-keyword">void</span><span class="z-constant"> 0</span><span>}</span><span class="z-keyword">:</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other"> i</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>[</span><span class="z-variable z-other">t</span><span class="z-keyword">++</span><span>]</span><span>)</span><span class="z-keyword">:</span><span class="z-keyword">void</span><span class="z-constant"> 0</span><span>}</span><span>;</span><span class="z-keyword">return</span><span class="z-entity z-name"> f</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">DECIMAL_PLACES</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">P</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">P</span><span>,</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ROUNDING_MODE</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">8</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">k</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">k</span><span>,</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">EXPONENTIAL_AT</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-entity z-name">u</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">?</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-keyword">-</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">B</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">$</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">1</span><span>]</span><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-keyword">-</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">B</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span>(</span><span class="z-variable z-other">$</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span class="z-keyword">-</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other z-constant">B</span><span>,</span><span class="z-variable z-other">$</span><span>]</span><span>,</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">RANGE</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-entity z-name">u</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">?</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-keyword">-</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">G</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">z</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">1</span><span>]</span><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-keyword">-</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span class="z-variable z-other z-constant">G</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span>(</span><span class="z-variable z-other">z</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span class="z-keyword">-</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> cannot be zero</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other z-constant">G</span><span>,</span><span class="z-variable z-other">z</span><span>]</span><span>,</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ERRORS</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">===</span><span class="z-keyword">!</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-constant">1</span><span class="z-keyword">===</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-constant">0</span><span class="z-keyword">===</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">H</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">j</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">x</span><span class="z-keyword">:</span><span class="z-variable z-other">o</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">+</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">j</span><span>,</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">CRYPTO</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">===</span><span class="z-keyword">!</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-constant">1</span><span class="z-keyword">===</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-constant">0</span><span class="z-keyword">===</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other z-constant">V</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">a</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other z-constant">V</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-constant">2</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">crypto unavailable</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">a</span><span>)</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">+</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">V</span><span>,</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">MODULO_MODE</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">9</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">W</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">W</span><span>,</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">POW_PRECISION</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">J</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">J</span><span>,</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">FORMAT</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">object</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">==</span><span class="z-keyword">typeof</span><span class="z-variable z-other"> e</span><span class="z-keyword">?</span><span class="z-variable z-other z-constant">X</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> not an object</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">X</span><span>,</span><span class="z-variable z-other">r</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-entity z-name">max</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> _</span><span>(</span><span class="z-variable z-language">arguments</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">lt</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-entity z-name">min</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> _</span><span>(</span><span class="z-variable z-language">arguments</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">gt</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-entity z-name">random</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> e</span><span class="z-keyword">=</span><span class="z-constant">9007199254740992</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">random</span><span>(</span><span>)</span><span class="z-keyword">*</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;</span><span class="z-constant">2097151</span><span class="z-keyword">?</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> d</span><span>(</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">random</span><span>(</span><span>)</span><span class="z-keyword">*</span><span class="z-variable z-other">e</span><span>)</span><span>}</span><span class="z-keyword">:</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-constant"> 8388608</span><span class="z-keyword">*</span><span>(</span><span class="z-constant">1073741824</span><span class="z-keyword">*</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">random</span><span>(</span><span>)</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">+</span><span>(</span><span class="z-constant">8388608</span><span class="z-keyword">*</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">random</span><span>(</span><span>)</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>)</span><span>}</span><span>;</span><span class="z-keyword">return</span><span class="z-storage z-type"> function</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span>,</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span>[</span><span>]</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">q</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">14</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-variable z-other z-constant">P</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-entity z-name">p</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">V</span><span>)</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">a</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">getRandomValues</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">getRandomValues</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> Uint32Array</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">*=</span><span class="z-constant">2</span><span>)</span><span>)</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">s</span><span>;</span><span>)</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-constant">131072</span><span class="z-keyword">*</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span>]</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">&gt;&gt;&gt;</span><span class="z-constant">11</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;=</span><span class="z-constant">9e15</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">getRandomValues</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> Uint32Array</span><span>(</span><span class="z-constant">2</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>[</span><span class="z-constant">1</span><span>]</span><span>)</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">%</span><span class="z-constant">1e14</span><span>)</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">+=</span><span class="z-constant">2</span><span>)</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span class="z-keyword">/</span><span class="z-constant">2</span><span>}</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">a</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">a</span><span>.</span><span class="z-variable z-other">randomBytes</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">randomBytes</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">*=</span><span class="z-constant">7</span><span>)</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">s</span><span>;</span><span>)</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-constant">281474976710656</span><span class="z-keyword">*</span><span>(</span><span class="z-constant">31</span><span class="z-keyword">&amp;</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span>]</span><span>)</span><span class="z-keyword">+</span><span class="z-constant">1099511627776</span><span class="z-keyword">*</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">+</span><span class="z-constant">4294967296</span><span class="z-keyword">*</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-constant">2</span><span>]</span><span class="z-keyword">+</span><span class="z-constant">16777216</span><span class="z-keyword">*</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-constant">3</span><span>]</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-constant">4</span><span>]</span><span class="z-keyword">&lt;&lt;</span><span class="z-constant">16</span><span>)</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-constant">5</span><span>]</span><span class="z-keyword">&lt;&lt;</span><span class="z-constant">8</span><span>)</span><span class="z-keyword">+</span><span class="z-variable z-other">t</span><span>[</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-constant">6</span><span>]</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;=</span><span class="z-constant">9e15</span><span class="z-keyword">?</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">randomBytes</span><span>(</span><span class="z-constant">7</span><span>)</span><span>.</span><span class="z-entity z-name">copy</span><span>(</span><span class="z-variable z-other">t</span><span>,</span><span class="z-variable z-other">s</span><span>)</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">%</span><span class="z-constant">1e14</span><span>)</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">+=</span><span class="z-constant">7</span><span>)</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span class="z-keyword">/</span><span class="z-constant">7</span><span>}</span><span class="z-keyword">else</span><span class="z-variable z-other"> j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-constant">14</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">crypto unavailable</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">a</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">s</span><span>)</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">s</span><span>;</span><span>)</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-entity z-name">n</span><span>(</span><span>)</span><span>,</span><span class="z-constant">9e15</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">u</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">f</span><span>[</span><span class="z-variable z-other">s</span><span class="z-keyword">++</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span class="z-keyword">%</span><span class="z-constant">1e14</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">s</span><span>]</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">%=</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">S</span><span>[</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">-</span><span class="z-variable z-other">e</span><span>]</span><span>,</span><span class="z-variable z-other">f</span><span>[</span><span class="z-variable z-other">s</span><span>]</span><span class="z-keyword">=</span><span class="z-entity z-name">d</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">/</span><span class="z-variable z-other">u</span><span>)</span><span class="z-keyword">*</span><span class="z-variable z-other">u</span><span>)</span><span>;</span><span class="z-constant">0</span><span class="z-keyword">===</span><span class="z-variable z-other">f</span><span>[</span><span class="z-variable z-other">s</span><span>]</span><span>;</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">pop</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">--</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">s</span><span>)</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-keyword">else</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>;</span><span class="z-constant">0</span><span class="z-keyword">===</span><span class="z-variable z-other">f</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">shift</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">-=</span><span class="z-variable z-other z-constant">O</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;=</span><span class="z-constant">10</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">s</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">-=</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">-</span><span class="z-variable z-other">s</span><span>)</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> l</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">l</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">l</span><span>}</span><span>}</span><span>(</span><span>)</span><span>,</span><span class="z-entity z-name">C</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> e</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span class="z-keyword">%</span><span class="z-variable z-other z-constant">R</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">R</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span>)</span><span>;</span><span class="z-variable z-other">f</span><span class="z-keyword">--</span><span>;</span><span>)</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">f</span><span>]</span><span class="z-keyword">%</span><span class="z-variable z-other z-constant">R</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">f</span><span>]</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">R</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span class="z-keyword">*</span><span class="z-variable z-other">o</span><span class="z-keyword">+</span><span class="z-variable z-other">u</span><span class="z-keyword">*</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span class="z-keyword">*</span><span class="z-variable z-other">o</span><span class="z-keyword">+</span><span class="z-variable z-other">r</span><span class="z-keyword">%</span><span class="z-variable z-other z-constant">R</span><span class="z-keyword">*</span><span class="z-variable z-other z-constant">R</span><span class="z-keyword">+</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">/</span><span class="z-variable z-other">t</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">R</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">+</span><span class="z-variable z-other">c</span><span class="z-keyword">*</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">f</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span class="z-keyword">%</span><span class="z-variable z-other">t</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> s</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">unshift</span><span>(</span><span class="z-variable z-other">s</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> n</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>,</span><span class="z-variable">r</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> i</span><span>,</span><span class="z-variable z-other">o</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">!=</span><span class="z-variable z-other">r</span><span>)</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">r</span><span class="z-keyword">?</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>;</span><span class="z-keyword">else</span><span class="z-keyword"> for</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">i</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">++</span><span>)</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span class="z-keyword">!=</span><span class="z-variable z-other">n</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>)</span><span>{</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span class="z-keyword">?</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>;</span><span class="z-keyword">break</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> o</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> r</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>,</span><span class="z-variable">r</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> i</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">--</span><span>;</span><span>)</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">t</span><span>]</span><span class="z-keyword">-=</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">t</span><span>]</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">n</span><span>[</span><span class="z-variable z-other">t</span><span>]</span><span class="z-keyword">?</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">t</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span class="z-keyword">*</span><span class="z-variable z-other">r</span><span class="z-keyword">+</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">t</span><span>]</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span>[</span><span class="z-variable z-other">t</span><span>]</span><span>;</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">e</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">&gt;</span><span class="z-constant">1</span><span>;</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">shift</span><span>(</span><span>)</span><span>)</span><span>;</span><span>}</span><span class="z-keyword">return</span><span class="z-storage z-type"> function</span><span>(</span><span class="z-variable">i</span><span>,</span><span class="z-variable">o</span><span>,</span><span class="z-variable">u</span><span>,</span><span class="z-variable">s</span><span>,</span><span class="z-variable">f</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> l</span><span>,</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">h</span><span>,</span><span class="z-variable z-other">g</span><span>,</span><span class="z-variable z-other">p</span><span>,</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">w</span><span>,</span><span class="z-variable z-other">v</span><span>,</span><span class="z-variable z-other z-constant">N</span><span>,</span><span class="z-variable z-other">y</span><span>,</span><span class="z-variable z-other z-constant">S</span><span>,</span><span class="z-variable z-other z-constant">R</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-variable z-other z-constant">D</span><span>,</span><span class="z-variable z-other z-constant">F</span><span>,</span><span class="z-variable z-other">_</span><span>,</span><span class="z-variable z-other">x</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">==</span><span class="z-variable z-other">o</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">?</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other z-constant">I</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other z-constant">L</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>.</span><span class="z-variable z-other">c</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span>(</span><span class="z-variable z-other z-constant">I</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other z-constant">I</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other z-constant">L</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other z-constant">L</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span>)</span><span class="z-keyword">return</span><span class="z-keyword"> new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">o</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">I</span><span class="z-keyword">?</span><span class="z-keyword">!</span><span class="z-variable z-other z-constant">L</span><span class="z-keyword">||</span><span class="z-variable z-other z-constant">I</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">!=</span><span class="z-variable z-other z-constant">L</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">:</span><span class="z-variable z-other z-constant">L</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other z-constant">I</span><span class="z-keyword">&amp;&amp;</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-other z-constant">I</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other z-constant">L</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">*</span><span class="z-variable z-other">x</span><span class="z-keyword">:</span><span class="z-variable z-other">x</span><span class="z-keyword">/</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">NaN</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">w</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">x</span><span>)</span><span>,</span><span class="z-variable z-other">v</span><span class="z-keyword">=</span><span class="z-variable z-other">w</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>[</span><span>]</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">-</span><span class="z-variable z-other">o</span><span>.</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">x</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span class="z-keyword">+</span><span class="z-variable z-other">c</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">||</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">b</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>)</span><span class="z-keyword">-</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-other">o</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>)</span><span>,</span><span class="z-variable z-other">x</span><span class="z-keyword">=</span><span class="z-variable z-other">x</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other z-constant">L</span><span>[</span><span class="z-variable z-other">a</span><span>]</span><span class="z-keyword">==</span><span>(</span><span class="z-variable z-other z-constant">I</span><span>[</span><span class="z-variable z-other">a</span><span>]</span><span class="z-keyword">||</span><span class="z-constant">0</span><span>)</span><span>;</span><span class="z-variable z-other">a</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other z-constant">L</span><span>[</span><span class="z-variable z-other">a</span><span>]</span><span class="z-keyword">&gt;</span><span>(</span><span class="z-variable z-other z-constant">I</span><span>[</span><span class="z-variable z-other">a</span><span>]</span><span class="z-keyword">||</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">c</span><span class="z-keyword">--</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">x</span><span>)</span><span class="z-variable z-other">v</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span class="z-constant">0</span><span>;</span><span class="z-keyword">else</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other z-constant">A</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">I</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other z-constant">F</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">L</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">x</span><span class="z-keyword">+=</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">g</span><span class="z-keyword">=</span><span class="z-entity z-name">d</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">/</span><span>(</span><span class="z-variable z-other z-constant">L</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">g</span><span class="z-keyword">&gt;</span><span class="z-constant">1</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">L</span><span class="z-keyword">=</span><span class="z-entity z-name">e</span><span>(</span><span class="z-variable z-other z-constant">L</span><span>,</span><span class="z-variable z-other">g</span><span>,</span><span class="z-variable z-other">f</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">I</span><span class="z-keyword">=</span><span class="z-entity z-name">e</span><span>(</span><span class="z-variable z-other z-constant">I</span><span>,</span><span class="z-variable z-other">g</span><span>,</span><span class="z-variable z-other">f</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">F</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">L</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other z-constant">A</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">I</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">R</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">F</span><span>,</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">I</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">F</span><span>)</span><span>,</span><span class="z-variable z-other">y</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">N</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other z-constant">F</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">y</span><span>;</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-variable z-other">y</span><span class="z-keyword">++</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>)</span><span>;</span><span class="z-variable z-other">_</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">L</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">_</span><span>.</span><span class="z-entity z-name">unshift</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">D</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">L</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other z-constant">L</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">f</span><span class="z-keyword">/</span><span class="z-constant">2</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other z-constant">D</span><span class="z-keyword">++</span><span>;</span><span class="z-keyword">do</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">g</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-entity z-name">n</span><span>(</span><span class="z-variable z-other z-constant">L</span><span>,</span><span class="z-variable z-other z-constant">N</span><span>,</span><span class="z-variable z-other z-constant">F</span><span>,</span><span class="z-variable z-other">y</span><span>)</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">l</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other z-constant">S</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other z-constant">F</span><span class="z-keyword">!=</span><span class="z-variable z-other">y</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">S</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">S</span><span class="z-keyword">*</span><span class="z-variable z-other">f</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">||</span><span class="z-constant">0</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">g</span><span class="z-keyword">=</span><span class="z-entity z-name">d</span><span>(</span><span class="z-variable z-other z-constant">S</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">D</span><span>)</span><span>,</span><span class="z-variable z-other">g</span><span class="z-keyword">&gt;</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">g</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">f</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">g</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other">p</span><span class="z-keyword">=</span><span class="z-entity z-name">e</span><span>(</span><span class="z-variable z-other z-constant">L</span><span>,</span><span class="z-variable z-other">g</span><span>,</span><span class="z-variable z-other">f</span><span>)</span><span>,</span><span class="z-variable z-other">m</span><span class="z-keyword">=</span><span class="z-variable z-other">p</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other">y</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">N</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-constant">1</span><span class="z-keyword">==</span><span class="z-entity z-name">n</span><span>(</span><span class="z-variable z-other">p</span><span>,</span><span class="z-variable z-other z-constant">N</span><span>,</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">y</span><span>)</span><span>;</span><span>)</span><span class="z-variable z-other">g</span><span class="z-keyword">--</span><span>,</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">p</span><span>,</span><span class="z-variable z-other">m</span><span class="z-keyword">&gt;</span><span class="z-variable z-other z-constant">F</span><span class="z-keyword">?</span><span class="z-variable z-other">_</span><span class="z-keyword">:</span><span class="z-variable z-other z-constant">L</span><span>,</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">f</span><span>)</span><span>,</span><span class="z-variable z-other">m</span><span class="z-keyword">=</span><span class="z-variable z-other">p</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>;</span><span class="z-keyword">else</span><span class="z-constant"> 0</span><span class="z-keyword">==</span><span class="z-variable z-other">g</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">g</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other">p</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">L</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">m</span><span class="z-keyword">=</span><span class="z-variable z-other">p</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">y</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">m</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">p</span><span>.</span><span class="z-entity z-name">unshift</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other z-constant">N</span><span>,</span><span class="z-variable z-other">p</span><span>,</span><span class="z-variable z-other">y</span><span>,</span><span class="z-variable z-other">f</span><span>)</span><span>,</span><span class="z-variable z-other">y</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">N</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-keyword">-</span><span class="z-constant">1</span><span class="z-keyword">==</span><span class="z-variable z-other">l</span><span>)</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-entity z-name">n</span><span>(</span><span class="z-variable z-other z-constant">L</span><span>,</span><span class="z-variable z-other z-constant">N</span><span>,</span><span class="z-variable z-other z-constant">F</span><span>,</span><span class="z-variable z-other">y</span><span>)</span><span class="z-keyword">&lt;</span><span class="z-constant">1</span><span>;</span><span>)</span><span class="z-variable z-other">g</span><span class="z-keyword">++</span><span>,</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other z-constant">N</span><span>,</span><span class="z-variable z-other">y</span><span class="z-keyword">&gt;</span><span class="z-variable z-other z-constant">F</span><span class="z-keyword">?</span><span class="z-variable z-other">_</span><span class="z-keyword">:</span><span class="z-variable z-other z-constant">L</span><span>,</span><span class="z-variable z-other">y</span><span>,</span><span class="z-variable z-other">f</span><span>)</span><span>,</span><span class="z-variable z-other">y</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">N</span><span>.</span><span class="z-support z-variable">length</span><span>}</span><span class="z-keyword">else</span><span class="z-constant"> 0</span><span class="z-keyword">===</span><span class="z-variable z-other">l</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">g</span><span class="z-keyword">++</span><span>,</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span>;</span><span class="z-variable z-other">v</span><span>[</span><span class="z-variable z-other">a</span><span class="z-keyword">++</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">g</span><span>,</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">?</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-variable z-other">y</span><span class="z-keyword">++</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">I</span><span>[</span><span class="z-variable z-other z-constant">R</span><span>]</span><span class="z-keyword">||</span><span class="z-constant">0</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other z-constant">I</span><span>[</span><span class="z-variable z-other z-constant">R</span><span>]</span><span>]</span><span>,</span><span class="z-variable z-other">y</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>)</span><span>}</span><span class="z-keyword">while</span><span>(</span><span>(</span><span class="z-variable z-other z-constant">R</span><span class="z-keyword">++</span><span class="z-keyword">&lt;</span><span class="z-variable z-other z-constant">A</span><span class="z-keyword">||</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">x</span><span class="z-keyword">--</span><span>)</span><span>;</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">v</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">||</span><span class="z-variable z-other">v</span><span>.</span><span class="z-entity z-name">shift</span><span>(</span><span>)</span><span>}</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">==</span><span class="z-variable z-other">b</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">x</span><span class="z-keyword">=</span><span class="z-variable z-other">v</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-variable z-other">x</span><span class="z-keyword">&gt;=</span><span class="z-constant">10</span><span>;</span><span class="z-variable z-other">x</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">++</span><span>)</span><span>;</span><span class="z-entity z-name">U</span><span>(</span><span class="z-variable z-other">w</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">w</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span class="z-keyword">+</span><span class="z-variable z-other">c</span><span class="z-keyword">*</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">h</span><span>)</span><span>}</span><span class="z-keyword">else</span><span class="z-variable z-other"> w</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">w</span><span>.</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-keyword">+</span><span class="z-variable z-other">h</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> w</span><span>}</span><span>}</span><span>(</span><span>)</span><span>,</span><span class="z-entity z-name">h</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> e</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-string z-regexp">(</span><span class="z-string z-regexp">-</span><span class="z-keyword">?</span><span class="z-string z-regexp">)</span><span class="z-string z-regexp">0</span><span class="z-string z-regexp">(</span><span class="z-constant">[</span><span class="z-constant">xbo</span><span class="z-constant">]</span><span class="z-string z-regexp">)</span><span class="z-string z-regexp">(</span><span class="z-string z-regexp">?=</span><span class="z-constant">\w</span><span class="z-constant">[</span><span class="z-constant">\w</span><span class="z-constant">.</span><span class="z-constant">]</span><span class="z-keyword">*</span><span class="z-keyword">$</span><span class="z-string z-regexp">)</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">i</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-string z-regexp">(</span><span class="z-constant">[</span><span class="z-keyword">^</span><span class="z-constant">.</span><span class="z-constant">]</span><span class="z-keyword">+</span><span class="z-string z-regexp">)</span><span class="z-constant z-character z-escape">\.</span><span class="z-keyword">$</span><span class="z-punctuation z-definition z-string">/</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-constant z-character z-escape">\.</span><span class="z-string z-regexp">(</span><span class="z-constant">[</span><span class="z-keyword">^</span><span class="z-constant">.</span><span class="z-constant">]</span><span class="z-keyword">+</span><span class="z-string z-regexp">)</span><span class="z-keyword">$</span><span class="z-punctuation z-definition z-string">/</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-string z-regexp">-</span><span class="z-keyword">?</span><span class="z-string z-regexp">(</span><span class="z-string z-regexp">Infinity</span><span class="z-keyword">|</span><span class="z-string z-regexp">NaN</span><span class="z-string z-regexp">)</span><span class="z-keyword">$</span><span class="z-punctuation z-definition z-string">/</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-constant">\s</span><span class="z-keyword">*</span><span class="z-constant z-character z-escape">\+</span><span class="z-string z-regexp">(</span><span class="z-string z-regexp">?=</span><span class="z-constant">[</span><span class="z-constant">\w</span><span class="z-constant">.</span><span class="z-constant">]</span><span class="z-string z-regexp">)</span><span class="z-keyword">|</span><span class="z-keyword">^</span><span class="z-constant">\s</span><span class="z-keyword">+</span><span class="z-keyword">|</span><span class="z-constant">\s</span><span class="z-keyword">+</span><span class="z-keyword">$</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">g</span><span>;</span><span class="z-keyword">return</span><span class="z-storage z-type"> function</span><span>(</span><span class="z-variable">o</span><span>,</span><span class="z-variable">u</span><span>,</span><span class="z-variable">s</span><span>,</span><span class="z-variable">f</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> l</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span class="z-keyword">?</span><span class="z-variable z-other">u</span><span class="z-keyword">:</span><span class="z-variable z-other">u</span><span>.</span><span class="z-entity z-name">replace</span><span>(</span><span class="z-variable z-other">i</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">r</span><span>.</span><span class="z-entity z-name">test</span><span>(</span><span class="z-variable z-other">c</span><span>)</span><span>)</span><span class="z-variable z-other">o</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-entity z-name">isNaN</span><span>(</span><span class="z-variable z-other">c</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">null</span><span class="z-keyword">:</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">c</span><span class="z-keyword">?</span><span class="z-keyword">-</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-constant">1</span><span>;</span><span class="z-keyword">else</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">s</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span>.</span><span class="z-entity z-name">replace</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other"> l</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">x</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">==</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-entity z-name">toLowerCase</span><span>(</span><span>)</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">16</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">b</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">==</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-constant">2</span><span class="z-keyword">:</span><span class="z-constant">8</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">f</span><span class="z-keyword">!=</span><span class="z-variable z-other">l</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-variable z-other">n</span><span>}</span><span>)</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span>.</span><span class="z-entity z-name">replace</span><span>(</span><span class="z-variable z-other">n</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">$1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>.</span><span class="z-entity z-name">replace</span><span>(</span><span class="z-variable z-other">t</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0.$1</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">!=</span><span class="z-variable z-other">c</span><span>)</span><span>)</span><span class="z-keyword">return</span><span class="z-keyword"> new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">l</span><span>)</span><span>;</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-variable z-other z-constant">M</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">not a</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">?</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> base </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">f</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> number</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">u</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">null</span><span>}</span><span class="z-variable z-other">o</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">null</span><span>,</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>}</span><span>}</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">absoluteValue</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">abs</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> e</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">ceil</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> U</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-constant">2</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">comparedTo</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">cmp</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> M</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-entity z-name">i</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">decimalPlaces</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">dp</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> e</span><span>,</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">c</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">r</span><span>)</span><span class="z-keyword">return</span><span class="z-constant"> null</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span>(</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">-</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>)</span><span>)</span><span class="z-keyword">*</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span>)</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">%</span><span class="z-constant">10</span><span class="z-keyword">==</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">--</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-constant"> 0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">dividedBy</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">div</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> M</span><span class="z-keyword">=</span><span class="z-constant">3</span><span>,</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">P</span><span>,</span><span class="z-variable z-other">k</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">dividedToIntegerBy</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">divToInt</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> M</span><span class="z-keyword">=</span><span class="z-constant">4</span><span>,</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">1</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">equals</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">eq</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> M</span><span class="z-keyword">=</span><span class="z-constant">5</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">===</span><span class="z-entity z-name">i</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">floor</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> U</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-constant">3</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">greaterThan</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">gt</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> M</span><span class="z-keyword">=</span><span class="z-constant">6</span><span>,</span><span class="z-entity z-name">i</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">greaterThanOrEqualTo</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">gte</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> M</span><span class="z-keyword">=</span><span class="z-constant">7</span><span>,</span><span class="z-constant">1</span><span class="z-keyword">===</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-entity z-name">i</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>)</span><span class="z-keyword">||</span><span class="z-constant">0</span><span class="z-keyword">===</span><span class="z-variable z-other">n</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">isFinite</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-keyword">!</span><span class="z-keyword">!</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">c</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">isInteger</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">isInt</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-keyword">!</span><span class="z-keyword">!</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>)</span><span class="z-keyword">&gt;</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">c</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">-</span><span class="z-constant">2</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">isNaN</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-keyword">!</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">s</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">isNegative</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">isNeg</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-language"> this</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">isZero</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-keyword">!</span><span class="z-keyword">!</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">c</span><span>[</span><span class="z-constant">0</span><span>]</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">lessThan</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">lt</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> M</span><span class="z-keyword">=</span><span class="z-constant">8</span><span>,</span><span class="z-entity z-name">i</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">lessThanOrEqualTo</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">lte</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> M</span><span class="z-keyword">=</span><span class="z-constant">9</span><span>,</span><span class="z-keyword">-</span><span class="z-constant">1</span><span class="z-keyword">===</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-entity z-name">i</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>)</span><span class="z-keyword">||</span><span class="z-constant">0</span><span class="z-keyword">===</span><span class="z-variable z-other">n</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">minus</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">sub</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-variable z-other">s</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">f</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">return</span><span class="z-keyword"> new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-constant">NaN</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">!=</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">plus</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>;</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> l</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">l</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">c</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">a</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">h</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> a</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">:</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">h</span><span class="z-keyword">?</span><span class="z-variable z-other">s</span><span class="z-keyword">:</span><span class="z-constant">NaN</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">h</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> h</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">:</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">?</span><span class="z-variable z-other">s</span><span class="z-keyword">:</span><span class="z-constant">3</span><span class="z-keyword">==</span><span class="z-variable z-other">k</span><span class="z-keyword">?</span><span class="z-keyword">-</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">0</span><span>)</span><span>}</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-other">l</span><span>)</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-other">c</span><span>)</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span class="z-keyword">-</span><span class="z-variable z-other">c</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">f</span><span>)</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>)</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span>.</span><span class="z-entity z-name">reverse</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">--</span><span>;</span><span class="z-variable z-other">o</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span>;</span><span class="z-variable z-other">o</span><span>.</span><span class="z-entity z-name">reverse</span><span>(</span><span>)</span><span>}</span><span class="z-keyword">else</span><span class="z-keyword"> for</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span class="z-keyword">&lt;</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">f</span><span class="z-keyword">:</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">++</span><span>)</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">!=</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span>)</span><span>{</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span>;</span><span class="z-keyword">break</span><span>}</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span class="z-keyword">-</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">--</span><span>;</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">r</span><span class="z-keyword">++</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">b</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">f</span><span>;</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">a</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">i</span><span>]</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>;</span><span class="z-variable z-other">r</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other">a</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">r</span><span>]</span><span>;</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">r</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>)</span><span>;</span><span class="z-keyword">--</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">r</span><span>]</span><span>,</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span class="z-keyword">+=</span><span class="z-variable z-other">b</span><span>}</span><span class="z-variable z-other">a</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span class="z-keyword">-=</span><span class="z-variable z-other">h</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span>}</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-other">a</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">shift</span><span>(</span><span>)</span><span>,</span><span class="z-keyword">--</span><span class="z-variable z-other">c</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> a</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">?</span><span class="z-entity z-name">I</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">c</span><span>)</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">3</span><span class="z-keyword">==</span><span class="z-variable z-other">k</span><span class="z-keyword">?</span><span class="z-keyword">-</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>[</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">modulo</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">mod</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span>,</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other z-constant"> M</span><span class="z-keyword">=</span><span class="z-constant">11</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">||</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">?</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-constant">NaN</span><span>)</span><span class="z-keyword">:</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">||</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">c</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">?</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">i</span><span>)</span><span class="z-keyword">:</span><span>(</span><span class="z-constant">9</span><span class="z-keyword">==</span><span class="z-variable z-other z-constant">W</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">3</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">*=</span><span class="z-variable z-other">r</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">W</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span>.</span><span class="z-entity z-name">minus</span><span>(</span><span class="z-variable z-other">t</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">negated</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">neg</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> e</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">||</span><span class="z-constant">null</span><span>,</span><span class="z-variable z-other">e</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">plus</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">add</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">s</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">12</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">o</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">return</span><span class="z-keyword"> new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-constant">NaN</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">!=</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">i</span><span>.</span><span class="z-entity z-name">minus</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>;</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> u</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">u</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">s</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">f</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">l</span><span>)</span><span class="z-keyword">return</span><span class="z-keyword"> new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">/</span><span class="z-constant">0</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">f</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">l</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> l</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">f</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">?</span><span class="z-variable z-other">i</span><span class="z-keyword">:</span><span class="z-constant">0</span><span class="z-keyword">*</span><span class="z-variable z-other">o</span><span>)</span><span>}</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-other">u</span><span>)</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-other">s</span><span>)</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span class="z-keyword">-</span><span class="z-variable z-other">s</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>)</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-keyword">-</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span>.</span><span class="z-entity z-name">reverse</span><span>(</span><span>)</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">--</span><span>;</span><span class="z-variable z-other">r</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span>;</span><span class="z-variable z-other">r</span><span>.</span><span class="z-entity z-name">reverse</span><span>(</span><span>)</span><span>}</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">o</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">n</span><span>;</span><span>)</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">f</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">+</span><span class="z-variable z-other">l</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">+</span><span class="z-variable z-other">o</span><span>)</span><span class="z-keyword">/</span><span class="z-variable z-other">b</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">f</span><span>[</span><span class="z-variable z-other">n</span><span>]</span><span class="z-keyword">%=</span><span class="z-variable z-other">b</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> o</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">unshift</span><span>(</span><span class="z-variable z-other">o</span><span>)</span><span>,</span><span class="z-keyword">++</span><span class="z-variable z-other">s</span><span>)</span><span>,</span><span class="z-entity z-name">I</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">s</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">precision</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">sd</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> n</span><span>,</span><span class="z-variable z-other">t</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>.</span><span class="z-variable z-other">c</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">e</span><span class="z-keyword">!==</span><span class="z-keyword">!</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-constant">1</span><span class="z-keyword">!==</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-constant">0</span><span class="z-keyword">!==</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-constant">13</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">argument</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">!=</span><span class="z-keyword">!</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">null</span><span>)</span><span>)</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">i</span><span>)</span><span class="z-keyword">return</span><span class="z-constant"> null</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span class="z-keyword">*</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>[</span><span class="z-variable z-other">t</span><span>]</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">%</span><span class="z-constant">10</span><span class="z-keyword">==</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">--</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">&gt;=</span><span class="z-constant">10</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">/=</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">++</span><span>)</span><span>;</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">r</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">round</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>;</span><span class="z-keyword">return</span><span>(</span><span class="z-constant">null</span><span class="z-keyword">==</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">15</span><span>)</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">U</span><span>(</span><span class="z-variable z-other">t</span><span>,</span><span class="z-keyword">~</span><span class="z-keyword">~</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">n</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">8</span><span>,</span><span class="z-constant">15</span><span>,</span><span class="z-variable z-other">w</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">n</span><span class="z-keyword">:</span><span class="z-variable z-other">k</span><span>)</span><span>,</span><span class="z-variable z-other">t</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">shift</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> n</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>;</span><span class="z-keyword">return</span><span class="z-entity z-name"> H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-keyword">-</span><span class="z-variable z-other">y</span><span>,</span><span class="z-variable z-other">y</span><span>,</span><span class="z-constant">16</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">argument</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1e</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-entity z-name">c</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span class="z-keyword">:</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">n</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">n</span><span>.</span><span class="z-variable z-other">c</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-keyword">-</span><span class="z-variable z-other">y</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-variable z-other">e</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">y</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">n</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">*</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-constant">1</span><span class="z-keyword">/</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">n</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">squareRoot</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">sqrt</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> e</span><span>,</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">P</span><span class="z-keyword">+</span><span class="z-constant">4</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0.5</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">1</span><span class="z-keyword">!==</span><span class="z-variable z-other">l</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">f</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">f</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-keyword">return</span><span class="z-keyword"> new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">l</span><span class="z-keyword">||</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">l</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">f</span><span class="z-keyword">||</span><span class="z-variable z-other">f</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">NaN</span><span class="z-keyword">:</span><span class="z-variable z-other">f</span><span class="z-keyword">?</span><span class="z-variable z-other">s</span><span class="z-keyword">:</span><span class="z-constant">1</span><span class="z-keyword">/</span><span class="z-constant">0</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">sqrt</span><span>(</span><span class="z-keyword">+</span><span class="z-variable z-other">s</span><span>)</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-other">l</span><span class="z-keyword">||</span><span class="z-variable z-other">l</span><span class="z-keyword">==</span><span class="z-constant">1</span><span class="z-keyword">/</span><span class="z-constant">0</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">f</span><span>)</span><span>,</span><span>(</span><span class="z-variable z-other">n</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">+</span><span class="z-variable z-other">c</span><span>)</span><span class="z-keyword">%</span><span class="z-constant">2</span><span class="z-keyword">==</span><span class="z-constant">0</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">+=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">sqrt</span><span>(</span><span class="z-variable z-other">n</span><span>)</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-entity z-name">t</span><span>(</span><span>(</span><span class="z-variable z-other">c</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">/</span><span class="z-constant">2</span><span>)</span><span class="z-keyword">-</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">c</span><span class="z-keyword">||</span><span class="z-variable z-other">c</span><span class="z-keyword">%</span><span class="z-constant">2</span><span>)</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">==</span><span class="z-constant">1</span><span class="z-keyword">/</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1e</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">c</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>.</span><span class="z-entity z-name">toExponential</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">indexOf</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">e</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">+</span><span class="z-variable z-other">c</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">l</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">c</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span class="z-keyword">+</span><span class="z-variable z-other">a</span><span>,</span><span class="z-constant">3</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">l</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>)</span><span>;</span><span>;</span><span>)</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">u</span><span>.</span><span class="z-entity z-name">plus</span><span>(</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">a</span><span>,</span><span class="z-constant">1</span><span>)</span><span>)</span><span>)</span><span>,</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">u</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">l</span><span>)</span><span class="z-keyword">===</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span>)</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">l</span><span>)</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">--</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-variable z-other">l</span><span class="z-keyword">-</span><span class="z-constant">3</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">9999</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">!=</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">||</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">4999</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">!=</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>{</span><span>(</span><span class="z-keyword">!</span><span class="z-keyword">+</span><span class="z-variable z-other">n</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-keyword">+</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">5</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">==</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">charAt</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-entity z-name">U</span><span>(</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-variable z-other z-constant">P</span><span class="z-keyword">+</span><span class="z-constant">2</span><span>,</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span class="z-variable z-other">i</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">i</span><span>)</span><span>.</span><span class="z-entity z-name">eq</span><span>(</span><span class="z-variable z-other">s</span><span>)</span><span>)</span><span>;</span><span class="z-keyword">break</span><span>}</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">o</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-entity z-name">U</span><span>(</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">u</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-variable z-other z-constant">P</span><span class="z-keyword">+</span><span class="z-constant">2</span><span>,</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">u</span><span>)</span><span>.</span><span class="z-entity z-name">eq</span><span>(</span><span class="z-variable z-other">s</span><span>)</span><span>)</span><span>)</span><span>{</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span>;</span><span class="z-keyword">break</span><span>}</span><span class="z-variable z-other">a</span><span class="z-keyword">+=</span><span class="z-constant">4</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">+=</span><span class="z-constant">4</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>}</span><span class="z-keyword">return</span><span class="z-entity z-name"> U</span><span>(</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">i</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-variable z-other z-constant">P</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">k</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">times</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">mul</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">h</span><span>,</span><span class="z-variable z-other">g</span><span>,</span><span class="z-variable z-other">p</span><span>,</span><span class="z-variable z-other">d</span><span>,</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">w</span><span>,</span><span class="z-variable z-other">v</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">=</span><span class="z-variable z-other">v</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">y</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">17</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>.</span><span class="z-variable z-other">c</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span>(</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">y</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">y</span><span>[</span><span class="z-constant">0</span><span>]</span><span>)</span><span>)</span><span class="z-keyword">return</span><span class="z-keyword">!</span><span class="z-variable z-other">v</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">||</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other">y</span><span class="z-keyword">||</span><span class="z-variable z-other">y</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other">y</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-constant">null</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">*=</span><span class="z-variable z-other">v</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">y</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">null</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-other">v</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>)</span><span class="z-keyword">+</span><span class="z-entity z-name">t</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">*=</span><span class="z-variable z-other">v</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">N</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-variable z-other">y</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">l</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">d</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">N</span><span>,</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">=</span><span class="z-variable z-other">y</span><span>,</span><span class="z-variable z-other">y</span><span class="z-keyword">=</span><span class="z-variable z-other">d</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span class="z-keyword">+</span><span class="z-variable z-other">h</span><span>,</span><span class="z-variable z-other">d</span><span class="z-keyword">=</span><span>[</span><span>]</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">--</span><span>;</span><span class="z-variable z-other">d</span><span>.</span><span class="z-entity z-name">push</span><span>(</span><span class="z-constant">0</span><span>)</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">m</span><span class="z-keyword">=</span><span class="z-variable z-other">b</span><span>,</span><span class="z-variable z-other">w</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">R</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>;</span><span class="z-keyword">--</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;=</span><span class="z-constant">0</span><span>;</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">g</span><span class="z-keyword">=</span><span class="z-variable z-other">y</span><span>[</span><span class="z-variable z-other">o</span><span>]</span><span class="z-keyword">%</span><span class="z-variable z-other">w</span><span>,</span><span class="z-variable z-other">p</span><span class="z-keyword">=</span><span class="z-variable z-other">y</span><span>[</span><span class="z-variable z-other">o</span><span>]</span><span class="z-keyword">/</span><span class="z-variable z-other">w</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span class="z-keyword">+</span><span class="z-variable z-other">s</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">o</span><span>;</span><span>)</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-keyword">--</span><span class="z-variable z-other">s</span><span>]</span><span class="z-keyword">%</span><span class="z-variable z-other">w</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">N</span><span>[</span><span class="z-variable z-other">s</span><span>]</span><span class="z-keyword">/</span><span class="z-variable z-other">w</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">p</span><span class="z-keyword">*</span><span class="z-variable z-other">c</span><span class="z-keyword">+</span><span class="z-variable z-other">a</span><span class="z-keyword">*</span><span class="z-variable z-other">g</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-other">g</span><span class="z-keyword">*</span><span class="z-variable z-other">c</span><span class="z-keyword">+</span><span class="z-variable z-other">f</span><span class="z-keyword">%</span><span class="z-variable z-other">w</span><span class="z-keyword">*</span><span class="z-variable z-other">w</span><span class="z-keyword">+</span><span class="z-variable z-other">d</span><span>[</span><span class="z-variable z-other">u</span><span>]</span><span class="z-keyword">+</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">c</span><span class="z-keyword">/</span><span class="z-variable z-other">m</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">/</span><span class="z-variable z-other">w</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">+</span><span class="z-variable z-other">p</span><span class="z-keyword">*</span><span class="z-variable z-other">a</span><span>,</span><span class="z-variable z-other">d</span><span>[</span><span class="z-variable z-other">u</span><span class="z-keyword">--</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span class="z-keyword">%</span><span class="z-variable z-other">m</span><span>;</span><span class="z-variable z-other">d</span><span>[</span><span class="z-variable z-other">u</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> r</span><span class="z-keyword">?</span><span class="z-keyword">++</span><span class="z-variable z-other">i</span><span class="z-keyword">:</span><span class="z-variable z-other">d</span><span>.</span><span class="z-entity z-name">shift</span><span>(</span><span>)</span><span>,</span><span class="z-entity z-name">I</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">d</span><span>,</span><span class="z-variable z-other">i</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">toDigits</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span class="z-keyword">=</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">18</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">precision</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-constant">null</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">n</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">8</span><span>,</span><span class="z-constant">18</span><span>,</span><span class="z-variable z-other">w</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">n</span><span class="z-keyword">:</span><span class="z-variable z-other">k</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span class="z-entity z-name">U</span><span>(</span><span class="z-variable z-other">t</span><span>,</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">t</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">toExponential</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> F</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">19</span><span>)</span><span class="z-keyword">?</span><span class="z-keyword">~</span><span class="z-keyword">~</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-constant">null</span><span>,</span><span class="z-variable z-other">n</span><span>,</span><span class="z-constant">19</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">toFixed</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> F</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">20</span><span>)</span><span class="z-keyword">?</span><span class="z-keyword">~</span><span class="z-keyword">~</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-constant">null</span><span>,</span><span class="z-variable z-other">n</span><span>,</span><span class="z-constant">20</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">toFormat</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span class="z-keyword">=</span><span class="z-entity z-name">F</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">21</span><span>)</span><span class="z-keyword">?</span><span class="z-keyword">~</span><span class="z-keyword">~</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-constant">null</span><span>,</span><span class="z-variable z-other">n</span><span>,</span><span class="z-constant">21</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-entity z-name">split</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-keyword">+</span><span class="z-variable z-other z-constant">X</span><span>.</span><span class="z-variable z-other">groupSize</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-keyword">+</span><span class="z-variable z-other z-constant">X</span><span>.</span><span class="z-variable z-other">secondaryGroupSize</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">X</span><span>.</span><span class="z-variable z-other">groupSeparator</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>[</span><span class="z-constant">1</span><span>]</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span class="z-keyword">?</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">-=</span><span class="z-variable z-other">r</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">h</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span class="z-keyword">%</span><span class="z-variable z-other">o</span><span class="z-keyword">||</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">substr</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">r</span><span>)</span><span>;</span><span class="z-variable z-other">h</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">r</span><span>;</span><span class="z-variable z-other">r</span><span class="z-keyword">+=</span><span class="z-variable z-other">o</span><span>)</span><span class="z-variable z-other">f</span><span class="z-keyword">+=</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">substr</span><span>(</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">o</span><span>)</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">+=</span><span class="z-variable z-other">s</span><span class="z-keyword">+</span><span class="z-variable z-other">a</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-variable z-other">r</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">-</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">f</span><span>)</span><span>}</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">l</span><span class="z-keyword">?</span><span class="z-variable z-other">f</span><span class="z-keyword">+</span><span class="z-variable z-other z-constant">X</span><span>.</span><span class="z-variable z-other">decimalSeparator</span><span class="z-keyword">+</span><span>(</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-keyword">+</span><span class="z-variable z-other z-constant">X</span><span>.</span><span class="z-variable z-other">fractionGroupSize</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">l</span><span>.</span><span class="z-entity z-name">replace</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> RegExp</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-constant">\\</span><span class="z-string">d{</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">u</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">}</span><span class="z-constant">\\</span><span class="z-string">B</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">g</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">$&amp;</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other z-constant">X</span><span>.</span><span class="z-variable z-other">fractionGroupSeparator</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">l</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">f</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> t</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">toFraction</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> n</span><span>,</span><span class="z-variable z-other">t</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">j</span><span>,</span><span class="z-variable z-other">h</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">g</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">p</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">q</span><span>)</span><span>,</span><span class="z-variable z-other">d</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">q</span><span>)</span><span>,</span><span class="z-variable z-other">m</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">q</span><span>)</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">j</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">j</span><span class="z-keyword">=</span><span class="z-variable z-other">a</span><span>,</span><span>(</span><span class="z-keyword">!</span><span>(</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">isInt</span><span>(</span><span>)</span><span>)</span><span class="z-keyword">||</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">lt</span><span>(</span><span class="z-variable z-other">q</span><span>)</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">j</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">L</span><span>(</span><span class="z-constant">22</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">max denominator </span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span>(</span><span class="z-variable z-other">a</span><span class="z-keyword">?</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">out of range</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">not an integer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span class="z-variable z-other">a</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">s</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">U</span><span>(</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">s</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-constant">1</span><span>)</span><span>.</span><span class="z-entity z-name">gte</span><span>(</span><span class="z-variable z-other">q</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">s</span><span class="z-keyword">:</span><span class="z-constant">null</span><span>)</span><span>)</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">g</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> h</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">c</span><span class="z-keyword">=</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">g</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">p</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">c</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">-</span><span class="z-variable z-other">h</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">p</span><span>.</span><span class="z-variable z-other">c</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">S</span><span>[</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span class="z-keyword">%</span><span class="z-variable z-other z-constant">O</span><span>)</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">+</span><span class="z-variable z-other">u</span><span class="z-keyword">:</span><span class="z-variable z-other">u</span><span>]</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-keyword">!</span><span class="z-variable z-other">e</span><span class="z-keyword">||</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">cmp</span><span>(</span><span class="z-variable z-other">p</span><span>)</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-variable z-other">p</span><span class="z-keyword">:</span><span class="z-variable z-other">d</span><span class="z-keyword">:</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">z</span><span>,</span><span class="z-variable z-other">z</span><span class="z-keyword">=</span><span class="z-constant">1</span><span class="z-keyword">/</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">c</span><span>)</span><span>,</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">c</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">p</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-entity z-name">plus</span><span>(</span><span class="z-variable z-other">l</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">m</span><span>)</span><span>)</span><span>,</span><span class="z-constant">1</span><span class="z-keyword">!=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-entity z-name">cmp</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>;</span><span>)</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">m</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">d</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">plus</span><span>(</span><span class="z-variable z-other">l</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">d</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">p</span><span class="z-keyword">=</span><span class="z-variable z-other">s</span><span>.</span><span class="z-entity z-name">minus</span><span>(</span><span class="z-variable z-other">l</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">p</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> i</span><span class="z-keyword">=</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">minus</span><span>(</span><span class="z-variable z-other">t</span><span>)</span><span>,</span><span class="z-variable z-other">m</span><span>,</span><span class="z-constant">0</span><span>,</span><span class="z-constant">1</span><span>)</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">plus</span><span>(</span><span class="z-variable z-other">i</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">d</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-entity z-name">plus</span><span>(</span><span class="z-variable z-other">i</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">m</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">f</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">d</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">h</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">*=</span><span class="z-constant">2</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-other">d</span><span>,</span><span class="z-variable z-other">m</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">k</span><span>)</span><span>.</span><span class="z-entity z-name">minus</span><span>(</span><span class="z-variable z-other">h</span><span>)</span><span>.</span><span class="z-entity z-name">abs</span><span>(</span><span>)</span><span>.</span><span class="z-entity z-name">cmp</span><span>(</span><span class="z-entity z-name">C</span><span>(</span><span class="z-variable z-other">f</span><span>,</span><span class="z-variable z-other">t</span><span>,</span><span class="z-variable z-other">o</span><span>,</span><span class="z-variable z-other">k</span><span>)</span><span>.</span><span class="z-entity z-name">minus</span><span>(</span><span class="z-variable z-other">h</span><span>)</span><span>.</span><span class="z-entity z-name">abs</span><span>(</span><span>)</span><span>)</span><span class="z-keyword">&lt;</span><span class="z-constant">1</span><span class="z-keyword">?</span><span>[</span><span class="z-variable z-other">d</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">m</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>)</span><span>]</span><span class="z-keyword">:</span><span>[</span><span class="z-variable z-other">f</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>)</span><span>,</span><span class="z-variable z-other">t</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>)</span><span>]</span><span>,</span><span class="z-variable z-other">z</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">n</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">toNumber</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-keyword">+</span><span class="z-variable z-language">this</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">toPower</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">pow</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span>,</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-entity z-name">d</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span class="z-keyword">-</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-keyword">+</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other z-constant">M</span><span class="z-keyword">=</span><span class="z-constant">23</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>,</span><span class="z-keyword">!</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-keyword">-</span><span class="z-variable z-other">y</span><span>,</span><span class="z-variable z-other">y</span><span>,</span><span class="z-constant">23</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">exponent</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-keyword">!</span><span class="z-entity z-name">isFinite</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">||</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">y</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">/=</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">||</span><span class="z-entity z-name">parseFloat</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-constant">NaN</span><span>)</span><span>)</span><span class="z-keyword">||</span><span class="z-constant">0</span><span class="z-keyword">==</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> t</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-entity z-name">pow</span><span>(</span><span class="z-keyword">+</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">?</span><span class="z-variable z-other">t</span><span class="z-keyword">%</span><span class="z-variable z-other">n</span><span class="z-keyword">:</span><span class="z-variable z-other">t</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span class="z-keyword">&gt;</span><span class="z-constant">1</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">u</span><span>.</span><span class="z-entity z-name">gt</span><span>(</span><span class="z-variable z-other">q</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">u</span><span>.</span><span class="z-entity z-name">isInt</span><span>(</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">gt</span><span>(</span><span class="z-variable z-other">q</span><span>)</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">isInt</span><span>(</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span>.</span><span class="z-entity z-name">mod</span><span>(</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-constant">null</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other z-constant">J</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-entity z-name">p</span><span>(</span><span class="z-variable z-other z-constant">J</span><span class="z-keyword">/</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">+</span><span class="z-constant">2</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-other">q</span><span>)</span><span>;</span><span>;</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">%</span><span class="z-constant">2</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">u</span><span>)</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">r</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span class="z-keyword">break</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-variable z-other">r</span><span>.</span><span class="z-variable z-other">c</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">r</span><span>.</span><span class="z-variable z-other">c</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span>.</span><span class="z-entity z-name">mod</span><span>(</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>}</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-entity z-name">d</span><span>(</span><span class="z-variable z-other">o</span><span class="z-keyword">/</span><span class="z-constant">2</span><span>)</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">o</span><span>)</span><span class="z-keyword">break</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">u</span><span>)</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-variable z-other">u</span><span>.</span><span class="z-variable z-other">c</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">u</span><span>.</span><span class="z-variable z-other">c</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">u</span><span>.</span><span class="z-variable z-other">c</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">u</span><span>.</span><span class="z-entity z-name">mod</span><span>(</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> n</span><span class="z-keyword">?</span><span class="z-variable z-other">r</span><span class="z-keyword">:</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">q</span><span>.</span><span class="z-entity z-name">div</span><span>(</span><span class="z-variable z-other">r</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">?</span><span class="z-variable z-other">r</span><span>.</span><span class="z-entity z-name">mod</span><span>(</span><span class="z-variable z-other">i</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-entity z-name">U</span><span>(</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other z-constant">J</span><span>,</span><span class="z-variable z-other">k</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">r</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">toPrecision</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> F</span><span>(</span><span class="z-variable z-language">this</span><span>,</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other z-constant">A</span><span>,</span><span class="z-constant">24</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">precision</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-constant">null</span><span>,</span><span class="z-variable z-other">n</span><span>,</span><span class="z-constant">24</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">toString</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> n</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">e</span><span>;</span><span class="z-keyword">return</span><span class="z-constant"> null</span><span class="z-keyword">===</span><span class="z-variable z-other">o</span><span class="z-keyword">?</span><span class="z-variable z-other">i</span><span class="z-keyword">?</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Infinity</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">i</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">-</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">NaN</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-entity z-name">H</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">2</span><span>,</span><span class="z-constant">64</span><span>,</span><span class="z-constant">25</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">base</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">?</span><span class="z-entity z-name">D</span><span>(</span><span class="z-entity z-name">l</span><span>(</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">o</span><span>)</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>,</span><span class="z-constant">10</span><span>,</span><span class="z-variable z-other">i</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other z-constant">B</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">o</span><span class="z-keyword">||</span><span class="z-variable z-other">o</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">$</span><span class="z-keyword">?</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">o</span><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name">l</span><span>(</span><span class="z-variable z-other">n</span><span>,</span><span class="z-variable z-other">o</span><span>)</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">i</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">t</span><span>.</span><span class="z-variable z-other">c</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">-</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">truncated</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">trunc</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> U</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> E</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>,</span><span class="z-variable z-language">this</span><span>.</span><span class="z-variable z-other">e</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>,</span><span class="z-constant">1</span><span>)</span><span>}</span><span>,</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-variable z-other">valueOf</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">T</span><span>.</span><span class="z-entity z-name">toJSON</span><span class="z-keyword">=</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> e</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-language">this</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>.</span><span class="z-variable z-other">e</span><span>;</span><span class="z-keyword">return</span><span class="z-constant"> null</span><span class="z-keyword">===</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-variable z-other">n</span><span>.</span><span class="z-entity z-name">toString</span><span>(</span><span>)</span><span class="z-keyword">:</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-entity z-name">r</span><span>(</span><span class="z-variable z-other">n</span><span>.</span><span class="z-variable z-other">c</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">B</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">t</span><span class="z-keyword">||</span><span class="z-variable z-other">t</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">$</span><span class="z-keyword">?</span><span class="z-entity z-name">f</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">t</span><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name">l</span><span>(</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">t</span><span>)</span><span>,</span><span class="z-variable z-other">n</span><span>.</span><span class="z-variable z-other">s</span><span class="z-keyword">&lt;</span><span class="z-constant">0</span><span class="z-keyword">?</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">-</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">e</span><span class="z-keyword">:</span><span class="z-variable z-other">e</span><span>)</span><span>}</span><span>,</span><span class="z-constant">null</span><span class="z-keyword">!=</span><span class="z-variable z-other">e</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other z-constant">E</span><span>.</span><span class="z-entity z-name">config</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-variable z-other z-constant">E</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> t</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> n</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">|</span><span class="z-variable z-other">e</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span class="z-keyword">&gt;</span><span class="z-constant">0</span><span class="z-keyword">||</span><span class="z-variable z-other">e</span><span class="z-keyword">===</span><span class="z-variable z-other">n</span><span class="z-keyword">?</span><span class="z-variable z-other">n</span><span class="z-keyword">:</span><span class="z-variable z-other">n</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> r</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> n</span><span>,</span><span class="z-variable z-other">t</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-constant">1</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>[</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">r</span><span>;</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>[</span><span class="z-variable z-other">r</span><span class="z-keyword">++</span><span>]</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">-</span><span class="z-variable z-other">n</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other">t</span><span class="z-keyword">--</span><span>;</span><span class="z-variable z-other">n</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">n</span><span>)</span><span>;</span><span class="z-variable z-other">o</span><span class="z-keyword">+=</span><span class="z-variable z-other">n</span><span>}</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-constant">48</span><span class="z-keyword">===</span><span class="z-variable z-other">o</span><span>.</span><span class="z-entity z-name">charCodeAt</span><span>(</span><span class="z-keyword">--</span><span class="z-variable z-other">i</span><span>)</span><span>;</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> o</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">+</span><span class="z-constant">1</span><span class="z-keyword">||</span><span class="z-constant">1</span><span>)</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> i</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span>,</span><span class="z-variable z-other">r</span><span>,</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>.</span><span class="z-variable z-other">c</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>.</span><span class="z-variable z-other">s</span><span>,</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">e</span><span>,</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">n</span><span>.</span><span class="z-variable z-other">e</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">u</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">s</span><span>)</span><span class="z-keyword">return</span><span class="z-constant"> null</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other">i</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span class="z-keyword">&amp;&amp;</span><span class="z-keyword">!</span><span class="z-variable z-other">o</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">t</span><span class="z-keyword">||</span><span class="z-variable z-other">r</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> t</span><span class="z-keyword">?</span><span class="z-variable z-other">r</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-keyword">-</span><span class="z-variable z-other">s</span><span class="z-keyword">:</span><span class="z-variable z-other">u</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">!=</span><span class="z-variable z-other">s</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> u</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">u</span><span>,</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-variable z-other">f</span><span class="z-keyword">==</span><span class="z-variable z-other">l</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">i</span><span class="z-keyword">||</span><span class="z-keyword">!</span><span class="z-variable z-other">o</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> r</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-keyword">!</span><span class="z-variable z-other">i</span><span class="z-keyword">^</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">r</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> f</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">l</span><span class="z-keyword">^</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span>(</span><span class="z-variable z-other">f</span><span class="z-keyword">=</span><span class="z-variable z-other">i</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span class="z-keyword">&lt;</span><span>(</span><span class="z-variable z-other">l</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>.</span><span class="z-support z-variable">length</span><span>)</span><span class="z-keyword">?</span><span class="z-variable z-other">f</span><span class="z-keyword">:</span><span class="z-variable z-other">l</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">u</span><span>;</span><span class="z-variable z-other">u</span><span class="z-keyword">++</span><span>)</span><span class="z-keyword">if</span><span>(</span><span class="z-variable z-other">i</span><span>[</span><span class="z-variable z-other">u</span><span>]</span><span class="z-keyword">!=</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">u</span><span>]</span><span>)</span><span class="z-keyword">return</span><span class="z-variable z-other"> i</span><span>[</span><span class="z-variable z-other">u</span><span>]</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">u</span><span>]</span><span class="z-keyword">^</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> f</span><span class="z-keyword">==</span><span class="z-variable z-other">l</span><span class="z-keyword">?</span><span class="z-constant">0</span><span class="z-keyword">:</span><span class="z-variable z-other">f</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">l</span><span class="z-keyword">^</span><span class="z-variable z-other">t</span><span class="z-keyword">?</span><span class="z-constant">1</span><span class="z-keyword">:</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> o</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>)</span><span>{</span><span class="z-keyword">return</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-entity z-name">c</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>)</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">t</span><span class="z-keyword">&gt;=</span><span class="z-variable z-other">e</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> u</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">[object Array]</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">==</span><span class="z-support">Object</span><span>.</span><span class="z-support z-variable">prototype</span><span>.</span><span class="z-variable z-other">toString</span><span>.</span><span class="z-entity z-name">call</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> s</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>,</span><span class="z-variable">t</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> r</span><span>,</span><span class="z-variable z-other">i</span><span>,</span><span class="z-variable z-other">o</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">0</span><span>]</span><span>,</span><span class="z-variable z-other">u</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">s</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other">s</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">u</span><span>;</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">i</span><span class="z-keyword">=</span><span class="z-variable z-other">o</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other">i</span><span class="z-keyword">--</span><span>;</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">i</span><span>]</span><span class="z-keyword">*=</span><span class="z-variable z-other">n</span><span>)</span><span>;</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>]</span><span class="z-keyword">+=</span><span class="z-variable z-other z-constant">N</span><span>.</span><span class="z-entity z-name">indexOf</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">charAt</span><span>(</span><span class="z-variable z-other">u</span><span class="z-keyword">++</span><span>)</span><span>)</span><span>;</span><span class="z-variable z-other">r</span><span class="z-keyword">&lt;</span><span class="z-variable z-other">o</span><span>.</span><span class="z-support z-variable">length</span><span>;</span><span class="z-variable z-other">r</span><span class="z-keyword">++</span><span>)</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">r</span><span>]</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span class="z-keyword">-</span><span class="z-constant">1</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-constant">null</span><span class="z-keyword">==</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">r</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">r</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">=</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">r</span><span class="z-keyword">+</span><span class="z-constant">1</span><span>]</span><span class="z-keyword">+=</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">r</span><span>]</span><span class="z-keyword">/</span><span class="z-variable z-other">t</span><span class="z-keyword">|</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">o</span><span>[</span><span class="z-variable z-other">r</span><span>]</span><span class="z-keyword">%=</span><span class="z-variable z-other">t</span><span>)</span><span>}</span><span class="z-keyword">return</span><span class="z-variable z-other"> o</span><span>.</span><span class="z-entity z-name">reverse</span><span>(</span><span>)</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> f</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-keyword">return</span><span>(</span><span class="z-variable z-other">e</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword">&gt;</span><span class="z-constant">1</span><span class="z-keyword">?</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">charAt</span><span>(</span><span class="z-constant">0</span><span>)</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">1</span><span>)</span><span class="z-keyword">:</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">+</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span class="z-keyword">?</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">e</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">e+</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span class="z-keyword">+</span><span class="z-variable z-other">n</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> l</span><span>(</span><span class="z-variable">e</span><span>,</span><span class="z-variable">n</span><span>)</span><span>{</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> t</span><span>,</span><span class="z-variable z-other">r</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span><span class="z-keyword">++</span><span class="z-variable z-other">n</span><span>;</span><span class="z-variable z-other">r</span><span class="z-keyword">+=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">r</span><span class="z-keyword">+</span><span class="z-variable z-other">e</span><span>}</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">t</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-support z-variable">length</span><span>,</span><span class="z-keyword">++</span><span class="z-variable z-other">n</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">t</span><span>)</span><span>{</span><span class="z-keyword">for</span><span>(</span><span class="z-variable z-other">r</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">n</span><span class="z-keyword">-=</span><span class="z-variable z-other">t</span><span>;</span><span class="z-keyword">--</span><span class="z-variable z-other">n</span><span>;</span><span class="z-variable z-other">r</span><span class="z-keyword">+=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span><span class="z-variable z-other">e</span><span class="z-keyword">+=</span><span class="z-variable z-other">r</span><span>}</span><span class="z-keyword">else</span><span class="z-variable z-other"> t</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">n</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-constant">0</span><span>,</span><span class="z-variable z-other">n</span><span>)</span><span class="z-keyword">+</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">+</span><span class="z-variable z-other">e</span><span>.</span><span class="z-entity z-name">slice</span><span>(</span><span class="z-variable z-other">n</span><span>)</span><span>)</span><span>;</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span>}</span><span class="z-storage z-type">function</span><span class="z-entity z-name"> c</span><span>(</span><span class="z-variable">e</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-variable z-other"> e</span><span class="z-keyword">=</span><span class="z-entity z-name">parseFloat</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>,</span><span class="z-constant">0</span><span class="z-keyword">&gt;</span><span class="z-variable z-other">e</span><span class="z-keyword">?</span><span class="z-entity z-name">p</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span class="z-keyword">:</span><span class="z-entity z-name">d</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>}</span><span class="z-storage z-type">var</span><span class="z-variable z-other"> a</span><span>,</span><span class="z-variable z-other">h</span><span>,</span><span class="z-variable z-other">g</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">^</span><span class="z-string z-regexp">-</span><span class="z-keyword">?</span><span class="z-string z-regexp">(</span><span class="z-constant">\d</span><span class="z-keyword">+</span><span class="z-string z-regexp">(</span><span class="z-constant z-character z-escape">\.</span><span class="z-constant">\d</span><span class="z-keyword">*</span><span class="z-string z-regexp">)</span><span class="z-keyword">?</span><span class="z-keyword">|</span><span class="z-constant z-character z-escape">\.</span><span class="z-constant">\d</span><span class="z-keyword">+</span><span class="z-string z-regexp">)</span><span class="z-string z-regexp">(</span><span class="z-string z-regexp">e</span><span class="z-constant">[</span><span class="z-constant">+-</span><span class="z-constant">]</span><span class="z-keyword">?</span><span class="z-constant">\d</span><span class="z-keyword">+</span><span class="z-string z-regexp">)</span><span class="z-keyword">?</span><span class="z-keyword">$</span><span class="z-punctuation z-definition z-string">/</span><span class="z-keyword">i</span><span>,</span><span class="z-variable z-other">p</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-variable z-other">ceil</span><span>,</span><span class="z-variable z-other">d</span><span class="z-keyword">=</span><span class="z-variable z-other">Math</span><span>.</span><span class="z-variable z-other">floor</span><span>,</span><span class="z-variable z-other">m</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string"> not a boolean or binary digit</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">w</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">rounding mode</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">v</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">number type has more than 15 significant digits</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other z-constant">N</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ$_</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">b</span><span class="z-keyword">=</span><span class="z-constant">1e14</span><span>,</span><span class="z-variable z-other z-constant">O</span><span class="z-keyword">=</span><span class="z-constant">14</span><span>,</span><span class="z-variable z-other">y</span><span class="z-keyword">=</span><span class="z-constant">9007199254740991</span><span>,</span><span class="z-variable z-other z-constant">S</span><span class="z-keyword">=</span><span>[</span><span class="z-constant">1</span><span>,</span><span class="z-constant">10</span><span>,</span><span class="z-constant">100</span><span>,</span><span class="z-constant">1e3</span><span>,</span><span class="z-constant">1e4</span><span>,</span><span class="z-constant">1e5</span><span>,</span><span class="z-constant">1e6</span><span>,</span><span class="z-constant">1e7</span><span>,</span><span class="z-constant">1e8</span><span>,</span><span class="z-constant">1e9</span><span>,</span><span class="z-constant">1e10</span><span>,</span><span class="z-constant">1e11</span><span>,</span><span class="z-constant">1e12</span><span>,</span><span class="z-constant">1e13</span><span>]</span><span>,</span><span class="z-variable z-other z-constant">R</span><span class="z-keyword">=</span><span class="z-constant">1e7</span><span>,</span><span class="z-variable z-other z-constant">A</span><span class="z-keyword">=</span><span class="z-constant">1e9</span><span>;</span><span class="z-keyword">if</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">undefined</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">!=</span><span class="z-keyword">typeof</span><span class="z-variable z-other"> crypto</span><span class="z-keyword">&amp;&amp;</span><span>(</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-variable z-other">crypto</span><span>)</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">function</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">==</span><span class="z-keyword">typeof</span><span class="z-variable z-other"> define</span><span class="z-keyword">&amp;&amp;</span><span class="z-variable z-other">define</span><span>.</span><span class="z-variable z-other">amd</span><span>)</span><span class="z-entity z-name">define</span><span>(</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span><span class="z-keyword">return</span><span class="z-entity z-name"> n</span><span>(</span><span>)</span><span>}</span><span>)</span><span>;</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">undefined</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">!=</span><span class="z-keyword">typeof</span><span class="z-support"> module</span><span class="z-keyword">&amp;&amp;</span><span class="z-support">module</span><span>.</span><span class="z-support">exports</span><span>)</span><span>{</span><span class="z-keyword">if</span><span>(</span><span class="z-support">module</span><span>.</span><span class="z-support">exports</span><span class="z-keyword">=</span><span class="z-entity z-name">n</span><span>(</span><span>)</span><span>,</span><span class="z-keyword">!</span><span class="z-variable z-other">a</span><span>)</span><span class="z-keyword">try</span><span>{</span><span class="z-variable z-other">a</span><span class="z-keyword">=</span><span class="z-entity z-name">require</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">crypto</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>}</span><span class="z-keyword">catch</span><span>(</span><span class="z-variable z-other z-constant">E</span><span>)</span><span>{</span><span>}</span><span>}</span><span class="z-keyword">else</span><span class="z-variable z-other"> e</span><span class="z-keyword">||</span><span>(</span><span class="z-variable z-other">e</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">undefined</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword">!=</span><span class="z-keyword">typeof</span><span class="z-variable z-other"> self</span><span class="z-keyword">?</span><span class="z-variable z-other">self</span><span class="z-keyword">:</span><span class="z-entity z-name">Function</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">return this</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>(</span><span>)</span><span>)</span><span>,</span><span class="z-variable z-other">e</span><span>.</span><span class="z-variable z-other">BigNumber</span><span class="z-keyword">=</span><span class="z-entity z-name">n</span><span>(</span><span>)</span><span>}</span><span>(</span><span class="z-variable z-language">this</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> &lt;</span><span>/</span><span class="z-entity z-name z-tag">script</span><span>&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">style</span><span>&gt;</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> body</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> font-family</span><span>:</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">HelveticaNeue-Light</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Helvetica Neue Light</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Helvetica Neue</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Helvetica</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Arial</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Lucida Grande</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-support z-constant"> sans-serif</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> background</span><span>:</span><span class="z-constant"> #</span><span class="z-constant">E2E2E2</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> *</span><span>,</span><span class="z-entity z-name z-tag"> *</span><span class="z-entity">:</span><span class="z-entity">after</span><span>,</span><span class="z-entity z-name z-tag"> *</span><span class="z-entity">:</span><span class="z-entity">before</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> box-sizing</span><span>:</span><span class="z-support z-constant"> border-box</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> margin</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> padding</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity"> #</span><span class="z-entity">pleasewait</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> position</span><span>:</span><span class="z-support z-constant"> absolute</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> top</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> left</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> width</span><span>:</span><span class="z-constant"> 100</span><span class="z-keyword">%</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> height</span><span>:</span><span class="z-constant"> 100</span><span class="z-keyword">%</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> padding</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> margin</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity"> #</span><span class="z-entity">infomessage</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> text-align</span><span>:</span><span class="z-support z-constant"> center</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> font-size</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> margin</span><span>:</span><span class="z-constant"> 0</span><span class="z-constant"> 2</span><span class="z-keyword">rem</span><span class="z-constant"> 4.5</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity"> .</span><span class="z-entity">wrapper</span><span>{</span></span> <span class="giallo-l"><span class="z-support"> background</span><span>:</span><span class="z-constant"> #</span><span class="z-constant">E2E2E2</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> position</span><span>:</span><span class="z-support z-constant"> absolute</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> top</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> left</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> width</span><span>:</span><span class="z-constant"> 100</span><span class="z-keyword">%</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> height</span><span>:</span><span class="z-constant"> 100</span><span class="z-keyword">%</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> padding</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> margin</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> display</span><span>:</span><span class="z-support z-constant">none</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> text-align</span><span>:</span><span class="z-support z-constant"> center</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity"> .</span><span class="z-entity">title</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> text-align</span><span>:</span><span class="z-support z-constant"> center</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> font-size</span><span>:</span><span class="z-constant"> 1.2</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> margin</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">rem</span><span class="z-constant"> 0</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity"> .</span><span class="z-entity">message</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> text-align</span><span>:</span><span class="z-support z-constant"> center</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> font-size</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /*</span><span class="z-comment">margin: 0 2rem 4.5rem;</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity"> #</span><span class="z-entity">passwordField</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> text-align</span><span>:</span><span class="z-support z-constant"> center</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> font-size</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> margin</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">rem</span><span class="z-constant"> 0</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> /*</span><span class="z-comment">margin: 0 2rem 4.5rem;</span><span class="z-punctuation z-definition z-comment">*/</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity"> .</span><span class="z-entity">wrapper</span><span class="z-entity z-name z-tag"> button</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> background</span><span>:</span><span class="z-support z-constant"> transparent</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> border</span><span>:</span><span class="z-support z-constant"> none</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> color</span><span>:</span><span class="z-constant"> #</span><span class="z-constant">1678E5</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> height</span><span>:</span><span class="z-constant"> 3</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> font-size</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> width</span><span>:</span><span class="z-constant"> 50</span><span class="z-keyword">%</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> position</span><span>:</span><span class="z-support z-constant"> absolute</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> bottom</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> cursor</span><span>:</span><span class="z-support z-constant"> pointer</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity"> #</span><span class="z-entity">cancel-button</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> border-top</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">px</span><span class="z-support z-constant"> solid</span><span class="z-constant"> #</span><span class="z-constant">B4B4B4</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> border-right</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">px</span><span class="z-support z-constant"> solid</span><span class="z-constant"> #</span><span class="z-constant">B4B4B4</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> left</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> border-radius</span><span>:</span><span class="z-constant"> 0</span><span class="z-constant"> 0</span><span class="z-constant"> 0</span><span class="z-constant"> 10</span><span class="z-keyword">px</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity"> #</span><span class="z-entity">confirm-button</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> border-top</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">px</span><span class="z-support z-constant"> solid</span><span class="z-constant"> #</span><span class="z-constant">B4B4B4</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> right</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> border-radius</span><span>:</span><span class="z-constant"> 0</span><span class="z-constant"> 0</span><span class="z-constant"> 10</span><span class="z-keyword">px</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity"> .</span><span class="z-entity">wrapper</span><span class="z-entity z-name z-tag"> button</span><span class="z-entity">:</span><span class="z-entity">focus</span><span>,</span></span> <span class="giallo-l"><span class="z-entity"> .</span><span class="z-entity">wrapper</span><span class="z-entity z-name z-tag"> button</span><span class="z-entity">:</span><span class="z-entity">hover</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> font-weight</span><span>:</span><span class="z-support z-constant"> bold</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> background</span><span>:</span><span class="z-constant"> #</span><span class="z-constant">EFEFEF</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity"> .</span><span class="z-entity">wrapper</span><span class="z-entity z-name z-tag"> button</span><span class="z-entity">:</span><span class="z-entity">active</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> background</span><span>:</span><span class="z-constant"> #</span><span class="z-constant">D6D6D6</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity"> .</span><span class="z-entity">button</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> margin</span><span>:</span><span class="z-constant"> 1</span><span class="z-keyword">rem</span><span class="z-constant"> 0</span><span class="z-keyword">rem</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> display</span><span>:</span><span class="z-support z-constant"> inline-block</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> padding</span><span>:</span><span class="z-constant"> 9</span><span class="z-keyword">px</span><span class="z-constant"> 15</span><span class="z-keyword">px</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> background-color</span><span>:</span><span class="z-constant"> #</span><span class="z-constant">3898EC</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> color</span><span>:</span><span class="z-support z-constant"> white</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> border</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> line-height</span><span>:</span><span class="z-support z-constant"> inherit</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> text-decoration</span><span>:</span><span class="z-support z-constant"> none</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> cursor</span><span>:</span><span class="z-support z-constant"> pointer</span><span>;</span></span> <span class="giallo-l"><span class="z-support"> border-radius</span><span>:</span><span class="z-constant"> 0</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name z-tag"> input</span><span class="z-entity">.</span><span class="z-entity">button</span><span> {</span></span> <span class="giallo-l"><span class="z-support"> -webkit-appearance</span><span>:</span><span> button</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> &lt;</span><span>/</span><span class="z-entity z-name z-tag">style</span><span>&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">body</span><span>&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">div</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">pleasewait</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">br</span><span>/&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">p</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">infomessage</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span><span>Please wait...</span><span>&lt;/</span><span class="z-entity z-name z-tag">p</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">div</span><span>&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">form</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">form</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> class</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">wrapper</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">br</span><span>/&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">p</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">message</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> class</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">message</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span><span>&lt;/</span><span class="z-entity z-name z-tag">p</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">p</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">passwordField</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span><span>&lt;</span><span class="z-entity z-name z-tag">label</span><span>&gt;</span><span>Password Required:</span><span>&lt;/</span><span class="z-entity z-name z-tag">label</span><span>&gt;</span><span>&lt;</span><span class="z-entity z-name z-tag">input</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">password</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> type</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">password</span><span class="z-punctuation z-definition z-string">&quot;</span><span> /&gt;</span><span>&lt;/</span><span class="z-entity z-name z-tag">p</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">button</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">cancel-button</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> type</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">button</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> autofocus</span><span>&gt;</span><span>Cancel</span><span>&lt;/</span><span class="z-entity z-name z-tag">button</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">button</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">confirm-button</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> type</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">button</span><span class="z-punctuation z-definition z-string">&quot;</span><span> &gt;</span><span>Confirm</span><span>&lt;/</span><span class="z-entity z-name z-tag">button</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">form</span><span>&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">div</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">modal-dialog</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> class</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">wrapper</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">h3</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">modal-dialog-title</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> class</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">title</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span><span>Title</span><span>&lt;/</span><span class="z-entity z-name z-tag">h3</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">p</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">modal-dialog-message</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> class</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">message</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span><span>Message</span><span>&lt;/</span><span class="z-entity z-name z-tag">p</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">span</span><span class="z-entity"> id</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">modal-dialog-button</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-entity"> class</span><span>=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">button</span><span class="z-punctuation z-definition z-string">&quot;</span><span>&gt;</span><span>Ok</span><span>&lt;/</span><span class="z-entity z-name z-tag">span</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">div</span><span>&gt;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> &lt;</span><span class="z-entity z-name z-tag">script</span><span>&gt;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> noMessageReceivedYet</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> closedByCode</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> pleaseWait</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">pleasewait</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> form</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">form</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> cancelButton</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">cancel-button</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> confirmButton</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">confirm-button</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> message</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">message</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> infoMessage</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">infomessage</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> password</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">password</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> passwordField</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">passwordField</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> modalDialog</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">modal-dialog</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> modalDialogButton</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">modal-dialog-button</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> modalDialogTitle</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">modal-dialog-title</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> modalDialogMessage</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">getElementById</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">modal-dialog-message</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> firstUrl</span><span class="z-keyword"> =</span><span class="z-constant"> null</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> inIframe</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> source</span><span class="z-keyword"> =</span><span class="z-constant"> null</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">window</span><span>.</span><span class="z-variable z-other">opener</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> inIframe</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> source</span><span class="z-keyword"> =</span><span class="z-variable z-other"> window</span><span>.</span><span class="z-variable z-other">opener</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">window</span><span>.</span><span class="z-variable z-other">parent</span><span class="z-keyword"> !=</span><span class="z-variable z-other"> window</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> source</span><span class="z-keyword"> =</span><span class="z-variable z-other"> window</span><span>.</span><span class="z-variable z-other">parent</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> console</span><span>.</span><span class="z-entity z-name">log</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">closing</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> window</span><span>.</span><span class="z-entity z-name">close</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> closeWindow</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> closedByCode</span><span class="z-keyword"> =</span><span class="z-constant"> true</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> window</span><span>.</span><span class="z-entity z-name">close</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> showWaiting</span><span>(</span><span class="z-variable">text</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">text</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> text</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Please wait...</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> infoMessage</span><span>.</span><span class="z-variable z-other">innerHTML</span><span class="z-keyword"> =</span><span class="z-variable z-other"> text</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> pleaseWait</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">display</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">block</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> form</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">display</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">none</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hideWaiting</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> pleaseWait</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">display</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">none</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> form</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">display</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">block</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> window</span><span>.</span><span class="z-variable z-other">onbeforeunload</span><span class="z-keyword"> =</span><span class="z-constant"> null</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> showMessage</span><span>(</span><span class="z-variable">title</span><span>,</span><span class="z-variable"> message</span><span>,</span><span class="z-variable"> callback</span><span>,</span><span class="z-variable"> buttonText</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialog</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">display</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">block</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialogTitle</span><span>.</span><span class="z-variable z-other">innerHTML</span><span class="z-keyword"> =</span><span class="z-variable z-other"> title</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialogMessage</span><span>.</span><span class="z-variable z-other">innerHTML</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span>(</span><span class="z-keyword">typeof</span><span class="z-variable z-other"> message</span><span>)</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">string</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialogMessage</span><span>.</span><span class="z-variable z-other">innerHTML</span><span class="z-keyword"> +=</span><span class="z-variable z-other"> message</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialogMessage</span><span>.</span><span class="z-entity z-name">appendChild</span><span>(</span><span class="z-variable z-other">message</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialogMessage</span><span>.</span><span class="z-entity z-name">appendChild</span><span>(</span><span class="z-variable z-other">document</span><span>.</span><span class="z-entity z-name">createElement</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">br</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">buttonText</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> buttonText</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Ok</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialogButton</span><span>.</span><span class="z-variable z-other">innerHTML</span><span class="z-keyword"> =</span><span class="z-variable z-other"> buttonText</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialogButton</span><span>.</span><span class="z-entity z-name">onclick</span><span class="z-keyword"> =</span><span class="z-storage z-type"> function</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialogButton</span><span>.</span><span class="z-variable z-other">onclick</span><span class="z-keyword"> =</span><span class="z-constant"> null</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialog</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">display</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">none</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">callback</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> callback</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> hideMessage</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialog</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">display</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">none</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> modalDialogButton</span><span>.</span><span class="z-variable z-other">onclick</span><span class="z-keyword"> =</span><span class="z-constant"> null</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> sendAsync</span><span>(</span><span class="z-variable">url</span><span>,</span><span class="z-variable">payload</span><span>,</span><span class="z-variable"> callback</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> request</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> XMLHttpRequest</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> request</span><span>.</span><span class="z-entity z-name">open</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">POST</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-variable z-other"> url</span><span>,</span><span class="z-constant"> true</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> request</span><span>.</span><span class="z-entity z-name">setRequestHeader</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">Content-Type</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">application/json</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> request</span><span>.</span><span class="z-entity z-name">onreadystatechange</span><span class="z-keyword"> =</span><span class="z-storage z-type"> function</span><span>(</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span> (</span><span class="z-variable z-other">request</span><span>.</span><span class="z-variable z-other">readyState</span><span class="z-keyword"> ===</span><span class="z-constant"> 4</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> result</span><span class="z-keyword"> =</span><span class="z-variable z-other"> request</span><span>.</span><span class="z-variable z-other">responseText</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> error</span><span class="z-keyword"> =</span><span class="z-constant"> null</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> result</span><span class="z-keyword"> =</span><span class="z-variable z-other z-constant"> JSON</span><span>.</span><span class="z-entity z-name">parse</span><span>(</span><span class="z-variable z-other">result</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> catch</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> message</span><span class="z-keyword"> =</span><span class="z-keyword"> !</span><span class="z-keyword">!</span><span class="z-variable z-other">result</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> !</span><span class="z-keyword">!</span><span class="z-variable z-other">result</span><span>.</span><span class="z-variable z-other">error</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> !</span><span class="z-keyword">!</span><span class="z-variable z-other">result</span><span>.</span><span class="z-variable z-other">error</span><span>.</span><span class="z-variable z-other">message</span><span class="z-keyword"> ?</span><span class="z-variable z-other"> result</span><span>.</span><span class="z-variable z-other">error</span><span>.</span><span class="z-variable z-other">message</span><span class="z-keyword"> :</span><span class="z-punctuation z-definition z-string"> &#39;</span><span class="z-string">Invalid JSON RPC response: </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword"> +</span><span class="z-variable z-other z-constant"> JSON</span><span>.</span><span class="z-entity z-name">stringify</span><span>(</span><span class="z-variable z-other">result</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> error</span><span class="z-keyword"> =</span><span> {</span><span>message</span><span>:</span><span class="z-variable z-other">message</span><span>,</span><span>type</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">JsonParse</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> callback</span><span>(</span><span class="z-variable z-other">error</span><span>,</span><span class="z-variable z-other"> result</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> try</span><span> {</span></span> <span class="giallo-l"><span class="z-variable z-other"> request</span><span>.</span><span class="z-entity z-name">send</span><span>(</span><span class="z-variable z-other z-constant">JSON</span><span>.</span><span class="z-entity z-name">stringify</span><span>(</span><span class="z-variable z-other">payload</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword"> catch</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-entity z-name"> callback</span><span>(</span><span>{</span><span>message</span><span>:</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">CONNECTION ERROR: Couldn</span><span class="z-constant">\&#39;</span><span class="z-string">t connect to node </span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-keyword">+</span><span class="z-variable z-other"> url</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">.</span><span class="z-punctuation z-definition z-string">&#39;</span><span>,</span><span>type</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">noConnection</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> addBlocky</span><span>(</span><span class="z-variable">message</span><span>,</span><span class="z-variable"> address</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> icon</span><span class="z-keyword"> =</span><span class="z-variable z-other"> blockies</span><span>.</span><span class="z-entity z-name">create</span><span>(</span><span>{</span></span> <span class="giallo-l"><span> seed</span><span>:</span><span class="z-variable z-other"> address</span><span>,</span></span> <span class="giallo-l"><span> size</span><span>:</span><span class="z-constant"> 8</span><span>,</span></span> <span class="giallo-l"><span> scale</span><span>:</span><span class="z-constant"> 6</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> message</span><span>.</span><span class="z-entity z-name">appendChild</span><span>(</span><span class="z-variable z-other">icon</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> askAuthorization</span><span>(</span><span class="z-variable">transactionInfo</span><span>,</span><span class="z-variable"> data</span><span>,</span><span class="z-variable"> requireUnlock</span><span>,</span><span class="z-variable"> sourceWindow</span><span>)</span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> value</span><span class="z-keyword"> =</span><span class="z-variable z-other"> transactionInfo</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">value</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span class="z-keyword"> ?</span><span class="z-variable z-other"> transactionInfo</span><span>.</span><span class="z-variable z-other">value</span><span class="z-keyword"> :</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">0</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> gasProvided</span><span class="z-keyword"> =</span><span class="z-variable z-other"> transactionInfo</span><span>.</span><span class="z-variable z-other">gas</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> gasPriceProvided</span><span class="z-keyword"> =</span><span class="z-variable z-other"> transactionInfo</span><span>.</span><span class="z-variable z-other">gasPrice</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> gasPrice</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> BigNumber</span><span>(</span><span class="z-variable z-other">gasPriceProvided</span><span>,</span><span class="z-constant">16</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> gas</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> BigNumber</span><span>(</span><span class="z-variable z-other">gasProvided</span><span>,</span><span class="z-constant">16</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> weiValue</span><span class="z-keyword"> =</span><span class="z-keyword"> new</span><span class="z-entity z-name"> BigNumber</span><span>(</span><span class="z-variable z-other">value</span><span>,</span><span class="z-constant">16</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> gasWeiValue</span><span class="z-keyword"> =</span><span class="z-variable z-other"> gas</span><span>.</span><span class="z-entity z-name">times</span><span>(</span><span class="z-variable z-other">gasPrice</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> etherValue</span><span class="z-keyword"> =</span><span class="z-variable z-other"> weiValue</span><span>.</span><span class="z-entity z-name">dividedBy</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> BigNumber</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> gasEtherValue</span><span class="z-keyword"> =</span><span class="z-variable z-other"> gasWeiValue</span><span>.</span><span class="z-entity z-name">dividedBy</span><span>(</span><span class="z-keyword">new</span><span class="z-entity z-name"> BigNumber</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">1000000000000000000</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> hideWaiting</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> message</span><span>.</span><span class="z-variable z-other">innerHTML</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> addBlocky</span><span>(</span><span class="z-variable z-other">message</span><span>,</span><span class="z-variable z-other">transactionInfo</span><span>.</span><span class="z-variable z-other">from</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> span</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">createElement</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">span</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> span</span><span>.</span><span class="z-variable z-other">style</span><span class="z-keyword">=</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">font-size:3em;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> span</span><span>.</span><span class="z-variable z-other">innerHTML</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&amp;nbsp;&amp;nbsp;&amp;nbsp;</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&amp;#x2192;</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">&amp;nbsp;&amp;nbsp;&amp;nbsp;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> message</span><span>.</span><span class="z-entity z-name">appendChild</span><span>(</span><span class="z-variable z-other">span</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> addBlocky</span><span>(</span><span class="z-variable z-other">message</span><span>,</span><span class="z-variable z-other">transactionInfo</span><span>.</span><span class="z-variable z-other">to</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> message</span><span>.</span><span class="z-entity z-name">appendChild</span><span>(</span><span class="z-variable z-other">document</span><span>.</span><span class="z-entity z-name">createElement</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">br</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> textSpan</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">createElement</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">span</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> message</span><span>.</span><span class="z-entity z-name">appendChild</span><span>(</span><span class="z-variable z-other">textSpan</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> textSpan</span><span>.</span><span class="z-variable z-other">innerHTML</span><span class="z-keyword"> =</span><span class="z-variable z-other"> etherValue</span><span>.</span><span class="z-entity z-name">toFormat</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string"> ether &lt;br/&gt; + gas cost (</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span class="z-variable z-other"> gasEtherValue</span><span>.</span><span class="z-entity z-name">toFormat</span><span>(</span><span>)</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string"> ether )</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">requireUnlock</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> passwordField</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">display</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">block</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> passwordField</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">display</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">none</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> cancelButton</span><span>.</span><span class="z-entity z-name">onclick</span><span class="z-keyword"> =</span><span class="z-storage z-type"> function</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> sourceWindow</span><span>.</span><span class="z-entity z-name">postMessage</span><span>(</span><span>{</span><span>id</span><span>:</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">id</span><span>,</span><span>result</span><span>:</span><span class="z-constant">null</span><span>,</span><span>error</span><span>:</span><span>{</span><span>message</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Not Authorized</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span>type</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">cancel</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span class="z-variable z-other">firstUrl</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> closeWindow</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-entity z-name"> submitFunc</span><span class="z-keyword"> =</span><span class="z-storage z-type"> function</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> window</span><span>.</span><span class="z-entity z-name">onbeforeunload</span><span class="z-keyword"> =</span><span class="z-storage z-type"> function</span><span> (</span><span class="z-variable">event</span><span>)</span><span> {</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">closedByCode</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">do not close now as a transaction is progress, this cannot be canceled and we wait for an answer</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">requireUnlock</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">password</span><span>.</span><span class="z-variable z-other">value</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> password</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">border</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">2px solid red</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-variable z-other"> password</span><span>.</span><span class="z-variable z-other">style</span><span>.</span><span class="z-variable z-other">border</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">none</span><span class="z-punctuation z-definition z-string">&quot;</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> params</span><span class="z-keyword"> =</span><span> [</span><span class="z-variable z-other">transactionInfo</span><span>.</span><span class="z-variable z-other">from</span><span>,</span><span class="z-variable z-other">password</span><span>.</span><span class="z-variable z-other">value</span><span>,</span><span class="z-constant">3</span><span>]</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> showWaiting</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Please wait...&lt;br/&gt;Do not close the window.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> sendAsync</span><span>(</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">url</span><span>,</span><span>{</span><span>id</span><span>:</span><span class="z-constant">999992</span><span>,</span><span>method</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">personal_unlockAccount</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span>params</span><span>:</span><span class="z-variable z-other">params</span><span>}</span><span>,</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">error</span><span>,</span><span class="z-variable">result</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">error</span><span class="z-keyword"> ||</span><span class="z-variable z-other"> result</span><span>.</span><span class="z-variable z-other">error</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> showMessage</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Error unlocking account</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Please retry.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> hideWaiting</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> sendAsync</span><span>(</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">url</span><span>,</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">payload</span><span>,</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">error</span><span>,</span><span class="z-variable">result</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> sourceWindow</span><span>.</span><span class="z-entity z-name">postMessage</span><span>(</span><span>{</span><span>id</span><span>:</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">id</span><span>,</span><span>result</span><span>:</span><span class="z-variable z-other">result</span><span>,</span><span>error</span><span>:</span><span class="z-variable z-other">error</span><span>}</span><span>,</span><span class="z-variable z-other">firstUrl</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> closeWindow</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> sendAsync</span><span>(</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">url</span><span>,</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">payload</span><span>,</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">error</span><span>,</span><span class="z-variable">result</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">result</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> result</span><span>.</span><span class="z-variable z-other">error</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> processMessage</span><span>(</span><span class="z-variable z-other">data</span><span>,</span><span class="z-variable z-other">sourceWindow</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> sourceWindow</span><span>.</span><span class="z-entity z-name">postMessage</span><span>(</span><span>{</span><span>id</span><span>:</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">id</span><span>,</span><span>result</span><span>:</span><span class="z-variable z-other">result</span><span>,</span><span>error</span><span>:</span><span class="z-variable z-other">error</span><span>}</span><span>,</span><span class="z-variable z-other">firstUrl</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> closeWindow</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> showWaiting</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> form</span><span>.</span><span class="z-variable z-other">onsubmit</span><span class="z-keyword"> =</span><span class="z-variable z-other"> submitFunc</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> confirmButton</span><span>.</span><span class="z-variable z-other">onclick</span><span class="z-keyword"> =</span><span class="z-variable z-other"> submitFunc</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> needToAndCanUnlockAccount</span><span>(</span><span class="z-variable">address</span><span>,</span><span class="z-variable">url</span><span>,</span><span class="z-variable">callback</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> sendAsync</span><span>(</span><span class="z-variable z-other">url</span><span>,</span><span>{</span><span>id</span><span>:</span><span class="z-constant">9999990</span><span>,</span><span>method</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_sign</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span>params</span><span>:</span><span>[</span><span class="z-variable z-other">address</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">0xc6888fa8d57087278718986382264244252f8d57087278718986382264244252f</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>}</span><span>,</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">error</span><span>,</span><span class="z-variable">result</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">error</span><span class="z-keyword"> ||</span><span class="z-variable z-other"> result</span><span>.</span><span class="z-variable z-other">error</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> sendAsync</span><span>(</span><span class="z-variable z-other">url</span><span>,</span><span>{</span><span>id</span><span>:</span><span class="z-constant">9999991</span><span>,</span><span>method</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">personal_listAccounts</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span>params</span><span>:</span><span>[</span><span>]</span><span>}</span><span>,</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">error</span><span>,</span><span class="z-variable">result</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">error</span><span class="z-keyword"> ||</span><span class="z-variable z-other"> result</span><span>.</span><span class="z-variable z-other">error</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> callback</span><span>(</span><span class="z-constant">true</span><span>,</span><span class="z-constant">false</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> callback</span><span>(</span><span class="z-constant">true</span><span>,</span><span class="z-constant">true</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> callback</span><span>(</span><span class="z-constant">false</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> receiveMessage</span><span>(</span><span class="z-variable">event</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">event</span><span>.</span><span class="z-variable z-other">source</span><span class="z-keyword"> !=</span><span class="z-variable z-other"> source</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">firstUrl</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">firstUrl</span><span class="z-keyword"> !=</span><span class="z-variable z-other"> event</span><span>.</span><span class="z-variable z-other">origin</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> firstUrl</span><span class="z-keyword"> =</span><span class="z-variable z-other"> event</span><span>.</span><span class="z-variable z-other">origin</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> hideMessage</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> noMessageReceivedYet</span><span class="z-keyword"> =</span><span class="z-constant"> false</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> data</span><span class="z-keyword"> =</span><span class="z-variable z-other"> event</span><span>.</span><span class="z-variable z-other">data</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> try</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> processMessage</span><span>(</span><span class="z-variable z-other">data</span><span>,</span><span class="z-variable z-other">event</span><span>.</span><span class="z-variable z-other">source</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">catch</span><span>(</span><span class="z-variable z-other">e</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> event</span><span>.</span><span class="z-variable z-other">source</span><span>.</span><span class="z-entity z-name">postMessage</span><span>(</span><span>{</span><span>id</span><span>:</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">id</span><span>,</span><span>result</span><span>:</span><span class="z-constant">null</span><span>,</span><span>error</span><span>:</span><span>{</span><span>message</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Could not process message data</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span>type</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">notValid</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span class="z-variable z-other">firstUrl</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> showMessage</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Error</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">The application has sent invalid data</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage z-type"> function</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> closeWindow</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> allowedMethods</span><span class="z-keyword"> =</span><span> [</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">web3_clientVersion</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">web3_sha3</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">net_version</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">net_peerCount</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">net_listening</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_protocolVersion</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_syncing</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_coinbase</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_mining</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_hashrate</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_gasPrice</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_accounts</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_blockNumber</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getBalance</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getStorageAt</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getTransactionCount</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getBlockTransactionCountByHash</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getBlockTransactionCountByNumber</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getUncleCountByBlockHash</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getUncleCountByBlockNumber</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getCode</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_sendRawTransaction</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_call</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_estimateGas</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getBlockByHash</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getBlockByNumber</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getTransactionByHash</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getTransactionByBlockHashAndIndex</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getTransactionByBlockNumberAndIndex</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getTransactionReceipt</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getUncleByBlockHashAndIndex</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getUncleByBlockNumberAndIndex</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getCompilers</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_compileLLL</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_compileSolidity</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_compileSerpent</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_newFilter</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_newBlockFilter</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_newPendingTransactionFilter</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_uninstallFilter</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getFilterChanges</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getFilterLogs</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getLogs</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_getWork</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_submitWork</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span> ,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">eth_submitHashrate</span><span class="z-punctuation z-definition z-string">&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_post&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_version&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_newIdentity&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_hasIdentity&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_newGroup&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_addToGroup&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_newFilter&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_uninstallFilter&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_getFilterChanges&quot;</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment"> //</span><span class="z-comment"> ,&quot;shh_getMessages&quot;</span></span> <span class="giallo-l"><span> ]</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> isMethodAllowed</span><span>(</span><span class="z-variable">method</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> return</span><span class="z-variable z-other"> allowedMethods</span><span>.</span><span class="z-entity z-name">indexOf</span><span>(</span><span class="z-variable z-other">method</span><span>)</span><span class="z-keyword"> !=</span><span class="z-keyword"> -</span><span class="z-constant">1</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> processMessage</span><span>(</span><span class="z-variable">data</span><span>,</span><span class="z-variable"> sourceWindow</span><span>)</span><span>{</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">inIframe</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-entity z-name">isMethodAllowed</span><span>(</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">method</span><span>)</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> sendAsync</span><span>(</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">url</span><span>,</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">payload</span><span>,</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">error</span><span>,</span><span class="z-variable">result</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> sourceWindow</span><span>.</span><span class="z-entity z-name">postMessage</span><span>(</span><span>{</span><span>id</span><span>:</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">id</span><span>,</span><span>result</span><span>:</span><span class="z-variable z-other">result</span><span>,</span><span>error</span><span>:</span><span class="z-variable z-other">error</span><span>}</span><span>,</span><span class="z-variable z-other">firstUrl</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> sourceWindow</span><span>.</span><span class="z-entity z-name">postMessage</span><span>(</span><span>{</span><span>id</span><span>:</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">id</span><span>,</span><span>result</span><span>:</span><span class="z-constant">null</span><span>,</span><span>error</span><span>:</span><span>{</span><span>message</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">method (</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span class="z-variable z-other"> data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">method</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">) not allowed in iframe</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span>type</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">notAllowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span class="z-variable z-other">firstUrl</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">method</span><span class="z-keyword"> ==</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">eth_sendTransaction</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> transactionInfo</span><span class="z-keyword"> =</span><span class="z-constant"> null</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">params</span><span>.</span><span class="z-support z-variable">length</span><span class="z-keyword"> &gt;</span><span class="z-constant"> 0</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">params</span><span>[</span><span class="z-constant">0</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">gas</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">params</span><span>[</span><span class="z-constant">0</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">gasPrice</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">params</span><span>[</span><span class="z-constant">0</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">to</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">params</span><span>[</span><span class="z-constant">0</span><span>]</span><span>[</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">from</span><span class="z-punctuation z-definition z-string">&quot;</span><span>]</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> transactionInfo</span><span class="z-keyword"> =</span><span class="z-variable z-other"> data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">params</span><span>[</span><span class="z-constant">0</span><span>]</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">transactionInfo</span><span class="z-keyword"> !=</span><span class="z-constant"> null</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> needToAndCanUnlockAccount</span><span>(</span><span class="z-variable z-other">transactionInfo</span><span>.</span><span class="z-variable z-other">from</span><span>,</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">url</span><span>,</span><span class="z-storage z-type">function</span><span>(</span><span class="z-variable">requireUnlock</span><span>,</span><span class="z-variable">canUnlock</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">requireUnlock</span><span class="z-keyword"> &amp;&amp;</span><span class="z-variable z-other"> canUnlock</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> askAuthorization</span><span>(</span><span class="z-variable z-other">transactionInfo</span><span>,</span><span class="z-variable z-other">data</span><span>,</span><span class="z-constant">true</span><span>,</span><span class="z-variable z-other"> sourceWindow</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-keyword">!</span><span class="z-variable z-other">requireUnlock</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> askAuthorization</span><span>(</span><span class="z-variable z-other">transactionInfo</span><span>,</span><span class="z-variable z-other">data</span><span>,</span><span class="z-constant">false</span><span>,</span><span class="z-variable z-other">sourceWindow</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">requireUnlock</span><span class="z-keyword"> &amp;&amp;</span><span class="z-keyword"> !</span><span class="z-variable z-other">canUnlock</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> messageHtml</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">createElement</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">span</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> addBlocky</span><span>(</span><span class="z-variable z-other">messageHtml</span><span>,</span><span class="z-variable z-other">transactionInfo</span><span>.</span><span class="z-variable z-other">from</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> messageHtml</span><span>.</span><span class="z-entity z-name">appendChild</span><span>(</span><span class="z-variable z-other">document</span><span>.</span><span class="z-entity z-name">createElement</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">br</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-storage z-type"> var</span><span class="z-variable z-other"> span</span><span class="z-keyword"> =</span><span class="z-variable z-other"> document</span><span>.</span><span class="z-entity z-name">createElement</span><span>(</span><span class="z-punctuation z-definition z-string">&#39;</span><span class="z-string">span</span><span class="z-punctuation z-definition z-string">&#39;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> span</span><span>.</span><span class="z-variable z-other">innerHTML</span><span class="z-keyword"> =</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">You need to unlock your account first : &lt;br/&gt;</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span class="z-variable z-other"> transactionInfo</span><span>.</span><span class="z-variable z-other">from</span><span>;</span></span> <span class="giallo-l"><span class="z-variable z-other"> messageHtml</span><span>.</span><span class="z-entity z-name">appendChild</span><span>(</span><span class="z-variable z-other">span</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-entity z-name"> showMessage</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Account Locked</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other">messageHtml</span><span>,</span><span class="z-storage z-type">function</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> processMessage</span><span>(</span><span class="z-variable z-other">data</span><span>,</span><span class="z-variable z-other">sourceWindow</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>,</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">Done</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> sourceWindow</span><span>.</span><span class="z-entity z-name">postMessage</span><span>(</span><span>{</span><span>id</span><span>:</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">id</span><span>,</span><span>result</span><span>:</span><span class="z-constant">null</span><span>,</span><span>error</span><span>:</span><span>{</span><span>message</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Need to specify from , to, gas and gasPrice</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span>type</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">notValid</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span class="z-variable z-other">firstUrl</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-entity z-name"> closeWindow</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span><span class="z-keyword">else</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> sourceWindow</span><span>.</span><span class="z-entity z-name">postMessage</span><span>(</span><span>{</span><span>id</span><span>:</span><span class="z-variable z-other">data</span><span>.</span><span class="z-variable z-other">id</span><span>,</span><span>result</span><span>:</span><span class="z-constant">null</span><span>,</span><span>error</span><span>:</span><span>{</span><span>message</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">method (</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-keyword"> +</span><span class="z-variable z-other"> data</span><span>.</span><span class="z-variable z-other">payload</span><span>.</span><span class="z-variable z-other">method</span><span class="z-keyword"> +</span><span class="z-punctuation z-definition z-string"> &quot;</span><span class="z-string">) not allowed in popup</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span>type</span><span>:</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">notAllowed</span><span class="z-punctuation z-definition z-string">&quot;</span><span>}</span><span>,</span><span class="z-variable z-other">firstUrl</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span> </span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-storage z-type"> function</span><span class="z-entity z-name"> checkMessageNotReceived</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">noMessageReceivedYet</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> showMessage</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">Error</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">No transaction received. Please make sure popup are not blocked.</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-storage z-type"> function</span><span>(</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-entity z-name"> closeWindow</span><span>(</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"><span class="z-entity z-name"> setTimeout</span><span>(</span><span class="z-variable z-other">checkMessageNotReceived</span><span>,</span><span class="z-constant">1000</span><span>)</span><span>;</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-variable z-other"> window</span><span>.</span><span class="z-entity z-name">addEventListener</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">message</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-variable z-other"> receiveMessage</span><span>)</span><span>;</span></span> <span class="giallo-l"><span class="z-keyword"> if</span><span>(</span><span class="z-variable z-other">source</span><span>)</span><span>{</span></span> <span class="giallo-l"><span class="z-variable z-other"> source</span><span>.</span><span class="z-entity z-name">postMessage</span><span>(</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">ready</span><span class="z-punctuation z-definition z-string">&quot;</span><span>,</span><span class="z-punctuation z-definition z-string">&quot;</span><span class="z-string">*</span><span class="z-punctuation z-definition z-string">&quot;</span><span>)</span><span>;</span></span> <span class="giallo-l"><span> }</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span> &lt;</span><span>/</span><span class="z-entity z-name z-tag">script</span><span>&gt;</span></span> <span class="giallo-l"><span> &lt;/</span><span class="z-entity z-name z-tag">body</span><span>&gt;</span></span> <span class="giallo-l"><span>&lt;/</span><span class="z-entity z-name z-tag">html</span><span>&gt;</span></span></code></pre><h2 id="copyright">Copyright</h2> <p>Copyright and related rights waived via <a href="https://wg-eips.ritovision.com/license/">CC0</a>.</p> 2015-11-15T00:00:00+00:00 2026-02-11T14:49:27+00:00 Vitalik Buterinhttps://github.com/vbuterin https://wg-eips.ritovision.com/101/ <h3 id="specification">Specification</h3> <ol> <li>Accounts now have only two fields in their RLP encoding: <strong>code</strong> and <strong>storage</strong>.</li> <li>Ether is no longer stored in account objects directly; instead, at address <code>0</code>, we premine a contract which contains all ether holdings. The <code>eth.getBalance</code> command in web3 is remapped appropriately.</li> <li><code>msg.value</code> no longer exists as an opcode.</li> <li>A transaction now only has four fields: <strong>to</strong>, <strong>startgas</strong>, <strong>data</strong> and <strong>code</strong>.</li> <li>Aside from an RLP validity check, and checking that the <strong>to</strong> field is twenty bytes long, the <strong>startgas</strong> is an integer, and <strong>code</strong> is either empty or hashes to the <strong>to</strong> address, there are no other validity constraints; anything goes. However, the block gas limit remains, so miners are disincentivized from including junk.</li> <li>Gas is charged for bytes in <strong>code</strong> at the same rate as <strong>data</strong>.</li> <li>When a transaction is sent, if the receiving account does not yet exist, the account is created, and its code is set to the code provided in the transaction; otherwise the code is ignored.</li> <li>A <code>tx.gas</code> opcode is added alongside the existing <code>msg.gas</code> at index <code>0x5c</code>; this new opcode allows the transaction to access the original amount of gas allotted for the transaction</li> </ol> <p>Note that <code>ECRECOVER</code>, sequence number/nonce incrementing and ether are now nowhere in the bottom-level spec (NOTE: ether is going to continue to have a privileged role in Casper PoS). To replicate existing functionality under the new model, we do the following.</p> <p>Simple user accounts can have the following default standardized code:</p> <pre class="giallo z-code"><code data-lang="python"><span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> We assume that data takes the following schema:</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> bytes 0-31: v (ECDSA sig)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> bytes 32-63: r (ECDSA sig)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> bytes 64-95: s (ECDSA sig)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> bytes 96-127: sequence number (formerly called &quot;nonce&quot;)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> bytes 128-159: gasprice</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> bytes 172-191: to</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> bytes 192+: data</span></span> <span class="giallo-l"></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Get the hash for transaction signing</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>mstore</span><span>(</span><span class="z-constant">0</span><span>,</span><span> msg</span><span>.</span><span>gas</span><span>)</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>calldatacopy</span><span>(</span><span class="z-constant">32</span><span>,</span><span class="z-constant"> 96</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 96</span><span>)</span></span> <span class="giallo-l"><span>h</span><span class="z-keyword"> =</span><span> sha3</span><span>(</span><span class="z-constant">96</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 96</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Call ECRECOVER contract to get the sender</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>call</span><span>(</span><span class="z-constant">5000</span><span>,</span><span class="z-constant"> 3</span><span>,</span><span> [</span><span>h</span><span>,</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">0</span><span>)</span><span>,</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">32</span><span>)</span><span>,</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">64</span><span>)</span><span>]</span><span>,</span><span class="z-constant"> 128</span><span>,</span><span> ref</span><span>(</span><span>addr</span><span>)</span><span>,</span><span class="z-constant"> 32</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Check sender correctness</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span> addr</span><span class="z-keyword"> ==</span><span class="z-storage z-type"> 0x</span><span class="z-constant">82a978b3f5962a5b0957d9ee9eef472ee55b42f1</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Check sequence number correctness</span></span> <span class="giallo-l"><span class="z-keyword">assert</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">96</span><span>)</span><span class="z-keyword"> ==</span><span class="z-variable z-language"> self</span><span>.</span><span>storage</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Increment sequence number</span></span> <span class="giallo-l"><span class="z-variable z-language">self</span><span>.</span><span>storage</span><span>[</span><span class="z-keyword">-</span><span class="z-constant">1</span><span>]</span><span class="z-keyword"> +=</span><span class="z-constant"> 1</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Make the sub-call and discard output</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>call</span><span>(</span><span>msg</span><span>.</span><span>gas</span><span class="z-keyword"> -</span><span class="z-constant"> 50000</span><span>,</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">160</span><span>)</span><span>,</span><span class="z-constant"> 192</span><span>,</span><span class="z-keyword"> ~</span><span>calldatasize</span><span>(</span><span>)</span><span class="z-keyword"> -</span><span class="z-constant"> 192</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span> <span class="giallo-l"><span class="z-punctuation z-definition z-comment">#</span><span class="z-comment"> Pay for gas</span></span> <span class="giallo-l"><span class="z-keyword">~</span><span>call</span><span>(</span><span class="z-constant">40000</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span> [</span><span class="z-constant">SEND</span><span>,</span><span> block</span><span>.</span><span>coinbase</span><span>,</span><span class="z-keyword"> ~</span><span>calldataload</span><span>(</span><span class="z-constant">128</span><span>)</span><span class="z-keyword"> *</span><span> (</span><span>tx</span><span>.</span><span>gas</span><span class="z-keyword"> -</span><span> msg</span><span>.</span><span>gas</span><span class="z-keyword"> +</span><span class="z-constant"> 50000</span><span>)</span><span>]</span><span>,</span><span class="z-constant"> 96</span><span>,</span><span class="z-constant"> 0</span><span>,</span><span class="z-constant"> 0</span><span>)</span></span></code></pre> <p>This essentially implements signature and nonce checking, and if both checks pass then it uses all remaining gas minus 50000 to send the actual desired call, and then finally pays for gas.</p> <p>Miners can follow the following algorithm upon receiving transactions:</p> <ol> <li>Run the code for a maximum of 50000 gas, stopping if they see an operation or call that threatens to go over this limit</li> <li>Upon seeing that operation, make sure that it leaves at least 50000 gas to spare (either by checking that the static gas consumption is small enough or by checking that it is a call with <code>msg.gas - 50000</code> as its gas limit parameter)</li> <li>Pattern-match to make sure that gas payment code at the end is <em>exactly</em> the same as in the code above.</li> </ol> <p>This process ensures that miners <em>waste</em> at most 50000 gas before knowing whether or not it will be worth their while to include the transaction, and is also highly general so users can experiment with new cryptography (eg. ed25519, Lamport), ring signatures, quasi-native multisig, etc. Theoretically, one can even create an account for which the <em>valid signature</em> type is a valid Merkle branch of a receipt, creating a quasi-native alarm clock.</p> <p>If someone wants to send a transaction with nonzero value, instead of the current <code>msg.sender</code> approach, we compile into a three step process:</p> <ol> <li>In the outer scope just before calling, call the ether contract to create a cheque for the desired amount</li> <li>In the inner scope, if a contract uses the <code>msg.value</code> opcode anywhere in the function that is being called, then we have the contract cash out the cheque at the start of the function call and store the amount cashed out in a standardized address in memory</li> <li>In the outer scope just after calling, send a message to the ether contract to disable the cheque if it has not yet been cashed</li> </ol> <h3 id="rationale">Rationale</h3> <p>This allows for a large increase in generality, particularly in a few areas:</p> <ol> <li>Cryptographic algorithms used to secure accounts (we could reasonably say that Ethereum is quantum-safe, as one is perfectly free to secure one's account with Lamport signatures). The nonce-incrementing approach is now also open to revision on the part of account holders, allowing for experimentation in k-parallelizable nonce techniques, UTXO schemes, etc.</li> <li>Moving ether up a level of abstraction, with the particular benefit of allowing ether and sub-tokens to be treated similarly by contracts</li> <li>Reducing the level of indirection required for custom-policy accounts such as multisigs</li> </ol> <p>It also substantially simplifies and <em>purifies</em> the underlying Ethereum protocol, reducing the minimal consensus implementation complexity.</p> <h3 id="implementation">Implementation</h3> <p>Coming soon.</p>